NIRSpec MOS Recommended Strategies

The recommended strategies for the JWST NIRSpec MOS mode depend largely on science use case and goals. The emphasis here is on universal tips and tricks to improve observation efficiency, and avoid common problems.

On this page

Using the MSA Planning Tool (MPT) and the MSA Configuration Editor effectively requires some background information. The NIRSpec multi-object spectroscopy (MOS) mode is arguably the most complex instrument mode to plan observations for in APT. This article shares hints for specifying MOS observations for the NIRSpec MSA. The strategies are not limited to the MSA Planning Tool, but include the use of the MSA Configuration Editor to define observations directly (without the use of MPT). Ultimately, the best strategies to adopt depend to a large extent on the science goals. Some of the more common pitfalls are discussed as well. In addition to these JDox articles, there are training videos, science use case examples, and sample programs for this mode that are provided in APT from the menu item File → JWST Demonstration Proposals. Finally, the JWST Helpdesk is a good resource for problems or questions that are not answered by the documentation.

For step-by-step instructions see the MOS Roadmap.

General notes about how MPT operates, and what it produces

MOS planning with the automatic planning tool (MPT) is recommended for most MOS science. The tool makes use of the instrument model to find accurate source positions at the MSA, and it uses the shutter status information to avoid inoperable shutters, to name a few of the issues that affect MOS observation planning. Using the tool to define your MOS observations is recommended for all but some specialized science cases. MPT can plan observations at a single pointing, or at multiple dithered pointings. With a proper Catalog * and sufficient source coverage, MPT will derive favorable pointings and matched MSA configurations at those pointings for the user. In this case, the observed sources are not precisely defined by the user - MPT selects them at optimal pointings it determines for the observation. MPT can also be used to create an MSA configuration at a fixed pointing that the user chooses.  The MPT computational requirements and performance are given in NIRSpec MPT - Computational Performance.

*Bold italics style indicates words that are also parameters or buttons in software tools (like the APT and ETC). Similarly, a bold style represents menu items and panels.

Feasible angles

There are convenient tools for identifying feasible Aperture Position Angles (APAs) for a given target or pointing for JWST observations. They are the General Target Visibility Tool (GTVT) and the NIRSpec Observation Visibility Tool (NOVT)

Catalogs and candidate lists

See Also: MPT - Catalogs

All MOS observation planning with MPT must be done using a single parent Catalog. 'Primary' or 'Filler' candidate lists are derived from the parent Catalog. Planning MOS spectroscopy with MPT is terminology-rich.

Catalog size and field of view 

When observing in the MSA and using the MSATA methodology for target acquisition, the Catalog area should minimally cover the MSA footprint. This area is approximately 3.5' × 3.5'.  Particularly for detailed program updates, the coverage should be large enough to provide the flexibility of planning at any Aperture Position Angle (APA). This is especially true given that the APA will be assigned to most MOS programs. The extra Catalog coverage will provide some flexibility to MPT to find preferred pointings where a greater number of sources can be observed at a given APA in a single pointing, or over a set of defined dithers. Additionally, it will serve to provide reference stars for the MSATA over the 4 MSA quadrants at different orientations. Reference stars must be defined in the program update, but are not needed at proposal submission.

If you have a Catalog of candidate set covering an area that is smaller than the MSA footprint, and plan to use the high resolution gratings, try to design your plans so that the majority of the sources are in Quad 3 and Quad 4. This helps to ensure that the target spectra will not be cut off by the edge of the detector. You can do this by adjusting the search grid parameters in the MPT Planner

Weights and their use

See also: MPT Planner

If some Catalog sources are preferred over others, place them at the top of the Catalog. This will ensure that these sources are considered first for the MSA configurations, even when target weights are not used. Both Primaries and Fillers are added into an MSA configuration in the order they appear in the Catalog. Source weights can also be added to the Catalog and used during planning. If weights are used in planning, the candidate sets will be ordered by weight before considering them for the MSA configuration. The weights should be integer values, and should reflect the relative preference for observing them. During planning, the candidate lists will be ordered by the source weights.

When a user chooses to use source weights in planning, the weights of observed Primaries are used to define the best pointing, and the weights of all observed sources, PrimariesFillers, and Contaminants are summed into a Total Weight for each exposure in the Plan.

Maximizing exposures of sources over a set of dithers

Like the Primary sources, Fillers are tracked during dithering so that Plans with dithers will observe both Primaries and Fillers at as many dither points as possible. This is the default behavior of MPT. The set of observed sources may not fill the MSA, but each source will have been observed for the maximum exposure depth.

Alternatively, many observers may be interested in observing as many Primary sources as possible, even if they are not observed to the full exposure depth. This can be done when using Fixed Dithers by also selecting "Partially Completed Sources". 

If you would like to fill the MSA with as many preferred sources as possible at each dither, it is recommended to select "Partially Completed Sources". If selected, after a first round where MPT selects Primary sources that can be observed at all dither points, it will look for additional Primaries at as many dither points as possible (down to a minimum number of exposures specified by the user). After completing the addition of extra Primaries to varying depth, the Fillers will be added in the same manner; completed Fillers will be added first, followed by Fillers at fewer and fewer dither points. This option will help to maximize the use of the MSA, though some sources will be observed at less than maximum exposure depth.

If you prefer to keep your Primary and Filler candidate lists separate, add a column to the parent Catalog with a '1' for Primaries and a '0' for Fillers. Upload the Catalog, and then create the Primary and Filler candidate sets by filtering using the added column.

Making use of stuck open shutters

It is possible to allow MPT to use stuck open shutters for planning observations of sources that may fall into them. In the MPT Planner, there is a checkbox called "Allow sources in areas affected by stuck open shutters".  Select this option to allow MPT to use these shutters for sources.  This will help to increase the multiplexing in the MSA. The photometric calibration of these shutters is less certain, so users who require well-calibrated fluxes should not to use this option. 

Checking for contamination by other sources in the slit

The Catalog should include not only your desired sources, but all other sources in the field, so that contamination from unplanned sources can be checked. Contamination checking must be done after a plan has been created in MPT. You can check a planned exposure (in the Plans tab of MPT) by bringing up the MSA Shutter View, and loading the parent Catalog. This will display all additional sources on top of the observed sources with different symbols. Look for slits that have more than one source within the (dark orange) planned slit. These unplanned sources are shown as black dots and plus symbols. If you find some affected slits, either re-plan after lowering the weight of the target source in the Catalog or, if weights are not used, move these affected sources lower in the Catalog. Alternatively, you can use the MPT's MSA Config Editor to select alternate targets in the MSA configuration, but that approach is tedious.

Planning observations using the PRISM and other gratings

When planning to observe the same sources with more than one disperser, it is usually best to plan them together in the same MPT Plan to ensure the the same MSA configurations are observed with each. A primary reason why one may prefer to create separate Plans is to maximize the multiplexing for PRISM observations. PRISM spectra are much shorter and it is possible to observe 3 to 4 times more of them at a single pointing (if Catalog density is high). There are no proven strategies to ensure a large number of the same sources are observed in independent Plans. One way to attempt this is to design the grating Plan first, and export the list of observed sources. Increase the weights of the successful sources in the Catalog, then re-import it, and make two new Plans, one for the PRISM (which will use PRISM multiplexing) and one for the grating or gratings you want to observe. The altered imported Catalog must become the new Catalog from which all derived plans are generated. This approach will allow for creating an Observation from both MPT Plans

There are few choices for planning high- or medium-resolution grating spectroscopy in conjunction with PRISM spectroscopy: 

  1. Plan the PRISM and grating observations separately to make the most of MSA multiplexing for each. This will likely result in many fewer sources in common in both Plans (i.e. fewer sources in BOTH dispersers). The user then has the option of altering the Catalog weights during planning as described above.

  2. Plan them together so that more of the SAME sources are observed in all dispersers in the same Plan. Add in all exposure specifications before generating the Plan. Then, you have two choices:
    1. Checking the box "Multiple Sources per Row" will result in the use of the PRISM multiplexing, but will also cause overlapping spectra for the grating exposures. You can additionally specify the Minimum Separation in shutters to control the extent of spectral overlap.
    2. Not checking the box will result in the appropriate multiplexing for the gratings to avoid overlapping spectra, but will generate PRISM exposures with fewer sources.

Merging Plans into one observation for overhead savings

After developing a set of Plans in MPT, or designing a custom MOS observation in the MOS spectroscopy template, it is possible to select the associated Plans in MPT on the Plans pane and merge them into a single observation in APT using the Create Observation button. The Plans must all have been designed using the same Aperture Position Angle, and must originate from the same parent Catalog, or merging will fail. Merging Plans into one observation can save overheads like the GS acquisition overhead by more efficient packing of the Visits where possible. This feature can be used for merging multiple MPT-generated Plans, like those described in option 1 of the previous section, or for merging Plans from MOS observations designed at the Observation level, or both.

Exposure parameters

Follow the prescribed recommendations in NIRSpec Detector Recommended Strategies and use the JWST ETC to best determine exposure parameters (Readout Pattern, Groups/Int, Integrations/Exp) that balance exposure overheads and cosmic ray hits. For deep observations - additional duplicate exposures can be specified in the observation template to obtain the total exposure time needed on sources.

Planning at a fixed pointing

To make a plan at a fixed pointing, set the search grid Width and Height to 0" in the MPT Planner

Dithering strategies

Dither and Nod options for MOS spectroscopy are described in NIRSpec MOS Dither and Nod Patterns.

Dithering is highly recommended for observing with the MSA. In the MPT, pre-defined dither patterns are NOT offered as they are for other APT templates. Instead, the user specifies a set of fixed dither separations, and the specific pointings are derived for the user by the MPT. Multiple dithers can be specified, and each will result in a new exposure (or set of exposures, if nods are specified). Fixed Dither requires an integer number of shutters to be specified, but the algorithm can tolerate short or long dithers.

It is important to note that optical distortions cause individual sources to be offset by slightly differing amounts, especially when dithering over large distances (>~ 10 arcseconds). However, MPT will calculate the individual positions of the sources after a specified dither taking these distortions into account, and will create a new MSA configuration in order to observe all the Primary sources at the new offset position. As a result, individual sources may be dithered by a slightly smaller or larger distance than specified, thereby assuring that sources line up with their respective shutters. This approach helps to increase the multiplexing of the MSA when dithers are used.

Detector gap

A dither of ~ 20" or larger in dispersion (two or more exposures) will provide enough separation to bridge the detector gap, so that combining spectra from the two dither positions will fill the wavelength gaps.  Normally, sources will not be observed in regions of the MSA where there is no overlap between pointings. These areas can be filled by specifying a Filler candidate list during planning. Additionally, it is now possible to add in Primaries and even Fillers that appear in multiple exposures, but which are not completely observed at all specified dithers. This is accomplished by selecting the option for "Partially Completed Sources" in the MPT Planner.


Short in-slit 'nods' are appropriate for point-like sources, but are not recommended when MSA sources are extended (e.g., when they fill the shutter). Nods are generated by MPT when the user clicks the button of the same name in the MPT Planner. This practice will obtain independent measurements of point-like sources in spectral bands I or II that can be combined to increase Signal-to-Noise. The number of exposures that result will be a multiple (e.g., 3, for 3 nod positions) of the number of specified dithers for each exposure specification (i.e., each grating-filter combination that is specified in the plan). For band III, the PSF is broader than one shutter, so in this case, if nodding is desired, the longer 5-shutter slitlet can be used with nodding at 3 positions in the slitlet. Further, constraining the source centering using the MPT Source Centering Constraint parameter should help to keep source flux from leaking into nearby shutters.

Slit-stepping or Slitlet-stepping

See Also: TA Recommended strategies

Often the science targets have resolved structure and observers may wish to perform slit-stepping (with a long slit across an extended source) or slitlet-stepping (with an MSA configuration of small slits on a distribution of sources in the MSA) across them to create pseudo-IFU exposures. It is more efficient to dither the telescope between steps rather than re-configuring the MSA at each step.  For a distribution of slightly-extended sources in the MSA, one approach is to design the first MSA configuration automatically in the MSA Planning Tool, or to use the MSA Configuration Editor at the Observation level in APT.  Alternatively, for very extended sources, simply select the long slit configuration. Next, duplicate the exposures in the MOS observation template. In the duplicated exposures, offsets can be specified in the dispersion direction to effectively create a set of pseudo-IFU exposures. Normally, one would specify offset positions on either side of the initial position. In this science case, MSATA may not be necessary. Rather, TA Method = NONE may be sufficient. In the case of small slitlets stepped over a distribution of MSA sources, slits at the extra positions will not contain the catalog sources in the slits. To avoid pipeline problems, empty slits will be assigned fake sources at the center of the centermost shutter. Note that these data will not be associated automatically in the pipeline - the observer will need to reprocess the observation.

The slitlet-stepping strategy with TA Method = NONE may be considered as a last resort for crowded fields where MSATA is not be possible.

Examining MOS observation and/or MPT Plan results

Plans generated in the MPT, or MOS Observations turned into Plans can be examined in the MPT Plans tab. The latter process is described in the NIRSpec MPT - Plans article.  Once in the Plans pane, MOS targets can be highlighted and the same targets will also become highlighted in other views ('MSA shutter view' and 'Collapsed shutter view'). Make sure to first highlight or select one or more Plans, and one or more "Pointings" before highlighting the targets of interest. Also, clicking on a target in either the MSA Shutter View or the Collapsed Shutter View will highlight them in other views. See Figure 1.

Planning information about sources in the exposures can also be exported from MPT. From the APT menu, select File → Export → MSA Target Info (csv).

Figure 1. Targets may be highlighted in an MPT Plan and will automatically become highlighted in other APT views.

Adding NIRCam or MIRI parallels 

When adding NIRCam parallels to NIRSpec observations, the NIRSpec observations will typically drive the pointing selection. Dither patterns can be added for the NIRCam parallels to improve sampling in the images. The patterns are described in the article Coordinated Parallel Dither Tables. Some considerations concerning exposure time matching of the parallels and the Primary observations are described below.

It is important not to specify any AUTO-CALs (designated "Autocals" in APT) for the NIRSpec observations as these are incompatible with the parallels that will be added after the NIRSpec planning is completed. AUTO-CALs are not recommended for most science programs, with or without parallels.

An example use case, NIRSpec MOS Deep Extragalactic Survey, describes planning NIRSpec MOS from an existing Catalog and adding NIRCam parallels for nearby imaging.

Compromise dithers and exposure time matching

See Also:  NIRSpec MOS Operations - Pre-Imaging Using NIRCam

There are a few optional dithering choices offered with the addition of the NIRCam coordinated parallels. Two- or three-point "compromise" dither patterns, in three different possible separations each, may be selected via the "Dither Type" parameter in the "Science Parameters" section of the template once the NIRSpec observations are defined. Adding these dithers will double or triple the NIRSpec exposures. NIRSpec planning should be done with this in mind, but it is possible to adjust the exposure duration parameters of NIRSpec after the fact.

Note that there needs to be an exact match between the number of NIRSpec exposures and the number of parallel exposures, and the parallel exposures must be shorter than the NIRSpec exposures. The exposure duration parameters for the NIRSpec exposures may be altered if NIRCam parallels are added with compromise dithers.

If you are planning to add NIRCam parallels and wish them to become the pre-imaging for follow-up NIRSpec observations, be aware that there are Special Requirements that should be added to the NIRSpec observations. These are outlined in NIRSpec MOS Operations - Pre-Imaging Using NIRCam.

Crowded fields MOS observing strategies

Note in the Call for Proposals the observing restriction for crowded fields needing MSATA

NIRSpec observations that require the MSA-based Target Acquisition in fields with a high density of targets (>~1 star per sq. arcsec) or with many bright targets (<ABMag 19.1 at higher density than 1 star per 10 sq. arcsec) are not permitted. 

These restrictions are in place because crowded fields beyond these limits have a either: 1) (>~1 star per sq. arcsec) - greater likelihood of failure in the complex MSATA process that uses reference stars to align the pointing, or 2) (<ABMag 19.1 at higher density than 1 star per 10 sq. arcsec), will not work with the MSATA process at all because of too many saturated stars. If feasible in the science use case, observations of crowded fields may be carried out using blind pointing (TA_Method=NONE), which results in greater pointing uncertainty. In this scenario, slitlet-stepping may help to ensure that the sources are successfully observed. The restriction limits on executing MSATA in crowded fields will be revisited once experience and characterization of the TA on-sky is gained. 

In crowded field science exposures, it may be difficult to have clear, uncontaminated shutters for targets. It is possible to plan single target shutters using the MPT Planner using the single shutter slit option. MPT will not allow plans with more than one Primary target in a target shutter. However, other sources from the catalog may be present in the target shutter and this should certainly be checked. Longer slit options with shutters adjacent to the target that are normally used for local background measurements will likely contain sources. Users may find that it preferable to start by selecting a single target shutter (either in MPT, or by manually creating the MSA configuration in the MSA Configuration Editor). Once the target shutters are selected, one may manually select Master Background  shutters in the MSA Configuration Editor for each planned exposure or pointing.  A Master Background spectrum may be sufficient for background removal in the data reduction pipeline.

Extended source MOS observing strategies

See Also:  Long Slit MOS Observations

Spatially extended targets of tens of arc seconds to an arc minute or more can be observed using the NIRSpec MOS mode. These observations are accomplished by positioning sources in the left side (quadrant 3 and/or 4 (Q3, Q4)) of the MSA field of view.  Positioning these extended targets in Q3 or Q4 affords the best chance of getting complete spectra unaffected by the long wavelength detector cutoff. The MSA planning Field Points in Quadrant 4 of the MSA are offered with TA_Method NONE, Verify_Only, or the Wide Aperture Target Acquisition (WATA) strategy as an alternative to automatically generating planned observations using the MPT. The process of specifying such an observation directly in the MOS template (without using the MPT) is described in the article Custom MOS Observations using the MSA Configuration Editor. Additionally, two built-in long slit MSA configurations are offered in the pull-down for the MSA configuration in the Exposure Specification. One of the two long slits can be used with the corresponding two Q4 Field Points in the Science Aperture selection. The process of using the built-in long slits is described in the article Long Slit MOS Observations.

Moving targets MOS observing strategies

See Also:  Long Slit MOS Observations

Moving targets can pose a challenge for NIRSpec MOS, but they are feasible to observe with special constraints. Particularly, the standard target acquisition process - MSATA - using nearby reference stars will not work, because the reference stars will be moving with respect to the stationary moving target tracking. Instead, moving targets with the NIRSpec MOS may use blind pointing (TA_Method=NONE) or the Wide Aperture Target Acquisition (WATA) strategy if the source is compact with a measurable centroid. The process of planning an observation directly in the MOS template (without using the MPT) can be used for moving targets; this is described in the article Long Slit MOS Observations.



Latest updates

 Formatting fixes, and added a link.

Clarified that for crowded fields, a single MSA shutter slit option may be used in MPT. Also, described how to examine a MOS observation as a Plan in MPT, and added a section on merging Plans.

  Corrections for new partially-completed sources option, ignore stuck open shutters option, and adjustable separation of shutters when multiple sources per row is enabled.

 Described how at some positions in slitlet-stepping, fake sources are generated and associated with the slits to avoid DMS processing failure.