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 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 also not precisely defined by the user - MPT selects them for the user at the pointings it determines for the observation. MPT can also be used to create an MSA configuration at a fixed pointing that the user chooses.

*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 must be 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 at a single pointing. This area is approximately 3' × 3'.  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 sources 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 manipulating the position of the center and the size of the search grid 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. Both Primaries and Fillers are added into an MSA configuration in the order they appear in the Catalog, starting from the top if weights are not used. Source weights can also be added to the Catalog and used during planning. 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, only the weights of the Primaries are used. The Filler weights are not used.

Maximizing the number of exposures that contain the same sources over a set of dithered positions

Even with preferential ordering in the Fillers list, you may find that few Fillers are repeated at all dithers. Fillers are not tracked during dithering in the way that the Primary sources are. Fillers are added to each MSA configuration independently: they are considered in order starting from the top of the Fillers list and inserted into the MSA configuration whenever possible. (Nods are treated differently for Fillers - Fillers will be present in all nods of a given configuration when they are observed.)

If there are sources that you want to observe through a set of dithers, it is recommended to include them in the Primary candidate list and assign weights according to preference.

We suspect most observers will be interested in maximizing the number of Primary sources observed at all dither positions in an observation. The Fixed Dither option will do this for you. 

However, since the Fixed Dither strategy currently does not save partially observed Primary sources (i.e. Primaries that could be observed at some, but not all, dither points) the resulting MSA configurations it produces may not fill the MSA, even with moderate to high source density. Hence, when using Fixed Dithers, the multiplexing efficiency in each MSA configuration can be improved by specifying a Filler candidate list. Including the Primary sources near the top of the Fillers list will provide additional observations of Primary sources, but at reduced 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.

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 up to 3 to 4 times more of them at a single pointing (for high Catalog density). There are no proven strategies to get a large number of the same sources in independent Plans. One way to attempt this is to design the grating Plan first, then 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 parent 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. Add 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.
    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.

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, make the search grid size 0" by 0" in the automatic 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 automatic 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. Bear in mind that optical distortions cause individual sources to be offset by slightly differing amounts, especially when dithering over large distances (>~ 10 arcseconds). MPT will calculate the individual positions of the sources after a specified dither, and will create a new MSA configuration in order to observe all the Primary sources at the new offset position. As such, individual sources may be dithered by a slightly smaller or larger distance than is specified by the Fixed Dither, thereby assuring that sources line up with their respective shutters.

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 positions will fill in their respective wavelength gaps.  When this is done, however, sources will not appear 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. It will soon be possible to add in primaries that appear in multiple exposures, but which are not completely observed at all specified dithers.


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 S/N. 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 slit margin parameter should help to keep source flux from leaking into nearby shutters.

Dithers and search grid parameter selection

The Fixed Dither methodology will work with dithers smaller or larger than the search grid step size.

Dithering is recommended for most use cases, especially when the goal is to observe more Primary candidates per pointing. In Fixed Dithers, only those Primary sources that are observable at all dither positions become members of the observed target set. As noted above, when using Fixed dithers, consider adding a Filler candidate set to fill in otherwise poorly-utilized areas of the MSA. Ordering the parent Catalog with the most desirable sources at the top will cause the Fillers to have the same ordering. Adding a column of target weights and sorting the Catalog by it before uploading it to MPT is a good way to do this. Sources will be considered in that order for each MSA configuration that is generated from the Catalog

Slit-stepping or Slitlet-stepping

See Also: TA Recommended strategies

Often the science targets will 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 possible to design the first MSA configuration automatically in the MSA Planning Tool (or to simply select the long slit configuration for very extended sources) and then to 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. If this is done, attention should be given to specify offset positions on either side of the initial position. In this case, MSATA may not be necessary. Rather, TA Method = NONE may be sufficient. Note that these data will not be automatically associated in the pipeline - that exercise will be left up to the observer.

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

Strategies for examining MPT Plan results

Highlighting targets in the Plans pane will also highlight them in other views ('MSA shutter view' and 'Collapsed shutter view') just as clicking on targets in those views 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 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 NIRCam parallel exposures, and the parallel exposures must be shorter than the NIRSpec exposures. The exposure duration parameters for the NIRSpec exposures can be altered if NIRCam parallels are added.

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 fields, it may be difficult to have clear, uncontaminated shutters adjacent to the target, as normally used for local background measurements in the 'nod' options. Users may instead find that selecting a single target shutter is preferable, and creating a Master Background spectrum for application in the data reduction pipeline will be sufficient.  It is possible to select master background shutters in the MSA Config Editor for each planned exposure or pointing.  

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 Q4 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 MOS Custom Configuration Process. In this example case, a column of NIRSpec MSA shutters can be open in a "longslit" configuration, for example, providing users with a way to acquire spectra across the full cross-dispersion direction on these extended sources in the MOS mode. Two built-in long slit MSA configurations are offered in the pull-down for the MSA configuration in the Exposure Specification. The two long slits, or a custom-designed MSA configuration made using the MSA Config Editor 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