Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Content Block

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 how to avoid common problems.

Content Block


Using the MSA Planning Tool (MPT) and the Manual Planner effectively requires some background.  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 Manual Planner 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 NIRSpec MOS Proposal Checklist.

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 selected pointings. MPT can also be used to create an MSA configuration at a fixed pointing that the user chooses.

Feasible angles

There are convenient tools for providing the 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

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

If some Catalog sources are preferred over others, put 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. 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.


When a user chooses to use target 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 in an observation, hence we recommend the Fixed Dithers strategy.  That strategy is much more efficient at maximizing the number of Primary sources observed at all dithers. Though the MSA multiplexing (the ability to fill the MSA with targets in one shot) is better using the Flexible dithers strategy, it cannot produce the same success as the Fixed Dither strategy in observing multiple primary targets through a set of dithers.

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.   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 candidate targets, 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 plusses. 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 Manual Planner to select alternate targets in the MSA configuration, but that approach is tedious when there are multiple configurations in a plan.

Planning observations using the PRISM and other gratings

When planning to observe with more than one disperser, it is usually best to plan them together in the same MPT Plan to ensure the the same sources 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 4 to 5 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 targets. 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 the merging of the final plans in to a single plan. Merge them, then make an Observation from them. 

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:

a. Checking the box "multiple sources per row" will result in the use of the PRISM multiplexing and will cause overlapping spectra for the grating exposures.
b. Not checking the box will result in the appropriate GRATING multiplexing that will keep enough separation between the grating spectra, but will generate PRISM exposures with fewer sources.

Exposure parameters

Follow the prescribed recommendations in NIRSpec Detector Recommended Strategies to determine exposure parameters (Readout Pattern, Groups/Int, Integrations/Exp)  that balance exposure overheads and cosmic ray hits.  For deep observations -  multiple duplicate exposure specifications can be specified in the same plan 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 MPTcanned dither patterns are NOT offered as they are for other APT templates. Instead, the user specifies a set of fixed dither separations, or constraints on a set of 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. Both 'Fixed' and 'Flexible' dither methods are provided in the automatic planner in MPT and can be used for long or short dithers. Fixed dithers requires an integer number of shutters to be specified. 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.  

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.  


Short in-slit 'nods' are appropriate for point-like sources, but are not recommended when MSA targets 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 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

In the MPT Planner, specified dither separations must be smaller than your search grid X (dispersion) extent, or Y (cross-dispersion) extent. Using Flexible Dithers, the specified dithers should be larger than your search grid step size as well. The Fixed Dither methodology will work with dithers smaller than the search grid step size.

Fixed Dithers are 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. 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

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. 

Figure container

Figure title

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

Figure caption

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

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 AUTOCALs for the NIRSpec observations as these are incompatible with the parallels that will be added after the NIRSpec planning is completed. AUTOCALs 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

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 AFTER the NIRSpec observations are defined.  Adding these dithers will double or triple the NIRSpec exposures. Therefor, NIRSpec planning should be done with this in mind. Divide the total exposure time you need by this factor BEFORE planning the NIRSpec observations. 


Note that there needs to be an exact match between the number of NIRSpec exposures generated by the plan, and the number of NIRCam parallel exposures.  

If you are planning to add NIRCam parallels and wish them to become 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.  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 Manual Planner for each planned exposure or pointing.  

Extended source MOS observing strategies

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 canned longslit configurations are offered in the pull-down for the MSA configuration in the exposure specification. The two canned long slits, or a custom-designed MSA configuration made using the Manual Planner can be used with the corresponding two Q4 Field Points in the Science Aperture selection. 

Moving targets MOS observing strategies

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 MOS Custom Configuration Process.

Content Block

Content Block

Multiexcerpt include
MultiExcerptNameNIRSpec icon and Name
PageWithExcerptMR:NIRSpec icon and name

Content Block



Last updated

Published February 06, 2018



The format for 'Last updated' is shown below. Enter updates above this internal"Comment" box. Only enter major updates (not typos or formatting changes).

Updated April 5, 2017

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam fermentum vestibulum est. Cras rhoncus. 
  • Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Sed quis tortor. 

Published March 2, 2017