NIRSpec MPT - Catalogs

Requirements for creating a catalog of sources, and ingesting it into the MSA Planning Tool. Candidate sets are also introduced.

On this page

Words in bold italics are buttons 
or parameters in GUI tools. Bold 
style represents GUI menus/
panels & data software packages.

In order to use the MSA Planning Tool (MPT), the user must create a Catalog for the field to be observed. This is true even for proposers waiting for NIRCam pre-imaging for accurate source positions. In that case, users should create a fake Catalog with similar areal coverage and density for using MPT to design their MOS proposals.

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.

Creating a source catalog

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

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 header line at the top of the file indicating column names separated by whitespace. The header 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.

Updating a source catalog with candidate reference stars for the MOS Program Update

See Also: NIRSpec MOS and MSATA Observing Process, MSA Shutter Operability, NIRSpec MOS Operations - Pre-Imaging Using NIRCam, NIRSpec MSATA Reference Star Selection Recommended Strategies

Observers will generally need to update their source Catalog before submitting the MOS program update. This is especially true when observers have requested and obtained NIRCam pre-imaging because actual source positions will have changed. Even so, the Catalog will have to be updated to mark suitable candidates for reference stars if using MSATA. The catalog update consists of adding 4 columns to identify the candidate reference stars in the brightness range from ABmag 18 to 25 in the NIRSpec filters.  The 4 required columns should be labeled "REFERENCE", "NRS_F110W", "NRS_F140X", and "NRS_CLEAR". The columns represent the suitability of a source as a reference star, and its magnitude in the NIRSpec TA filters. The value in the "REFERENCE" column should be TRUE if a source is a suitable candidate reference star, and FALSE otherwise. The values in the other 3 columns are the expected ABmag of the source in each of the NIRSpec TA filters indicated. The JWST ETC can be used to help derive these columnar data from existing magnitudes. Suitable candidates will have magnitudes in the NIRSpec bands from 18 to 25, and they should be isolated from other brighter sources or sources of similar brightness. During the preparation of the MOS program update, after ingesting the updated Catalog into APT (explained in the next section) and re-planning the MOS observation at the assigned angle, observers will be required to select a Reference Star bin for each Visit of their program. At that point, the positions of the candidate reference stars are checked in APT against available shutters in the MSA at the assigned Aperture Position Angle. The selection of the reference star bin at the Visit level in APT will infer the selection of the TA readout pattern and TA Filter for that Visit. Usually, the bin at the top of the pull-down menu is the preferred choice. It should have the most reference stars (with a minimum of 5 and up to a maximum of 8), and the reference stars should be in as many MSA quadrants as possible.

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.

Figure 1. Importing a catalog of sources

A pop-up window will then appear for loading the Catalog called the MSA Source Importer, 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. The name should not have spaces. 
Figure 2. Selecting a File Format

Defining the working set of columns

If the File Format has been selected properly in the MSA Source Importer pop-up window, MPT will attempt to auto-identify or label the columns (Figure 3) with the help of the header. Users should correct the labels using the pull-down menu located below each column. A number of common options are available: ID, RA, DecMagnitude, Magnitude ErrorRedshiftFWHM, 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 the Catalog has many columns that you don't need for planning, then it is convenient to leave them labelled as Ignore. If you plan to use a column in MPT for making a filtered Candidate Set, and it does not appear in the list shown, select Number if it contains numerical data, or Label if it has alpha-numeric values.

Figure 3. Assigning a type to each column

This source importer window pops up when loading a Catalog as an MSA Catalog Target. The window is expandable. MPT will try to identify the data type in each column, but it may need assistance in doing so. The user should help to identify the data type using the pull-down menu below each column. Only the columns you wish to have displayed in APT should be identified in this way.

Important Caveats

Despite all the nice options listed above, only columns labeled Magnitude, Size, Redshift, Weight, or Number can be used to create Candidate Sets by filtering the parent Catalog in APT. Since Candidate Sets will 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.

There are some known issues regarding catalog ingest and filtering:

First, if you plan to use Candidate Sets (subsets of the parent Catalog) for planning in MPT, make sure to ingest those columns as one of these 4 types: Magnitude, Size, Redshift, or Weight. If none of those options make sense, select the Number option. The "Number" type has been provided as a work-around. A detailed example is shown in an expandable panel below this box.

Alternatively, or if the workaround described here fails, identify the subset of sources for your Candidate Set outside of APT, and add a new column to the Catalog containing a unique numerical value to mark this set of sources. Ingest the column as a Number column so you can work with it in APT.

Secondly, one or a few of the recognized column types listed in the first paragraph of this subsection may not be displayed after catalog ingest. Magnitude Error has this problem. If you want to use this column for filtering, then, once again, select the Number label during ingest. The column will then be displayed, and the data should then become available for filtering (using the Number filter) to create a Candidate Set.

An example showing a step-by-step workaround for creating a Candidate Set using the Number column type

Let's say your catalog contains a FWHM column, and you wish to use it to filter the Catalog to create a Primary Candidate Set for use with MPT. The trick is to load it into APT in the following steps:

  1. Load the Catalog into APT as shown in Figures 1 and 2 above. By default, the FWHM column will be indicated as FWHM.

  2. Change the label below the column to Number by highlighting that option in the pull-down.

  3. Click Import to ingest the Catalog, and then specify the Astrometric Accuracy and Pre-Image Availability.

  4. Note that the catalog data displayed does include the FWHM column data (the last column in the figure above), but it is called FWHM, not Number. Column types read in as Number columns will not be displayed at all, unless they are one of the 13 or so types listed above Figure 3 that are automatically recognized by APT.

  5. Now, we want to create a Primary Candidate set for observation planning which contains only those sources within a specific range of values of FWHM. Click the New Candidate Set button below the highlighted Catalog (See previous figure). In the pop-up window (shown below), click the Add Filter button, and select the New Number Column option from the pull-down.

  6. In the new smaller pop-up window, pull down the Column menu and select FWHM.  Enter a Minimum and/or Maximum FWHM value for your Candidate Set.

  7. Click OK, and Make Candidate Set.  The new Candidate Set will then be displayed. Note that it contains only a subset of the parent Catalog sources.

Once the Catalog is ingested, selecting or highlighting it will display the data as shown in Figure 4. 

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 and 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 the user elects the Use Weights option in the MPT Planner, MPT will use the weights in the Catalog in a linear way. E.g. 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.

Catalog properties

An Astrometric Accuracy in units of milli-arcsec 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 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 the reference point for the observations that will use this Catalog. This position is the median values of the catalog source RA and Dec. All pointings derived by the Planner in the final plan and used to create an observation will be referenced as offsets from the Reference Position. When MPT designs offset pointings in Plans with dithers specified, the APA will be slightly adjusted from the specified APA in order to maintain the telescope attitude between dithers. 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 CatalogThe reference image will be stored in the archive for later archival observers.

Table 1. Description of the pre-imaging availability options

 Pre-image AvailabilityDescription
Is already obtained

The image was already obtained using a NIRCam observation, or another imaging instrument. The observer will be expected to upload the image to the archive during MOS program updates.

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 programThe 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.
Not required

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.

Figure 4. A Catalog successfully loaded to the MSA Planning Tool

A parent Catalog as displayed in MPT. Note the scroll bars. Scroll bars are available to help users navigate the catalog. Reorder columns by dragging and dropping. Note that the re-ordered Catalog displayed here if for convenience only, it has no effect on Catalog ordering as used in MPT to populate the MSA configurations, for example. A Comments tab is provided. It may be useful to comment on the magnitude units in the Catalog, for instance.

Candidate sets

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 a limited set of options for filtering: Magnitude, Size, Redshift, Weight, and Number Column. Define the appropriate filter limits 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.

Figure 5. Creating a candidate set by filtering catalog sources

Creating a candidate set by selecting sources with redshift greater than 3.
Figure 5 demonstrates how to create a Candidate Set of sources from a given catalog. In the example shown, sources with redshift between two limiting values are selected as members of the Candidate SetBy 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 Figure 4.

Do not delete a Catalog if you have Plans in MPT that were made with the Catalog

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 6 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.

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.

Figure 6. Example of an Aladin view of two candidate sets.
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.


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


Latest updates
    Added a section to describe the addition of columns marking candidate reference stars for MOS program updates.

    Described how the catalog reference position is computed and how it's used

    Clarified use of fake catalog for those waiting for pre-imaging.

    Described important caveats for catalog data ingest into MPT.  Provided a workaround to make it possible to filter on certain columns to make candidate sets for MPT planning.

    Fixed quotes and APT parameter fonts
Originally published