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, by the initial program update two months 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 prior to, or upon, the first program update submission deadline in order that the observer has gone 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 Roadmap, NIRSpec MOS and MSATA Observing Process, Pre-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 program will be assigned one or more program update deadlines 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 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). 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.
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 will 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 the adjusted Aperture PA for each pointing. The adjusted values 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.
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 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, as well as a selection of new reference star candidates.
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 regards 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, at least 5 stars 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 NIRSpec TA filters. The value in the "REFERENCE" column should be "TRUE" or "1" if a source is a suitable candidate reference star, and "FALSE" or "0" otherwise. Values of "YES" and "NO" are not currently supported. 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.
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 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.
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 would cause problems for the observing windows.
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:
- Retrieve the latest version of the program from STScI in APT.
- Without deleting anything in the program, 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.
- 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).
- 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).
- Click "Replan" on the highlighted MPT plan (item "6" in Figure 4).
- 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.
- 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).
- 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 correctly, 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.
- 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.
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 (a month 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 File, Custom 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.
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.
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