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

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

Using the MSA Planning Tool (MPT) and the MSA Configuration Editor effectively requires some background information. The NIRSpec multi-object spectroscopy (MOS) mode is a complex instrument mode when planning observations in APT. This article shares helpful information for common strategies used by MOS observers. The strategies may involve the use ofthe MSA Configuration Editor as well as the MSA Planning Tool. Ultimately, the best planning strategies to employ depend on the science goals. Some of the more common pitfalls are also discussed. 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. Lastly, the JWST Helpdesk is a good resource for questions that are not answered by the documentation.

For step-by-step instructions for planning MOS observations see the JWST Multi-Object Spectroscopy Roadmap.

Using MPT

See also: MOS terminology

MOS planning with the automatic MSA planning tool (MPT) is recommended for most MOS science. The tool uses the instrument model to find accurate source positions at the MSA, and 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 fixed or dithered pointings. With a proper Catalog and sufficient source coverage, MPT will derive favorable pointings and associated MSA Configurations at those pointings. The observed sources are not specifically selected by the user - MPT selects them as it determines optimal pointings for the observation. MPT typically works using a Grid Search for the Pointing Mode. It tests each grid point to find favorable pointings where the largest number of highest weight sources can be observed in operable shutters. The grid axes are not along RA and Dec - they are along the dispersion and cross-dispersion axes defined by the assigned APA. The final step should be for the user to plan with a step size less than a shutter width. The MPT computational requirements and performance are given in NIRSpec MPT - Computational Performance.

Except for the next section, the rest of this article describes various strategies for using MPT to achieve desired results.

Special cases where MPT is not needed

Extended sources

Spatially extended targets of tens of arcseconds to an arcminute 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, 2 built-in long slit MSA Configurations are offered in the pull-down for the MSA Configuration in the Exposure Specification. One of the 2 long slits can be used with the corresponding 2 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 Observation.

Moving targets

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 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.

Finding feasible angles

There are convenient tools for identifying feasible Aperture Position Angles (APA) for a given target or pointing for JWST observations. They are the General Target Visibility Tool (GTVT) and the NIRSpec Observation Visibility Tool (NOVT). Additionally, one may use the Total Roll Analysis report in the APT Visit Planner to determine feasible angles and associated times during the year when a target maybe observed. Note that the APA and V3PA are not the same for NIRSpec, but are related. MOS programs are typically assigned an APA by STScI from the range of feasible angles. The typical MOS Process is described in the article MOS and MSATA Observing Process.

Catalogs and Candidate lists - inputs to MPT

See also: MPT - Catalogs

Nearly all MOS observation planning with MPT must be done using a Catalog. 'Primary' or 'Filler' candidate lists may be defined by filtering on the values of one or more columns in the parent catalog.

Each MOS observation can only be planned using a single parent Catalog. Plans derived from different Catalogs can only become separate observations.

Catalog size and field of view

When preparing for proposal submission, it is useful to work with a Catalog in MPT in order to experiment with observing strategies and get a realistic estimate of the observing efficiency of your MOS observation. If a catalog from HST or JWST/NIRCam imaging is not available for your target field (e.g., you are planning to also request NIRCam pre-imaging to obtain a Catalog with accurate positions), then you should create a fake Catalog of expected size and density for running MPT.

When 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 critical 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 real Catalog or candidate set (e.g., from HST or JWST/NIRCam) covering an area that is smaller than the MSA footprint, and plan to use the high resolution gratings, the majority of the sources should be in quads 3 and quad 4. This helps to avoid red end spectral cut offs by the detector edge. You can do this most easily by clicking on the appropriate check boxes in the Masking Setup section of the MPT Planner.

Source weights

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 can be a positive float value, and should reflect the relative preference for observing them. Weights up to a very large maximum value will be read correctly. However, to avoid problems with MPT selecting the best pointing using summed weights, is recommended to use a more conservative maximum Weight value of 1e9 in practice. 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, Primaries, Fillers, and Contaminants are summed into a Total Weight for each exposure in the Plan.

Excluding Reference star candidates from the science source candidate sets

See also: MPT - Catalogs

Reference stars can be optionally excluded when filtering a catalog or Candidate Set to create a new Candidate set. The Reference Star filter can be selected from the pull-down list of filters and used alone or in combination with other filters when designing a new Candidate set.

Maximizing MSA multiplexing

The default behavior of MPT is to observe both Primaries and Fillers at as many dither points as possible. The set of observed sources may not fill the MSA, but each source that MPT selects will be observed for the maximum exposure depth. Many observers, however, may be more interested in observing as many Primary (and/or Filler) sources as possible, even if they are not observed to the full exposure depth.

Partially-completed sources

See also: MPT Planner

MPT can be instructed to do this for dithered observations by selecting the option Partially Completed Sources in the MPT Planner, and setting a minimum number of dithers that each source must have. Note however, that this option is only offered for dithers (i.e. Fixed Dithers, or multiple fixed pointings) - if "nods" are used as well as dithers, MPT will only select sources that are in the complete set of nods at a given dither point.

If you would like to fill the MSA with as many sources as possible at each dither, it is recommended to select Partially Completed Sources when dithering. After a first round where MPT selects Primary sources that can be observed at all dither points, it will then 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.

Using "stuck-open" or "failed-open" shutters

The spectrum of the sky or any discrete source falling into a failed-open shutter is dispersed onto the detector, and this could overlap with the spectrum of a science source. Whether this is significant for your science will depend on the brightness of your sources, the grating used, and the background flux level as a function of wavelength. The zodiacal background at a given pointing can also vary depending on the time of year. Unless instructed to do otherwise, MPT will not allow sources from the Primary or Filler candidate sets to be observed in stuck open shutters, as they are poorly calibrated. However, an unplanned source from the parent Catalog can inadvertently land in one of these stuck open shutters. You can check this by following the instructions in the section "Avoiding contamination by other sources".

MPT can optionally be instructed to use stuck-open shutters for planning to increase the multiplexing in the MSA. 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 planned (Primary and Filler) sources. Not only will the stuck-open shutter itself become available, but many shutters around it that would otherwise be masked to prevent spectral contamination by light in the stuck-open shutter will also become available for planning.

When using this option, there are some trade-offs to keep in mind. First, the photometric calibration of a source in a failed-open shutter will be less certain. Secondly, even if there are no planned sources in the failed-open shutter itself, the spectrum of a planned source in a nearby (normally masked) shutter will be affected by light entering the stuck-open shutter. That may be sky background, or light from an unplanned (Catalog) source that is not a Primary or Filler Candidate. Its spectrum will be shifted in dispersion with respect to that of the science source. Of course, the impacts can only really be assessed after the APA has been assigned. Users who require well-calibrated fluxes should not use this option. Also, depending on the catalog source density, using this option may only provide a few additional sources to the Plan. Whether or not this option is selected, MPT will attempt to prevent spectral contamination by separating planned sources (i.e., those from the Primary and Filler candidate sets) in the MSA.

Users who are considering this option may find the article on Background Recommended Strategies useful for estimating the impact of background contamination. The article Background Limited Observations gives advice on how to use the ETC to assess if your observations are sensitive to time-variable background levels.

Avoiding contamination by other sources

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 from a checkbox displayed below the shutters (Figure 1). 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 symbols. If you find too many 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 Configuration Editor to select alternate targets in the MSA Configuration, but that approach is tedious.

*Click on the figure for a larger view.*
Checking for contaminant sources in the slits of planned sources can be done by displaying the MSA Shutter View of an exposure in a Plan on the Plans pane of MPT. When the catalog checkbox is checked (note the blue checkbox at the bottom of the window) possible contaminants are shown as black circles or squares. If the contaminant is present in one of the Candidate Sets used to make the Plan, then it will appear as a black circle. Black squares are other sources from the Catalog, which can sometimes also occupy the same slit as a planned source. In the example shown in the red ellipse, two contaminants are present in the same slit as a filler source (blue filled circle within the slit). The background subtraction for this slit will be impacted by the presence of these additional sources. Note that contaminants can also appear in failed open shutters (red shutters). If **Allow sources in areas affected by failed open shutters** in the *MPT Planner* was selected, the presence of a source in the failed open shutter will affect the target and/or background spectra of any source slits that overlap the light red areas normally excluded from planning.

Observing a set of sources with multiple dispersers or gratings

If the goal is to observe the same sources with more than one disperser, it is usually preferable to plan them together in the same MPT Plan to ensure the the same MSA Configurations are observed with each.

Alternatively, one may prefer to create separate MPT Plans for PRISM exposures to maximize the number of sources. PRISM spectra are much shorter and it is possible to observe 3 or 4 times more of them at a single pointing (if the Catalog density is high). When planning independently, there are no simple strategies to ensure that a large number of the same sources are observed in both 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 imported Catalog with altered weights must become the new Catalog from which all derived Plans are generated. The new Plans can be selected together in the MPT Plans pane to create a single observation in the MOS spectroscopy APT template, as described in the section Merging Plans for overhead savings.

Summarizing, there are just a few choices for planning high- or medium-resolution grating spectroscopy in conjunction with PRISM spectroscopy:

Make separate Plans to make the most of MSA multiplexing for each. This will likely result in many fewer sources in common in both Plans. The user then has the option of altering the Catalog weights during planning as described above.
Plan them together so that more of the same sources are observed in all dispersers in the same Plan. First, select all the desired dispersers when generating the Plan in MPT. Then, you have 2 choices:
1. Checking the box Multiple Sources per Row in the Planner will result in the use of the PRISM multiplexing, but will also cause overlapping spectra for the grating exposures. You can additionally specify a Minimum Separation in shutters to control the extent of spectral overlap.
2. Not checking the Multiple Sources per Row 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 to save overheads

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, shown in Figure 2, 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. After the merge, APT will have a new observation in the APT tree, for which the user will need to complete the exposure parameters (Figure 3).

When merging plans, the individual plans that went into the resultant merged observation should be saved in MPT. Doing so will allow for re-creating these observations when needed, and will help reviewers to understand how the merged plan was created. Unfortunately, the "Describe Plans" button (Figure 2) does not capture the individual plan parameters of an observation made by merging plans.

*Click on the figure for a larger view.*
In the figure above, two Plans have been highlighted in the MPT **Plans** pane (indicated by the red arrow and shown highlighted in blue in the **Plan Selection** table). Clicking ***Create Observation*** (red ellipse) will make a single observation from both Plans.

*Click on the figure for a larger view.*
In the MOS observation template (in the APT **Forms Editor**), 2 new **Exposure Specifications** were made (upper table in this figure) when the observation was created from the MPT Plans. The exposure duration parameters (shown highlighted in red) need to be finalized. Correspondingly, there are 2 new **Configurations/Pointings** specified in the lower table, one for each ***MSA Configuration*** and ***Pointing*** from the Plans.

Duplicating exposures for deep observations

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, seen in Figure 3) that balance exposure overheads and cosmic ray hits. The maximum recommended integration duration is 1500 s. In general, it is better from the perspective of overheads to have more groups than integrations, up to the limiting integration duration. Then, it is better to have more integrations than exposures, up to the limiting exposure duration of 10,000s. The exposure duration parameters can be entered into the Exposure Specification area of the template. The editing buttons for these tables are activated when an exposure specification is highlighted. For deeper observations, additional duplicate exposures can be specified in the MOS observation template Configurations/Pointings area (the lower table in Figure 3) to obtain the total exposure time needed on sources.

Pointings and dithers in MPT

See also: NIRSpec MPT - Planner

Pointings and dithers in MPT are largely controlled using the Pointing Mode setting in the Pointing Setup section of the NIRSpec MPT - Planner. Several options are offered:

Grid Search (with optional Fixed Dithers and/or Nods)
Fixed Pointings (with optional Nods). These may be separated, or overlapping, MSA footprints.
MOS + FS (with optional Nods)

The sections below describe some shortcuts and specific considerations when using each of these options.

Pointing strategies

Creating a single fixed pointing in MPT

To make a plan at a fixed pointing, select the Grid Search Pointing Mode option. Insert the pointing corresponding to the Center of the MSA and set the search grid Width and Height to 0" in the MPT Planner. See Figure 4 below. MPT will design the associated MSA Configuration for the Primary and Filler Candidate Sets in an optimal way using the fixed pointing and APA specified in the Planner.

If it is not strictly required for your science, allowing MPT some flexibility in planning the pointing is preferred for obtaining a more optimal solution. You can adjust the Search Grid parameters to search a small area around your preferred pointing with a fine search grid step size. Depending on your Catalog density among other factors, MPT may find a pointing which will observe more of your candidate sources.

*Click on the figure for a larger view.*

Multiple Fixed Pointings

It is pretty straightforward to specify multiple Fixed Pointings in the MPT Planner. The only extra note here is that these pointings can be completely separated, or share a region of overlap on the sky. MPT will design an MSA configuration for each pointing. If there are regions that overlap in the MSA footprints, MPT will first attempt create MSA configurations that include the largest number sources in common at all the MSA pointings. For those shared sources, the result is like a dither.

MOS + FS observations

Observers who have very few (one or two) favorite sources they wish to observe, while also observing another set of lower-weighted sources in the field are recommended to use the MOS + FS Pointing option in the MPT Planner. The benefit of using this feature of placing a favorite source into one of the fixed slits is that slit losses during to MSA bars will be avoided, while also ensuring that intermittent failed shutters or shorts in the MSA will not affect those sources. It should be noted though that, once the APA is assigned, using this mode will fix the pointing (or set of pointings, if there are a few sources to be observed in the slits). This implies that there will be much less flexibility in the selection of sources observed in the MSA quadrants.

Dithering strategies

Dithering is highly recommended for observing with the MSA. This can be accomplished in several different ways for a MOS observation:

by directly specifying multiple overlapping Fixed Pointings in the MPT Planner. MPT will attempt to optimize the MSA configurations for each pointing, first by attempting to observe the same sources in overlapping footprints.
using Fixed Dithers in the MPT Planner, where MPT finds the best pointings that maximize the number of highly weighted observed sources using a grid search. Both pointings and MSA configs are optimized in this case.
specifying Nods in the MPT Planner. These will be added at every pointing in a dithered plan.
specifying Dispersion and Cross-Dispersion Offsets in the MOS observation template. These can be added on top of pointings designed in MPT.

All of these capabilities are described in the NIRSpec MPT - Planner article. Dither and Nod options for MOS spectroscopy are also described in NIRSpec MOS Dither and Nod Patterns.

It is important to note that optical distortions cause individual sources to be offset by slightly differing amounts at different pointings, especially when dithering over large distances (>~ 10"). However, if Fixed Dithers are used, 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 at each pointing. This approach helps to increase the multiplexing of the MSA when dithers are used. MPT additionally optimizes the pointing and source selection, planning around known failed shutters.

The option to allow Partially Completed Sources (Primaries, and/or Fillers) in the MPT Planner is also offered when using MPT-specified dithers, to help to fill the MSA with sources at each footprint.

When Dispersion and Cross-Dispersion Offsets are specified outside of MPT on the observation template, the dithers will move the telescope relative to the existing distribution of sources at the base pointing, but no checking of failed shutters is performed, and the MSA is not re-configured unless the user applies a new MSA Configuration after the move, so this approach is less optimal to planning fixed dithers and nods using the MPT Planner. However it is useful for sub-shutter dithers, and slitlet-stepping, described below.

A Note about Nods

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). 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 limit source flux from leaking into nearby shutters.

Bridging the detector gap

A dither of ~20" (80 shutters) or larger in dispersion (2 or more exposures) will provide enough separation to bridge the detector gap, so that combining spectra from the 2 dither positions will fill the wavelength gaps. This can be done in several different ways: (1) Specifying a fixed dither of 80 shutters in the dispersion direction in the MPT Planner, (2) Specifying a dispersion offset directly in the Configurations/Pointings table in the observation template, and (3) Specifying a plan in MPT using the No Gaps checkbox in the MPT Planner. The last option is the recommended one since MPT will also check for failed shutters as it plans pointings and creates MSA configurations for successful sources.

Sub-shutter dithers

A sub-shutter dither can be specified directly in the Configurations/Pointings table of the MOS observation template. Each dither point is specified in a different row of the table, which results in one additional exposure if no nods are added. Start with an exiting Plan (e.g., perhaps one created with a catalog using MPT from which the observation is created). This will create a row for the base pointing in the Configurations/Pointings observation table. Highlight the row and duplicate the entry for the base pointing using the Duplicate button below the table. Using the Dispersion and/or Cross-dispersion Offset columns in the table, specify floating point fractional shutter dithers for the new row, as shown in Figure 5. The process can be repeated if additional sub-shutter dithers are desired. Finally, adding nods using the Nod Pattern column will then create multiple additional exposures for each dither specified. Depending on each source's placement in its respective shutter, even a sub-shutter dither could place a source behind the bar separating MSA shutters.

*Click on the figure for a larger view.*
Duplicating the base pointing row, one can add a sub-shutter dither using the same MSA configuration by entering fractional shutter values in the **Dispersion Offset** or **Cross-dispersion Offset** column. Depending on the number of added nods, multiple new exposures may be created. In the case shown, a ***3 Shutter Slitlet*** **Nod Pattern** was specified, hence there will be 3 exposures for each row of this table.

Slit-stepping or slitlet-stepping in MOS mode: pseudo-IFU observations

The MOS mode may be used to create pseudo-IFU observations of moderately extended sources. Often the science targets have resolved structure and observers may wish to perform slit-stepping (with a long slit configuration across an extended source) or slitlet-stepping (with an MSA Configuration of small slits on a distribution of sources in the MSA) to create pseudo-IFU exposures. It is more efficient to dither the telescope between steps using the same MSA Configuration rather than holding the telescope pointing fixed and re-configuring the MSA at each step. Typically, the observer designs steps in dispersion, but additional sub-shutter dithers along the cross-dispersion axis can be used to mitigate the effect of the MSA bars.

For this case, the preferred approach is to design an MSA Configuration automatically in the MSA Planning Tool using a Catalog. Alternatively, one may use the MSA Configuration Editor in APT to design a MSA Configuration. Either way, the next step is to create duplicate exposures in the MOS observation template. In the duplicated exposures, different 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; TA Method = NONE may be sufficient. In the case of small slitlets stepped over a distribution of MSA sources whose centers are listed in a Catalog, the slits of some exposures will not contain the source centers. To avoid pipeline problems, empty slits will be assigned fake sources at the center of the center-most shutter. Note that these data will not be associated automatically in the pipeline—the observer will need to reprocess the observation.

There are other reasons why an observer may want to step a slit or slitlet across a source or sources in the MSA. For example, slitlet-stepping can additionally be used to ensure on-source exposures when the coordinate accuracies are less certain than otherwise required for MOS observations with the MSA, or when the target acquisition methodology MSATA cannot be performed, for one reason or another.

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

MSA leakage calibration exposures

Leakage calibration exposures can be needed to remove spatially-dependent background from diffuse emission. The use of leakage exposures might be superior to nod or master background subtraction, where the leakage can change with the nod, and should be considered when diffuse emission is estimated to contribute 10 percent of the background. Strategies for determining whether MSA leakage calibration exposures are necessary are presented in NIRSpec MSA Leakage Subtraction Recommended Strategies.

Leakage exposures are included in the APT template by adding separate MOS exposures with the MSA Configuration selected to be ALLCLOSED in the Science Parameters Configurations/Pointings section of the Form Editor tab. A Leakage exposure can be added by either duplicating an existing science exposure and then editing for the configuration and exposure parameters or a new exposure can be entered for each pointing and each Grating/Filter selection of the science exposure. Figure 6 displays an APT example with two exposures, one for the science source and one for the leakage exposure (highlighted). The exposure time for the leakage exposure is not required to be the same as that for the associated science exposure.

**Figure 6. Adding leakage exposures for MOS observations.**

Examining the MOS observation and MPT Plan results

See also: NIRSpec MPT - Plans

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 (e.g. "MSA shutter view" and "Collapsed shutter view"). Make sure to first highlight or select one or more Plans, and then highlight 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 7.

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

*Click on the figure for a larger view.*
Sources in one exposure of an MPT **Plan** are highlighted in the **Plans** pane (bottom figure), and then appear as magenta dots in the MSA Shutter View (top left) and Collapsed Shutter View (top right). The Legends provide information on the type of sources by color.

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 of parallel instruments

There are a few optional dithering choices offered with the addition of the NIRCam coordinated parallels. Two- or 3-point "compromise" dither patterns, in 3 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.

Notable updates

12 May 2026
Re-organized the sections and removed some redundant text that exists in other articles.
30 May 2025
Updated Figures 4 and 7 to APT 2025.3.3 appearance.
22 Jul 2024
Added section on adding a Leakage exposure in APT.
25 Jul 2023
Added Figure 1 showing contaminants in the MSA Shutter View
11 May 2023
Added a section on sub-shutter dithers.
21 Apr 2022
Moved discussion of MSATA in crowded fields to the NIRSpec target acquisition strategies article.
12 Apr 2021
Clarified text in Crowded fields section regarding reference star isolation, and stipulated advice about fake catalog density.
07 Feb 2021
Added figures and links, clarified the slit stepping section and a number of other sub-sections. Shortened titles of sections and sub-sections for a cleaner TOC.
09 Oct 2020
Formatting fixes, and added a link.
20 Jun 2020
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.
20 Jan 2020
Corrections for new partially-completed sources option, ignore stuck open shutters option, and adjustable separation of shutters when multiple sources per row is enabled.
27 Jul 2020
Described how at some positions in slitlet-stepping, fake sources are generated and associated with the slits to avoid DMS processing failure.

Originally published

06 Feb 2018

JWST User Documentation

NIRSpec MOS Recommended Strategies