Requirements for creating a Catalog of sources, and ingesting it into the MSA Planning Tool are presented in this article. Candidate sets are also introduced. 

The MSA Planning Tool (MPT) is used for planning MSA Configurations to observe a set of sources distributed across the MSA aperture projected on the sky.  The tool requires the ingest of a catalog of source centers in order to run. Even for proposers waiting for NIRCam or other pre-imaging for accurate source positions, an input catalog is needed. Users waiting for pre-imaging should create a fake catalog with similar areal coverage and density to design their MOS proposals in MPT.

Optimal MOS spectral calibration for aperture flux loss and wavelength solutions will require Catalog measurements with high-precision relative astrometry from an existing image. The MOS mode observations can be planned using astrometry with accuracies from 5–50 mas. High precision spectral calibration needs relative positional accuracy of 15 milliarcsec or less, which typically requires space-based observations. Images obtained using HST/ACS or HST/WFC3 UVIS within the past 10 years should have this level of accuracy. In some cases, the planning of the NIRSpec spectroscopy will require prior NIRCam observations, a process that is called NIRCam pre-imaging. Nonetheless, while high-precision relative astrometry is highly recommended, it is not a requirement.

---

Creating a source Catalog

See Also: NIRSpec MOS and MSATA Observing Process, MPT Catalogs - Examples, NIRSpec MSA Target Acquisition, NIRSPEC MPT - MOS and MSATA Program Updates

Parent source Catalogs can have as many objects as needed. It is recommended that Catalogs include all known sources in the field in order for the user to spot contaminants and prevent the MPT from placing them into failed-open shutters. The MPT Catalogs - Examples article presents several examples to guide the user on Catalog formatting. Tables can be delineated by whitespaces, tabs, or commas. Virtual Observatory tables are also supported. For flight-ready program updates (but not proposals), the Catalog must also include reference stars for MSA target acquisition. Some useful information about updating the source Catalog for the MOS program update submission are presented in the next section.

Parent source Catalogs must be created with these simple rules in mind:

• Two columns are required for the equatorial celestial coordinates (J2000) RA and Dec for each source. These can be expressed in units of degrees or in hexadecimal format. 
• It is useful to associate each source position with an integer ID in the first column of the Catalog. The ID should be an integer value from 1 up to 1e6 (1,000,000). The ID will be encoded into the name of the Level 3 output products from the pipeline,
• It may be useful for at least one column to have source fluxes or magnitudes (optional).
• Optionally include a column called Stellarity with a value from 0 to 1 for increasingly point-like sources. Use a value of -1 for unknown source stellarity. This will be used by the pipeline for processing the sources. Default processing is for point-like objects.
• The Catalog may optionally contain a header line at the top of the file indicating column names separated by whitespace. The header line must begin with a "#".  
• Using recognized labels will assist ingest and filtering of the Catalog when making subset lists called Candidate Sets. Some recognized labels are ID, RA, DEC, Size, Redshift, Reference, Stellarity, Magnitude, Magnitude error, R50, Number, Label, Weight, and FWHM. Most of these are optional columns.
  
• The Catalogue must have a radial extent from its center position of less than 1 degree. APT will provide a warning message if the catalogue is larger than 1 degree. 

 

Cautionary advice concerning MOS Catalogs during program development

---

Updating a source Catalog with candidate reference stars for the MOS program update

See Also: NIRSpec MPT - MOS and MSATA Program Updates, NIRSpec MOS and MSATA Observing Process

Observers will generally need to update their source Catalog before submitting the initial MOS program update. This is especially true when NIRCam pre-imaging has been requested. In that case, actual source positions may have improved, and there will likely be new sources to add to the Catalog. Even for programs without NIRCam pre-imaging observations for which no changes are needed to sources or their positions, the Catalog will still need to be updated to mark suitable candidates for reference stars if using MSATA. A more detailed discussion of Catalog updates for preparing the MOS program update can be  found in the article on NIRSpec MPT - MOS and MSATA Program Updates.

---

Ingesting a source Catalog

How to ingest the source Catalog in APT

To start, the Catalog should be ingested into APT from the Targets folder (Make sure you are in the Form Editor). The button "Import MSA Source Catalog", highlighted in Figure 1, can be used to create an MSA Catalog Target.

A pop-up window labeled the MSA Source Importer will then appear for loading the Catalog, as shown in Figure 2. Several formats are allowed for the Catalog: CSV - Comma-Separated Values, TSV - Tab-Separated Values, Whitespace Separated, or VOT - Virtual Observatory Table format. Select the appropriate format under File Format. Give the Catalog a Catalog Name. The name should be from 2–31 characters, and only letters, numbers and "+", or "-" are allowed. Underscores are not allowed. The name should not have spaces. 

Defining the working set of columns

If the File Format has been selected properly in the MSA Source Importer, MPT will attempt to automatically label the columns (Figure 3) with the help of the file header. Users should correct the labels using the pull-down menu located below each column. A number of common options are available: ID, RA, Dec, Magnitude, Magnitude Error, Redshift, FWHM, R50, Weight, Reference, Stellarity, Number, and Label. Unrecognized columns will have the default label Ignore. All columns with the label Ignore will not be read into MPT.  If you plan to use a column in MPT for making a filtered Candidate List, and it does not appear in the list shown, select Number if it contains numerical data, or Label if it has alpha-numeric values. If the Catalog has many columns that you don't need for planning, then it is convenient to leave them labelled as Ignore.

Important caveats

 Since Candidate Lists created by filtering the parent Catalog in APTwill normally be used to create MPT Plans, it is important to ingest the data carefully at the start, so the essential columns become available for later filtering.

Once the Catalog is ingested, selecting or highlighting it will display the data. Figure 4 shows how the sources in a Catalog are displayed when the Catalog is highlighted within the main window of the GUI.

Scrollbars are present on the right and at the bottom to help navigate the Catalog. The Catalog may be sorted (in display mode only) by clicking on any column name. Columns may be reordered by dragging and dropping. The Catalog will maintain its initial ordering for making an observation plan.

---

Exporting a Catalog

An MSA Catalog can be exported from APT.  To do so, select File from the APT menu bar at the top of your screen, then select Export, then select Export MSA Catalogs [.csv].  You will be requested to specify the destination directory.  The catalog will be exported with the same name as used in APT to the destination directory in csv format.  If running APT from the command line, adding the parameter "-export msacatalogs" will also export the catalog.

---

Catalog properties

Source ID

The source ID is an optional column. The ID is read as an int. 

Source weights

Weights may optionally be used to create the MPT Plans. In the absence of source weights, MPT will prioritize sources based on the ordering of the sources in the Primary candidate set (which is derived from their order in the Catalog), described below. If some sources in your Catalog have a higher priority than others, then it is recommended to create an additional column called Weight in the Catalog and assign higher values for the weights to those sources. When this Catalog is ingested, assign the weight column as a Weight column type. If the use of source weights is enabled in the Planner, sources with larger weights are more likely to be observed. MPT will use the weights in the Catalog in a linear way.  For example, a source with a weight of 100 will count as much as 100 sources with a weight of 1 when the tool is attempting to optimize the MSA Configuration. If the Catalog does not have a weight column, MPT will assign the weight 1 to all sources. Weights up to a very large maximum value will be read correctly. However, to avoid problems with MPT selecting the best pointing using summed Weights, it's recommended to use a more conservative maximum value of 1e9 in practice.

Astrometric accuracy

A catalog relative Astrometric Accuracy in units of milliarcseconds must be specified after Catalog ingest. If a Catalog comes from, for example, an HST/WFC3/UVIS observation, one may assign the value 12–15 milliarcseconds. This value is used to estimate the final accuracy of the target acquisition when using the MSA target acquisition (MSATA) method.

Important Recommendation - Register catalog to Gaia DR3

Catalog Reference Position

The Catalog Reference Position is the reference point for the MOS observations that will use this Catalog. This position is automatically calculated by APT as a median of the Catalog source RA and Dec values, and is not editable.

Pre-image Availability

NIRSpec MSA observations will require the most accurate relative astrometry in order to place sources in the micro shutters. For this reason, the MPT asks for the Pre-image Availability which has the options and consequences listed in Table 1. This mechanism is used as a way to alert the ground system that there may be an associated observation that will need to be linked to the MOS observations for planning and scheduling. If the option Will be done in this program is selected, APT will ask the user to select the appropriate NIRCam observation in the program. The selection Is already obtained  indicates that there is an existing image in the archive or elsewhere that is associated with the source positions in the Catalog. The reference image in that case will be uploaded by the user with the program update submission and stored in the archive for later archival observers. This reference image is a snapshot of the imaging used at the time of planning the MOS observation, and will correspond to the positions used to create the pipeline source products.

Table 1. Description of the pre-imaging availability options

Pre-image upload options during program development

Observers are asked to provide any pre-imaging they have used (or will use) to derive Catalog positions for upload in APT at the time of MOS program update submission. Observers can indicate their intent to provide pre-imaging when it is available during proposal submission. For those MOS programs that have selected the option Is already available (see Table 1), observers will be expected to upload the imaging to MAST via APT so that it can be associated with the derived observed MOS sources in MAST. Associated imaging will be extremely useful for future archival researchers, and may also serve to streamline observation planning for the observing teams. The pre-image, once uploaded, is proprietary until the end of the proprietary period of the program, normally one year. The pre-image, once uploaded, can only be accessed by the PI or their designee during the proprietary period.

APT will present different options at each stage of proposal development.  

(1) In the initial proposal submission, the user ingests an MSA Catalog into the Targets folder in APT.  During the ingest, the observer is asked to select an option for any pre-imaging availability associated with the Catalog (See Table 1 above).  Figure 4 above shows what it looks like in APT prior to program acceptance.

(2) Once the proposal moves to approved status, observers will see a new button on the MSA Catalog Target for selection of the pre-image FITS file on disk, with a red X to indicate the file now needs to be uploaded. See Figure 5.  However, the option to provide imaging, or not, can be changed each time the program is submitted up until execution. Providing a snapshot in time of the imaging used to produce the Catalog positions will be useful for researchers to associate with the pipeline-produced spectral products from the program, which will be labeled by target position in the Catalog.  The upload requires a fits format image, and will be checked for a minimum set of header keywords.

(3) Finally, after the pre-image is attached to the program, APT will display some new buttons on the MSA Catalog Target: Copy to Disk, Replace, Send to Aladin, and Remove from Proposal (see Figure 6). These buttons allow one to copy the image to disk, replace the FITS image with a newer one for the archive, send the image to Aladin for viewing in APT, or to remove the pre-image from the program.

NIRCam pre-imaging that is part of the same program as the MOS observations will not need to be uploaded. The NIRCam images will automatically be saved in MAST, so do not need to be uploaded with the MOS program update.

---

Candidate sets (Also called Candidate Lists)

Candidate sets are extracted from the supplied source Catalog after it is loaded into MPT. Filters are applied to choose a subset of the source list based on a magnitude range, a type of source (extended vs. point-like), or a redshift range, among other possibilities. Several Candidate sets can be defined from the parent source Catalog.

By clicking on the New Candidate Set button, a new pop-up window is displayed (Figure 7). First specify a Name and begin source filtering by clicking on Add Filter. This button will present a set of options for filtering sources from the Catalog: ID, Coordinates, R50, FWHM, Size, Redshift, Reference Star, Stellarity, Weight, Area, Ellipticity, Theta, Magnitude, Magnitude Error, and Number Column. Define the appropriate filter limits for the candidate set, and click OK to close this window. Note that a range includes the numbers entered. Finally, click "Make Candidate Set".

MPT's calculations are complex and involve multiple iterations. Large source lists can result in long runtimes. The computations have been parallelized to increase efficiency, but the runtime will depend on your computer. (See the MPT Computational Performance article). It is advisable to experiment with smaller Candidate sets to see how long it takes and then add to them as needed.

Figure 7 demonstrates how to create a Candidate Set (also known as  a Candidate List) of sources from a given Catalog. In the example shown, sources with redshift between 2 limiting values are selected as members of the Candidate Set. By clicking on the Make Candidate Set button, the new Candidate Set is created. As many Candidate Sets as needed may be created using this procedure. 

Source Catalogs and Candidate Sets may be deleted using the Delete button seen in Figures 4-7, just below New Candidate Set. Note that a Catalog or Candidate Set used in an observation cannot be deleted until the observation using it is deleted.

A Catalog and/or one of the candidate sets derived from it, can be highlighted in the Targets folder of the GUI and displayed in Aladin by clicking the Send to Aladin button (shown in Figure 4). Figure 8 shows an Aladin view of the spatial distribution of sources from two Candidate Sets. We refer the user to the Aladin documentation for further information about Aladin features.

Once the parent source Catalog has been uploaded and the Candidate Sets have been created, the Planner can be used to specify a plan, as explained in the article NIRSpec MPT - Planner.

---

References

Karakla, D. et al. 2014, Proc. SPIE 9149
The NIRSpec MSA Planning Tool for multi-object spectroscopy with JWST

Aladin 

---

---