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 MSA 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. Additionally, new MOS terminology is defined, and the steps for implementing confirmation images are described. More detailed descriptions of MOS proposal implementation can be found in the JWST Multi-Object Spectroscopy Roadmap. The elements of MPT are covered in NIRSpec MPT - Catalogs, NIRSpec MPT - Planner and NIRSpec MPT - Plans articles. Likewise, 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. The MSA Planning Tool is also used to prepare the MOS program updates that are described in the article MSA Shutter Operability. The computational requirements and performance of MPT are discussed in  NIRSpec MPT - Computational Performance.

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 italics are buttons 
or parameters in GUI tools. Bold 
style represents GUI menus/
panels & data software packages.

Like all JWST observations, NIRSpec MOS proposals are created in APT. However, MOS planning is unlike other APT templates, because most users do not simply select a narrow range of parameters in the 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 become an observation in the NIRSpec MOS observation template in APT.

The basic steps for creating a MOS proposal in APT are as follows: 

  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. Create a Catalog, and upload it in APT's Targets folder by selecting the Import MSA Source Catalog button. This creates a new type of target called a 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, which can be 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 the MPT will populate the MOS APT template with pointing positions, 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 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 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 this 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 configurations 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.

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 configurations, and a table of the MSA sources observed in the MSA configurations.
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.

Planning 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 acquiring NIRSpec MOS confirmation images in the Obtain Confirmation Image 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: 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. Note that confirmation images are not possible when the program has attached parallel instrument observations.

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