NIRSpec MPT - Catalogs
Requirements for creating a catalog of sources, and ingesting it into the MSA Planning Tool. Candidate sets are also introduced.
In order to use the MSA Planning Tool (MPT), the user must create a Catalog
* for the field to be observed. 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-50mas. High precision spectral calibration needs relative positional accuracy of 15 milli-arcsec or less, which most likely requires space-based observations. Images obtained using HST/ACS or HST/WFC3 UVIS within the past ten years should have this level of accuracy. In some cases, the planning of the NIRSpec spectroscopy will require NIRCam observations, a process that is called NIRCam pre-imaging. Nonetheless, while high-precision relative astrometry is highly recommended, it is not a requirement.
*Bold italics style indicates words that are also parameters or buttons in software tools (like the APT and ETC). Similarly, a bold style represents menu items and panels.
Creating a source Catalog
Parent source Catalogs can have as many objects as needed. It is recommended that parent catalogs include all known sources in the field in order for the user to locate contaminants and prevent the MPT from placing them into failed open shutters. For flight-ready program updates (but not proposals), the parent Catalog must also include reference stars for MSA target acquisition. 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.
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 may be useful for at least one column to have the source fluxes or magnitudes (optional field).
- The Catalog may optionally contain a line at the top of the file indicating column headers separated by whitespace. The line must begin with a "#".
- Other columns can be included and used by the tool for creating candidate sets if properly identified during ingest (e.g. an optional column of source weights.)
There are some checks that should be done before ingesting your source Catalog into MPT. These are key to avoiding problems with MPT planning and downstream data processing:
- Commas should not be present in the source Catalog, unless they delineate columns in a CSV table. They are not handled correctly when ingesting the Catalog to MPT.
- There should be no duplicate entries in your source IDs. Different source positions should have a unique ID.
- There should be no NULL (or empty) entries in the Catalog. MPT may read the Catalog and assign a value of zero to such data. This would be particularly problematic for a magnitude column and could result in incorrect results in the derived candidate sets made from the Catalog. Instead, choose a value (real or integer) that can be easily filtered out.
Ingesting a source Catalog
To start, the Catalog should be ingested into APT from the Targets Folder. The button "Import MSA Source Catalog", highlighted in Figure 1, can be used to create an MSA Catalog target. This workflow and class of target is new to APT 2020.1.
Note: Use the column type Number to label a column you would like to work with in MPT that does not correspond to any other recognizable type listed.
Scrollbars are present 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 an dropping. The catalog will maintain its initial ordering for making an observation plan.
Weights may optionally be used to create the 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 advisable to create an additional column in the catalog with weights and assign higher values to those sources. When this Catalog is ingested, assign the weight column as a Weight type. If the use of source weights is enabled in the Planner, sources with larger weights are more likely to be observed. If the Catalog does not have a weight column, MPT will assign the weight 1 to all sources.
Note that if weights are assigned to sources, MPT will use these weights in a linear way when activating the use of weights in the Planner. 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.
An Astrometric Accuracy in units of milli-arcsec must be specified. If a Catalog comes from, for example, an HST/WFC3/UVIS observation, one may assign the value 12-15 milli-arcsec. This value is used to estimate the final accuracy of the target acquisition when using the MSA Target Acquisition (MSATA) method. (Note that NIRSpec MSATA parameters do not need to be included in proposals).
The Reference Position shows a fiducial reference point for the observations that will use this Catalog. All pointings derived by the Planner in the final plan and used to create an observation will be referenced as offsets from this pointing. This information is used to determine appropriate observational plan windows.
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 listed in Table 1. If "Will be done in this program" is selected, APT will ask the user to select the appropriate NIRCam observation. This mechanism is used as a way to alert the ground system that there may be an associated observation in this program or in another program that will need to be linked to the MOS observations for planning and scheduling. It can also indicate that there is an existing image in the archive that is associated with the source positions in the Catalog. The reference image will be stored in the archive for later archival observers.
Table 1. Description of the pre-imaging availability options
|Is already obtained|
The image was already obtained using a NIRCam observation.
|Will be obtained external to this program|
The image will not be part of this proposal. For example with a new HST proposal, or an upcoming NIRCam observation in another program.
|Will be done in this program||The user will propose to observe the same field with the JWST instrument NIRCam. In this case, two options are offered: selecting a NIRCam pre-imaging observation from the same proposal, or selecting a NIRCam coordinated parallel image attached to the program.|
For some science programs, an image may not be available and/or isn't required. For example, precise pointing may not be needed for observing extended sources.
Use this option if you just want to experiment with MPT without getting warnings.
Use this option if there exists imaging from an HST program from the past.
Candidate sets (also called Candidate Lists) 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.
Observers should be aware that they need to have all sources of interest in a single parent catalog for a given observation or a set of observations. The candidate lists (Primary Candidate List and Filler Candidate List) are derived from this single catalog. MPT will prevent the creation of an observation from plans that were made with different ingested catalogs.
By clicking on New Candidate Set (see Figure 4) a new window (Figure 5) is displayed. First insert a Candidate Set Name and begin source filtering by clicking on Add Filter. This button will present several options for filtering: Magnitude, Size, Redshift, Weight, and Number Column. Define the appropriate restrictions for the candidate set, and click OK to close this window. Note that the ranges are always inclusive of 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. It is advisable to experiment with smaller candidate sets to see how long it takes and then add to them as needed.
Source Catalogs and Candidate Sets may be deleted using the Delete button seen in Figure 4.
Do not delete a Catalog if you have Plans in APT that were made with the Catalog.
The Send to Aladin button helps the user to visualize the spatial distribution of sources. Figure 6 shows an Aladin view of the spatial distribution of sources from two Candidate Sets. All the Aladin features are available and we refer the user to the Aladin documentation for further information.
Having many planes in the Aladin stack may cause APT to run slowly, even after the popup is closed. To clear out all the layers, users should click Edit > Delete All in Aladin.
Karakla, D. et al. 2014, Proc. SPIE 9149
The NIRSpec MSA Planning Tool for multi-object spectroscopy with JWST