NIRSpec MSA Planning Tool, MPT

The MSA Planning Tool (MPT), in the Astronomers Proposal Tool (APT), is used for the preparation of NIRSpec multi-object spectroscopy (MOS) observations.

On this page

See also:  Using NIRSpec MOS mode: Summary and Helpful Hints Video Tutorial,   NIRSpec Multi-object Spectroscopy Overview and Tool Demo Video Tutorial

This page introduces the MSA1 Planning Tool (MPT), which can be found within the JWST Astronomers Proposal Tool (APT). Here, we provide a basic overview of the steps required to create a NIRSpec MOS proposal. NIRSpec MOS terminology is defined, and the steps for implementing confirmation images are also described in this article. More detailed descriptions of MOS proposal and program specification can be found in the JWST Multi-Object Spectroscopy Roadmap.  An overview of the multi-phase MOS observing process, from proposal submission to angle assignment and flight-ready updates can be found in the article NIRSpec MOS and MSATA Observing Process. Additional resources are listed in Resources for MOS and MSATA Program Updates.

The functional elements of MPT are covered in NIRSpec MPT - Catalogs, NIRSpec MPT - Planner and NIRSpec MPT - Plans articles. The MSA Planning Tool is also used to prepare the MOS program updates that are described in the article NIRSpec MOS and MSATA Observing Process. The computational requirements and performance of MPT are discussed in NIRSpec MPT - Computational Performance.

1 micro-shutter assembly

Creating a NIRSpec MOS proposal: a basic overview

See Also: JWST Multi-Object Spectroscopy Roadmap, NIRSpec MOS and MSATA Observing Process NIRSpec MPT - CatalogsNIRSpec MPT - Planner, and NIRSpec MPT - Plans

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

Like all JWST observations, NIRSpec MOS proposals are created in APT. However, MOS planning for most users does not simply involve the selection of a narrow set of parameters in the MOS template. Instead, the MSA Planning Tool (MPT) is used to generate test Plans. (A "Plan" refers to a set of pointings and MSA Configurations designed by MPT.) The Plans are reviewed in MPT, and one or more are selected to create an observation in the NIRSpec MOS observation template in APT.

The basic steps for creating a MOS proposal in APT are as follows (described in more detail in JWST Multi-Object Spectroscopy Roadmap) : 

  1. Select New JWST Proposal from the pull-down just below the Form Editor icon in the top tool bar of APT (shown in Figure 1).
  2. Starting from an existing Catalog, upload it in APT's Targets folder by selecting the Import MSA Source Catalog button. This creates a new type of target called an MSA Catalog Target.
  3. From the Catalog, define appropriate Primary and (optionally) Filler candidate sets with primary sources and filler sources, respectively. Filtering the catalog into these candidate sets can be done in the Catalog Target by highlighting the Catalog and clicking New Candidate Set.
  4. Click on the MSA Planning Tool icon found in APT's tool bar (between the Spreadsheet Editor, and HST's Orbit Planner; see Figure 1).
  5. Use MPT to create a variety of observing Plans, selecting options for nodding and dithering, source centering constraints, and the number of desired configurations in the MPT Planner tab (see Figure 2). For MPT to work, the user must be connected to the internet so MPT can check whether a selected aperture position angle is feasible.
  6. Use MPT to assess the quality of multiple Plans, and determine the best observing strategy for the science to be proposed. This is done in the MPT Plans tab (see Figure 2). 
  7. Create an observation using the preferred Plan by clicking the Create Observation button from the MPT Plans tab. Observations created using MPT will populate the MOS APT template with pointing positions, Primary and Filler candidate lists, MSA shutter configurations, and instrument setups (shown in Figure 3).

  8. Click on the Form Editor icon in the APT tool bar.  Fill out the remainder of the observation template (Figure 3), including exposure parameters, and (optionally) ETC Workbook IDs. Specify optional Confirmation Images, if desired.

  9. Run the Visit Planner, attach the proposal PDF, and submit! (Note that MSA target acquisition does not have to be defined at proposal submission, but will need to be included for flight-ready program updates after an aperture position angle is assigned.)

Figure 1. Loading the MSA Planning Tool in APT

The MSA Planning Tool is located in APT's tool bar. Clicking the icon will start the tool. At minimum, a Catalog will need to be defined prior to using MPT.
The MPT contains 2 tabs, as shown in Figure 2. The Planner tab includes a series of choices that will be used to generate optimized MSA configurations. These include the slit shape, nodding and dithering options, and choices to define the search grid for the optimization, among other things. The Plans tab of MPT allows proposers to evaluate the Plans, including the number of primary and filler targets that will be observed, and the number of exposures (dithers) that they will appear in. The Plans tab is useful for comparing the results of different choices that were made in the Planner tab. One or more Plans can be selected and made into an observation from the Plans tab. The NIRSpec MPT - Planner article describes that process in more detail.

In addition to the more common option of running MPT for automatic optimization, the NIRSpec MOS observation template includes an MSA Configuration Editor that can be used to create a custom MSA Configuration. With the MSA Configuration Editor, users can open and close particular shutters with the Catalog overlaid on the MSA shutter view. This editor can be used to modify MSA Configurations generated with MPT, as well as create new MSA Configurations from scratch. This process is described in the article Custom MOS Observations using the MSA Configuration Editor.

Finally, users can specify long slit MOS observations by selecting one of the long slit MSA Configuration provided in the observation template. This optional way of planning MOS observations also does not require the use of MPT. It is described in detail in the Long Slit MOS Observations article.

Following initial program submission, users should not change the MOS observation number.  During program implementation, MOS observations windows are identified on the long range plan and assigned an Aperture Position Angle. The internal mechanisms for keeping track of MOS observations can only happen if the observation number remains the same throughout implementation. Contact the JWST HelpDesk or your PC if you need to change the MOS observation number.

Figure 2. The MSA Planning Tool  Planner

Figure 3. The MOS observation template

NIRSpec MPT terminology 

NIRSpec MOS observing has introduced some new terminology. Table 1 gives the definition of terms used to describe MOS observation planning and provides links for more information.

Table 1. Glossary of MSA Planning Tool related terms


Parent Catalog

A complete list of sources in the field. This list should include objects of interest for MSA observations and any other objects that could contaminate spectra. The parent catalog will usually contain more sources than are observed in the NIRSpec MOS observations. (Candidate TA reference stars will eventually need to be added after program acceptance and for the design of flight-update programs.) A NIRSpec MOS Observation must be created using a single parent Catalog.
Candidate Set

A user-created list of sources of interest for MOS spectroscopic observations, derived from the parent Catalog. Candidate sets can be subsets of the parent Catalog that meet scientific sample selection criteria. They will typically be used as the primary or filler candidate lists in MPT. The full parent Catalog can also be a candidate set. Minimally, the user must specify a primary candidate set for running MPT.

PlanA product from running the MPT for a single set of parameters. Plans contain a list of pointings, MSA Configuration, and a table of the MSA sources observed in the MSA Configuration.
VisitNIRSpec MOS APT visits within an observation are created by the MPT after clicking Create Observation. Visits are components of an observation that begin with guide star acquisition, followed by target acquisition, and ultimately science exposures and perhaps small angle maneuvers of the telescope. All visits in an observation will execute at the same orient.
Observation NIRSpec MOS observations are sets of visits that are made by the MPT after clicking Create Observation on a preferred Plan or set of Plans. The NIRSpec MOS observation template is populated with many of the required observing parameters. Exposure parameters and other options can be added or edited to fully specify the observation. All visits in an observation will execute at the same orient.
MSA ConfigurationA set of planned open and closed micro-shutters in the MSA for one exposure, or one set of nodded exposures (which uses the same pattern of open/closed shutters). A visit may contain several MSA Configurations as needed to complete an MSA observation.
Target SetA subset of sources from the parent Catalog that are observed in the set of exposures that constitute a complete set of nods and dithers specified in the MPT Plan. A target set can use multiple MSA Configurations to achieve dithering. One or more target sets, each containing one or more MSA Configurations, may be observed in a single observation.


A series of adjacent commanded-open micro-shutters in the cross-dispersion direction forming a slit to disperse the light of a given target.

Source Centering Constraint

One of 5 choices for limiting source centering within a shutter in the MPT Planner: from tightly constrained to unconstrained.


Reposition the telescope slightly between exposures to place the targets into different shutters within their respective slitlets using the same MSA Configuration.
DitherTelescope offsets used to acquire multiple exposures within a single visit. By definition, dithers require a new MSA Configuration, while nods do not.

Optional NIRSpec MOS confirmation images

 NIRSpec MOS Confirmation Images can be acquired through the spectroscopy science filter and the science MSA Configuration.

There are 3 available options for NIRSpec MOS confirmation images in the Obtain Confirmation Images pulldown selection:

  • No (default): No MOS confirmation images are acquired at any point in the execution of science exposures.

  • After Target ACQ: MOS confirmation images are acquired following the conclusion of the NIRSpec target acquisition activity in a visit, and after the MSA and science filter are configured. These images can provide verification of target positioning within the MSA Configuration used in a visit. TA executes only once during a visit, so this confirmation image will also be taken just once.

  • After Target ACQ and New MSA Config: MOS confirmation images are acquired immediately after configuration of the MSA, every time a new MSA slitlet configuration is used. Note that for this option, the grating wheel will move to the imaging mirror to take confirmation images in-between science spectra. When the grating wheel is reconfigured to the dispersive element, it might not return to the exact same science position used for prior exposures. As a result, small wavelength shifts can occur between multiple MOS spectra acquired with a confirmation image in-between exposures. However, NIRSpec's grating wheel sensor is designed to remove this shift in the calibration pipeline.

Confirmation images can be planned by selecting the appropriate option in the multi-object spectroscopy pull-down menu in the APT template, as shown in Figure 4. This option should be selected after observations are created in the template by using the MPT.

Figure 4. Confirmation images in the MOS template

The Confirmation Images options in APT.


Karakla, D. et al. 2014, Proc. SPIE 9149
The NIRSpec MSA Planning Tool for multi-object spectroscopy with JWST

Latest updates
    Removed text about confirmation images not being allowed with parallels
    Review and minor updates

  • Added warning that users should not change MOS observation number during program implementation

    Added figure 3

    Minor updates and added links to other articles.

    Updated Figure 3 showing Assigned Angle field

    Added links to video tutorial help. 
Originally published