NIRSpec MPT - MOS and MSATA Program Updates

Final planning of MOS programs can only be done after an aperture position angle (Aperture PA) has been assigned, and when any required pre-imaging has become available.

During final planning, the observer will need to update their Catalog with candidate reference stars indicated, and with the magnitudes of the sources in the TA filters. The MOS observations will need to be replanned at the correct assigned angle. Finally, reference stars will need to be selected at the visit level in the program for each visit of a MOS observation, and TA exposure specifications will then be determined. Using the actual number of reference stars expected to be observed, APT will calculate a new overhead duration for the MSATA

On this page

        See Also: JWST Multi-Object Spectroscopy RoadmapNIRSpec MOS and MSATA Observing ProcessPre-Imaging Using NIRCam

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

As noted in the MOS Roadmap and the NIRSpec MOS and MSATA Observing Process articles, MOS programs must be updated with final science source selections from any pre-imaging, and with the specification of reference stars for use with the MSATA target acquisition methodology. FS and IFU programs using MSATA require a similar process. Each program will be assigned a program update deadline based on the scheduling window and selected orientation.

The following sections of this article outline a sequence of steps or considerations that observers should follow leading to their MOS program update submission. The information here complements the more terse MOS Roadmap.

Programs with an early deadline will need to be finalized quickly after the instrument astrometric solution becomes available near the end of commissioning.



Assignment of the aperture position angle

See Also: JWST Position Angles, Ranges, and Offsets, NIRSpec MOS and MSATA Observing Process

MOS observations and reference star selection can only be finalized after the aperture position angle has been assigned and the astrometric solution has been updated. Once the long range plan is constructed, programs that use the MSATA method of target acquisition receive an angle assignment from STScI. When the program is retrieved from STScI in APT, an assigned Aperture PA will appear in the APT program (Figure 1). Once angle assignments are made, STScI will make their best effort to adhere to the assignments given to each program. However, circumstances may occasionally require angle assignments to evolve over the course of the observing cycle. 

Figure 1. Where to find the Assigned Aperture PA in APT

Once an angle assignment has been made by STScI, APT will indicate the assigned angle (red circle) in the observation template. APT will also mark as an error (red X) when an observation does not use the correct assigned angle.


Updating the MSA Catalog with candidate reference stars

        See Also: NIRSpec MPT - Catalogs, NIRSpec MOS and MSATA Observing Process, NIRSpec MOS Operations - Pre-Imaging Using NIRCam, NIRSpec MSATA Reference Star Selection Recommended Strategies, and Predicting MSATA Reference Star Magnitudes

Observers will generally need to update their source Catalog before the MOS program update can be finalized. This is especially true when observers have requested and obtained NIRCam pre-imaging. In that case, actual source positions may have changed, 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. All in all, there should be more than 8 reference star candidates to account for the fact that some will be blocked by the mounting plate or fall behind failed-closed shutters. In areas that lack actual stars, the user may need to expand the list of candidates to include point-like galaxies.

The Catalog update requires the addition of 4 columns to identify the candidate reference stars in the brightness range from ABmag 18 to 25 in the 3 NIRSpec filters. The 4 required columns should be labeled "REFERENCE", "NRS_F110W", "NRS_F140X", and "NRS_CLEAR" (see Figure 2). 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" or "YES" if a source is a suitable candidate reference star, and "FALSE" or "NO" otherwise. The values in the other 3 columns are the expected ABmag of the source in each of the NIRSpec TA filters indicated. Suitable candidates will have magnitudes in the NIRSpec bands from around 18 to 25, and should be isolated from other brighter sources or sources of similar brightness. The user is directed to read the articles NIRSpec MSATA Reference Star Selection Recommended Strategies and Predicting MSATA Reference Star Magnitudes for guidance on how to identify suitable candidates and produce the required magnitudes. The JWST ETC can be used to help derive these columnar data from existing magnitudes. 

If it is not already present, a column indicating the "STELLARITY" of a source should be added. The column should have values between 0 and 1 to indicate the degree to which the source resembles a point (1 is point-like). This column is used by the pipeline processing software to determine which processing steps should be performed.  If the Catalog for the MOS observation was produced by the NIRCam pipeline from pre-imaging or imaging in another program, it will contain a column called "IS_EXTENDED". This will be used to compute a STELLARITY value for MOS spectral pipeline processing if one is not already present in the Catalog. If a STELLARITY column has been added to the Catalog containing user-determined values, that will take precedence over the "IS_EXTENDED" column that was generated by pipeline processing.

The MSA Catalog target can be edited up until the first MOS observation using it has been executed.

Figure 2. Added columns for indicating suitable reference star candidates

In this figure, the MSA Catalog Target has been highlighted in the APT tree, and then the parent Catalog has been highlighted within the GUI window in order to make visible the Catalog data (scrollable area). An updated Catalog includes the "Reference" column and the 3 columns containing magnitudes of each source in the MSATA filters ("NRS_F110W", "NRS_F140X", "NRS_CLEAR").

Making pre-Imaging available for archival researchers

At initial proposal submission, MOS users were instructed to make the connection between any NIRCam pre-imaging and the MOS observation in their proposal. This was done by selecting the appropriate option from the menu in the Pre-Image Availability field. The Pre-image Availability is specified on the MSA Catalog Target in the Targets folder in APT.  If the user highlights the MSA Catalog Target used in the MOS observation in the Targets folder, and again highlights the Catalog in the GUI, the Pre-Image availability field appears. (See the top panel in Figure 3.) The various selection options for this field are described in NIRSpec MPT - Catalogs.

At any time after proposal acceptance up to the point when the NIRCam observation has executed, it is still possible to connect the Catalog with the NIRCam pre-imaging in the manner illustrated in the lower panel of Figure 3 by selecting "Will be done in this program".  Doing so will set up the infrastructure to associate the NIRCam imaging products in the archive with the MOS observation products. However, once the NIRCam data have been obtained, then it is best to select "Is already obtained" for an option to upload the image and make a connection between it and the MOS data.

Observers who have obtained pre-images from other sources (e.g., existing HST data, NIRCam data from a different program, images from other telescopes) are also encouraged to provide an image for upload to MAST for future archival researchers. Even if the "Not required" option was selected at proposal submission, it can be changed during program development to "Is already obtained". This selection will allow for the opportunity to upload an image that will serve as a permanent record of the data from which the source Catalog was derived. Since the pipeline processing for MOS produces spectra for each observed source, and those products are labeled using their positions in the input catalog, making this complementary image available to future archival observers is valuable and recommended. Uploaded images will have the same proprietary period as the program products, typically one year. Providing the associated image is entirely optional and is left to the discretion of the program PI.

Note that attaching pre-imaging is an edit to the MSA Catalog Target itself.  Catalogs are editable up until the first MOS observation using them has been executed. 

Figure 3. Pre-imaging availability options

In the top figure, the MSA Catalog Target has been highlighted in the APT tree, and then the parent Catalog has been highlighted within the GUI window. The Pre-Imaging Availability field then appears in the GUI. Clicking on the field will offer a small menu of options, as shown.

The selection shown in the lower figure is appropriate for proposals containing as-yet-unexecuted NIRCam pre-imaging linked to the MOS observation. The option "Will be done in this program" will cause a new field to appear called "NIRCam Pre-Image Observation". The user can then specify the observation number of the NIRCam pre-imaging. Alternatively, if imaging from other sources has been used to create the input MSA Catalog, then the imaging data can be uploaded to MAST at program submission by selecting "Is already obtained" (the option highlighted in blue in the upper figure).


Re-planning and updating the MOS observation

      See Also: NIRSpec MSA Planning Tool, MPT

All programs that use MSATA and which need an aperture position angle assignment will require a program update. In this section we list the steps recommended for re-planning and updating the MOS observation. We begin by assuming the Catalog has been updated for reference stars as described above, and that science source positions have been updated from the pre-imaging. We further assume that the Assigned Aperture PA is available in APT. When these milestones have been reached, the observer can replan the observation by following the steps below.

During the preparation of the MOS program update, the MOS observation must be re-planned at the assigned Aperture PA. In order to preserve the assigned position angle associated with the MOS observation, do not delete the placeholder MOS observations, MPT Plans, Catalog, or Candidate sets when making updates to your MOS program. 

The next set of steps assumes that there is an assigned Aperture PA for your MOS observation, and that an updated Catalog has been created. To update an existing MOS observation with one that is planned with the updated Catalog at the assigned aperture position angle, follow these steps:

  1. Retrieve the latest version of the program from STScI in APT.
  2. Without deleting the old Catalog, ingest the new updated Catalog (named differently) to the Targets folder in APT. Catalog ingest is described in the article NIRSpec MPT - Catalogs. In the example shown in Figure 4, the existing Catalog is called HUBBLE-UDF, and the updated Catalog is called HUDF-SMALL.
  3. Next, review the observational strategy used to plan the existing MOS observation: Navigate to the MPT Plans pane in MPT (items marked "1" and "2" in Figure 4). Notice that If you have highlighted the existing observation in the APT tree, you will also see that the top entry is for the observation itself (item marked "3" in Figure 4). Instead of using that entry, locate and highlight the MPT Plan that was used to create this observation (item marked "4" in Figure 4).
  4. Click the "Describe Plan(s)" button (item "5" in Figure 4) to view the planning parameters that were used. Keep this pop-up panel displayed (shown in the lower figure in Figure 4).
  5. Click "Replan" on the highlighted MPT plan (item "6" in Figure 4).
  6. Compare the Planner parameters with the results from the Describe Plan output in step 3. Determine whether any of the planning parameters should be changed. For example, you may wish to narrow the size of the search grid, or change the dithering strategy.
  7. Change any of the parameters you wish in the MPT Planner, give the Plan a new name, then click "Generate Plan". Steps 6 and 7 can be repeated until you have a Plan with satisfactory results (e.g., the MSA utilization is high, and the plan will observe a large number of high priority sources).
  8. Next, to update the existing MOS observation using the newly created MPT Plan, first highlight the existing MOS observation (the one that will be replaced) in the APT Tree. Then, click "Update Observation N" in the MPT Plans pane (item "7" in Figure 4), where N is the observation number of the highlighted observation in the APT tree editor. This will update the observation with the new MPT Plan results. It is important to update existing observations in this way rather than creating a new observation because the angle assignment associated with the earlier observation should be retained.
  9. Optionally, after updating all MOS observations in the program, it should then be safe to delete old MPT Plans if they are unused by any observation. You may also delete the old Catalog if you are certain it is no longer being used in an observation or plan.

Figure 4. Steps in creating an updated MOS observation

In the top figure, the user has navigated to the Plans pane in MPT. The MPT plans used to create observations in the program are now ready to be updated using a new Catalog containing candidate reference stars, and with a newly-assigned aperture position angle. Before replanning, the observer should examine the planning parameters used to create the MPT Plan that was used to make the existing observation. This is done by highlighting the correct plan, then using the "Describe Planbutton to produce a list of saved planning parameters (shown in the lower figure). These planning parameters can be pushed to the Planner using the "Replan" button, and the user can make additional MPT plans by tweaking the parameters. The best plan can then be selected and used to "Update Observation N" (where "N" is the observation number in the APT tree editor).

Shutter Conflicts

       See Also: NIRSpec MSA Shutter Operability

MSA shutter operability evolves with time. For this reason, shutter status is planned to be monitored on an approximately every 2 months basis during operations. The updated reference information is then provided to APT.  You may notice alerts or warnings when loading your program into APT that indicate your previously-planned MOS observations now show some conflicts between planned sources and new inoperable shutters. This is expected. We recommend that you determine the best observing strategy for your program well in advance, but then replan MOS observations with the latest shutter operability just prior to your program deadline. This will mitigate conflicts by using the most up-to-date knowledge of the inoperable shutters. However, there is no guarantee that new conflicts will not develop after the program updates are submitted and before execution.

If you submitted your program update before the deadline and your science is significantly impacted by shutter operability changes after submission, you may wish to update your program again. Program updates up to the deadline will be accepted. If time is too short (i.e., within 60 days from your observation window start) you may request that STScI pull your observations for re-scheduling at a later time.

Contaminant checking of final MSA configurations

       See Also: MSA Target Info FileCustom MOS Observations using the MSA Configuration Editor

With the newly updated observation it is recommended to once again examine your MSA Configurations for Contaminants from the Catalog. Provided that a complete Catalog covering the observation area has been input, contaminants can be located using the MSA Configuration Editor. The MSA Configuration Editor is started at the Observation level in APT by clicking "Edit" on an exposure specification line. Contaminants appear as black dots in the target slits for planned sources in the MSA Shutter View, or in the Collapsed Shutter View of the MSA Configuration Editor. You may need to zoom in to see them. Alternatively, a list of planned sources including contaminants can be exported in the MSA Target Info file after the MOS observations have been updated.



Selecting reference stars for each visit of a MOS observation

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

NIRSpec MSATA parameters, including an actual selection of reference stars and TA exposure specifications, can only be planned after MOS observations have been replanned at the assigned fixed aperture position angle. After re-planning the MOS observation, the pointings of exposures will likely be different than for the previously planned observation's exposures.  When the MOS observation is updated in APT, the positions of the candidate reference stars at the first pointing in the Visit are checked against operable shutters in the MSA at the assigned aperture position angle. A Reference Star Bin must now be selected for each Visit of the program that uses MSATA. FS and IFU programs using MSATA will also follow this step after providing a Catalog of suitable reference stars.

First, make sure you are in the Form Editor of APT. When a visit is highlighted in the hierarchical editor of APT (the "APT tree"), APT will display a representation of the MSA quadrants and shutters (See Figure 5). Just above the MSA figure, the different Reference Star Bins are presented for selection in a pull-down menu. To create the bins, APT checks that candidate reference stars provided in the Catalog are within open areas of the MSA and sufficiently far from inoperable shutters at the first science pointing of the visit. The candidate stars are then ordered by brightness in each TA filter, and the brightest that fall within the magnitude limits for a given filter and readout pattern are selected to form each bin, with up to 8 stars per bin. If fewer than 5 suitable stars are found, the bin will not be offered as a selection. Occasionally, no reference star bins are shown because an insufficient number of suitable sources have been found for each of the bins. In that case, the user may need to expand the list of candidates in the Catalog to other point-like sources in the field.

The expected TA accuracy level is then computed from the input Catalog accuracy and the number of stars in a bin according to criteria in Table 1. This level of accuracy is displayed in the menu next to each bin. In the example shown in Figure 5, all the bins have "Reduced Accuracy" because it was a test that was done with a reduced accuracy input Catalog. Typically, users will need to provide a Catalog with optimal accuracy (<~ 15 mas) relative astrometry for most MOS science. The bins are ordered first by highest to lowest accuracy level for the TA, then by the most to least reference stars per bin, then by the smallest to largest exposure duration (which depends on the readout pattern), and finally by the most to least number of MSA quadrants containing the reference stars in a bin.

The observer's selection of the Reference Star Bin will govern the selection of the TA readout pattern and TA Filter (and, ultimately, the target acquisition timing) 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 selecting it should provide the best accuracy TA given the input Catalog accuracy.  The TA parameters corresponding to the selected bin will then be populated into both the Visit and Observation template. A reference star source ID can be seen by hovering over the small black square symbol of a reference star in the MSA figure. Additional information about the selected reference stars for a highlighted observation can be obtained by exporting the MSA Target Info file after saving the APT program.

Figure 5. Reference Star bins at the Visit level in APT.

Reference star bins are created by APT at the first pointing of the Visit that uses the MSATA strategy.

MSATA overheads after angle assignment

At the time of initial proposal submission, target acquisitions using the MSA are charged a fixed amount of time, currently 2048s.  In reality, the time needed to execute the target acquisition will vary as a function of the readout pattern selected and the number of reference stars used. After an angle assignment has been made, the MPT plan has been finalized for the Assigned Aperture PA, and a particular Reference Star Bin has been selected, APT will calculate the exact time needed for that target acquisition. This will likely result in a change in the time needed by your program. For example, use of the deepest NRSRAPIDD6 readout pattern with 8 reference stars will increase the required time for target acquisition by about 3.25 minutes above the baseline calculation. Should this cause your assigned allocation to be slightly exceeded, please contact your program coordinator to request the needed adjustment in your allocation.

The MSATA timing charge is not displayed separately in APT, but is included in the Instrument Overheads shown at the Visit level. Figure 6 shows an example of the Instrument overhead charges for two different selections of Reference Star Bin in the same Visit. 

Figure 6. MSATA timing charge

Instrument Overheads now includes actual MSATA timing charges based on the number of reference stars in the bin and the TA readout pattern. 


Source by source duplication checking

      See also: JWST Observation Duplication Checking, JWST Duplicate Observations Policy, MSA Target Info File

Users should additionally check there are no source duplications with other programs, from MOS observations, or from FS or IFU programs with similar instrument setups (same filter and grating).

For MOS observations, duplications are determined on a source-by-source basis.  It is worth noting that some duplications in MOS observations are allowed, provided that such objects are in the minority.  Precise definitions of MOS duplications can be found in JWST Duplicate Observations Policy.  Potential duplications can be found in MAST.  Observers may also find the MSA Target Info File useful for obtaining a machine readable list of targets on a configuration. The PI will be alerted by the PC if there are any duplications that need to be resolved.



MOS program update submission

       See Also: JWST Multi-Object Spectroscopy Roadmap

Prior to program update submission, the following items should be completed (See the MOS Roadmap for additional information):

  • the exposure duration parameters in the MOS observation template have been selected
  • any desired Confirmation images are specified
  • any parallel observations are fully specified, including any joint dithers.
  • the Visit Planner has been updated
  • the program comes within the allowed time allocation



Latest updates


Originally published