NIRSpec MPT - MOS and MSATA Program Updates

Even though final planning of MOS programs and reference star selection requires an assigned aperture position angle (Aperture PA), it is recommended that observers update their Catalogs early during program implementation. STScI understands that those programs requesting pre-imaging will need to wait for that to be completed before the Catalog can be updated.

For typical MOS programs, and any program using MSATA in Cycle 2 and beyond, by the MOS Program Update deadline 8 weeks prior to the start of the plan window, the observer must have updated their Catalog with candidate reference stars and their magnitudes in the TA filters. 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. This work should be completed by the first program update submission deadline.  Note that the observer will have to go through the lengthy exercise of checking for suitable reference stars in the vicinity of the MOS observations, and registering the Catalog to Gaia sources.

On this page

MOS program updates

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

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

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 candidates for use with the MSATA target acquisition methodology. FS and IFU programs using MSATA require a similar process. Each MOS or MSATA program will be assigned a plan window for each MOS observation and a related program update deadline.

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



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. Once the long range plan is constructed, programs that use the MSATA method of target acquisition receive an angle assignment from STScI early in the cycle. When the program is retrieved from STScI in APT, an assigned Aperture PA will appear in the APT program (Figure 1). STScI schedulers will make their best effort to hold the angle assignments for each MOS program fixed. However, circumstances may occasionally require STScI to make angle assignment changes over the course of the observing cycle. Additionally, PI-initiated angle assignment change requests are allowed, with some limitations. Whether initiated by the PI, or STScI during program implementation, an angle re-assignment will involve the need to replan a MOS observation.

At proposal submission, the exact pointings within a MOS observation are not yet finalized, so the assigned Aperture PA used for scheduling MOS observations is anchored to the Catalog Reference Position. For large or lop-sided catalogs, the Catalog Reference Position can be quite far from an individual pointing in the finalized observation of the MOS program update. Since the observatory does not roll during an observation, different pointings in the MOS observation have slightly different values of Aperture PA, reflecting the fact that the angle is relative to the position of the North Celestial Pole, which is slightly different for each pointing.

Keeping the assigned Aperture PA anchored to the Catalog Reference Position, MPT will compute an Aperture PA for each pointing, which is usually slightly different than the assigned APA. The APA values for a given pointing are presented on the MPT Plans pane in the Pointings table (see Figure 4 below, where the adjusted value is presented in the column called "APA"). 

This is important to keep in mind for users ingesting MSA configurations created outside of MPT.  The MSA configurations must be designed for the correct adjusted Aperture PA, not the assigned Aperture PA. The easiest way to determine the angle to use is to create a dummy observation with MPT for the exact pointing you wish to use for designing your MSA configuration outside of MPT.

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

        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 for the MOS program update submission so that appropriate reference star candidates can be included. Observers who requested and obtained  NIRCam pre-imaging may also want to update the catalog to include new sources and update all positions to the more precise astrometry. In that case as well, a selection of reference star candidates is required.

Source positional accuracy check required for MSATA and MOS observing

Based on experience from early MOS observations, the success of MSATA execution relies on good absolute positional accuracy, especially in regard to the roll. The NIRCam pipeline has not yet been updated to include a check of the astrometry against Gaia, so it is incumbent upon users to perform this check before deriving source coordinates for the MSA catalog. Observers with catalogs from other instruments, including HST, should also perform this check.

Imaging data used to derive the astrometry for your catalog of reference stars and science targets needs to be carefully vetted against Gaia stars. In particular, the MSA target acquisition procedure has a very limited ability to correct for errors in the initial roll, so it is strongly recommended that the rotation of the reference stars on the sky be aligned with that of the Gaia frame to better than one arcminute (60", 0.0167°) in rotation. Roll offsets larger than 500" (0.14°) are likely to fail. Care should be taken to consider any proper motion of the Gaia stars and reference stars to avoid introducing a spurious roll offset larger than this. This is required to produce the best astrometry possible, and to correct for any lingering small roll offsets that may affect target placements.

Marking candidate reference stars

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 many tens of reference star candidates in the MSA footprint at the first pointing of each visit to account for the fact that some will be blocked by the mounting plate or fall behind failed-closed shutters. Since the stars are sorted and binned by magnitude, each bin will have only a subset of visible reference stars. To form a bin, a minimum of 5 stars (and preferably 8) must survive the magnitude filtering and and be in operable shutters. Hence, 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 three NIRSpec TA filters. REFERENCE should be "TRUE","1", or "YES" (case insensitive) if a source is a suitable candidate reference star, and "FALSE", "0", or "NO" (case insensitive) 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. 

Note that reference star candidates are also considered for science source selection in MPT by default.  If this is not the desired behavior, the user should construct the Primary and Filler Candidate Sets by filtering them out using the catalog filtering capabilities in APT on the MSA Catalog Target.  Filtering is described in NIRSpec MPT - Catalogs.

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). A value of -1 should be used to indicate that the stellarity is missing or unknown. 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 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 imaging data from which the source Catalog was derived. The pipeline processing for MOS produces spectra for each observed source, and those products are labeled by their source ID in the input catalog.  Making this complementary image available to future archival observers is valuable for association with the positions of observed sources in the Catalog. 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 one or more program updates. 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.  Also, do not change the MOS observation number as doing so will cause problems for the observing windows.

To update an existing MOS observation with one that is planned with the updated Catalog at the assigned Aperture PA, follow these steps:

  1. Retrieve the latest version of the program from STScI in APT (File → Retrieve from STScI).
  2. Without deleting anything in the program, ingest the new updated Catalog (named differently) into 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 4. 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. In the Planner, change the Candidate Lists to use the new (updated) Catalog or any Candidate Lists made from it.  You may now change any of the other parameters 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, it is critical to update the existing MOS observation using the newly created MPT Plan. This is so that the MOS observation number remains the same, and so that the assigned Aperture PA for that observation is preserved.  To do this, 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 using the updated Catalog.
  9. Optionally, after updating the MOS observations in the program, it should then be safe to delete old MPT Plans if they are no longer used 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 Program Update 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 MOS Program Finalized deadline (4 weeks before the start of the execution window) will be accepted. If time is too short 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 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 limited duplications in MOS observations are allowed, according to the JWST Duplicate Observations Policy.  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.



Assigned aperture position angle change requests

There are cases where the science would benefit from a different Assigned Aperture Position Angle (Assigned APA), or from splitting the MOS observation into two or more observations.  

Assigned APA change requests that do not require TTRB approval:

  • Must be made in advance of the MOS Program Update submission deadline,
  • Cannot alter the assigned Plan Window  (Note that small APA changes of less than a degree are less likely to result in a Plan Window disruption.),
  • Cannot increase the allocated time

Further, the finalized flight-ready program must be submitted by the MOS Program Finalized date (one month in advance of the Plan Window start), and preferably by the MOS Program Update submission deadline (two months in advance of the Plan Window start).

APA changes like these necessitate a re-plan of the observation and technical review of the new MSA configurations. Thus, only one such change will be allowed per MOS observation (either a MOS observation split, or a change to the APA) and the request should be made as early as possible.  APA change requests (or requests to split a MOS observation) made outside the limitations outlined above must go to the TTRB and will require strong science justification for approval. This could potentially result in the need to push the observation into a future visibility period.


MOS program update submission

       See Also: JWST Multi-Object Spectroscopy Roadmap

For the MOS Program Update 8 weeks prior to the start of the plan window, the following items should be completed (See the MOS Roadmap for additional information):

  • the program comes within the allowed time allocation
  • The MOS observation is planned using the assigned Aperture Position Angle, including final pointings and MSA configurations.
  • the exposure duration parameters in the MOS observation template have been selected
  • Reference stars have been selected for each MOS visit
  • any parallel observations are fully specified, including any joint dithers.
  • any desired Confirmation images are specified
  • the Visit Planner has been updated

After the MOS program update has been submitted, complete with reference stars and observations planned using the Assigned Aperture Position Angle, the PC will check it in, and an instrument scientist will review it.  Following successful review, the MOS program is marked "flight ready", and proceeds to scheduling. These are the necessary ingredients to move the program from implementation to scheduling.




Latest updates
  •  
    Noted what is needed to move a MOS program from implementation to scheduling.


  • Expanded what is needed at program submission to include final angle, pointings, configs

  •   
    Added information about APA change requests

  •   
    Clarified what is needed for the MOS Program Update deadline

  •  
    Minor changes made for Cycle 2
Originally published