NIRSpec MSA Planning Tool, MPT

This page introduces the MSA Planning Tool (MPT), which can be found within the JWST Astronomers Proposal Tool Overview (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 NIRSpec MPT - Catalogs, NIRSpec MPT - Planner and NIRSpec MPT - Plans articles, as well as the MOS Roadmap.  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 Observing Process.

On this page

The NIRSpec MOS proposal and observing update process

Proposals for the NIRSpec MOS Mode: Like all JWST observations, NIRSpec MOS proposals are created in APT. However, the MOS planning is unlike other APT templates, because 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, which can then be used when filling out the NIRSpec MOS observation template. (A plan refers to a set of pointings and MSA configurations.) 

Updating NIRSpec MOS Observations for flight execution (coming soon):  NIRSpec MOS observations will not be flight executable at proposal submission time. After a proposal is accepted by the time allocation committee (TAC), the MOS observations are placed onto the Long Range Plan (LRP) and an execution orient and corresponding observing window are assigned. A second stage is necessary to replan NIRSpec MOS visits for flight execution readiness, to ensure that science targets are properly aligned in their MSA observing shutters. Target acquisition parameters are defined during this flight update process. See the description of the NIRSpec multi-phase MOS observing process in NIRSpec MOS Operations.

 The MSA Planning Tool: a basic overview 

The basic steps for creating a MOS proposal in APT are as follows (New in APT 28.0!): 

  1. Create and upload a complete catalog of sources.
  2. Define appropriate candidate sets with primary sources and filler sources.
  3. Navigate to MPT at the Observation Folder level in APT.
  4. Use the 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.
  5. Use MPT to assess the quality of the Plans, and arrive at an estimate of the sample size that can be proposed. This is done in the MPT Plans tab.
  6. Create an observation using the preferred plan. Observations created using the MPT will send pointing positions, MSA shutter configurations, and instrument setups to the MOS template.
  7. Fill out the remainder of the Observation template, including exposure parameters, and  ETC Workbook IDs. Select whether confirmation images are desired.

  8. Run the visit planner, and submit!  (MSA Target Acquisition does not have to be defined for proposal submission, but will need to be included for flight-ready program updates.)

Note that when starting from scratch, there will be an existing observation already present in the Observation Folder. It is a dummy observation that should be deleted. It is advisable to delete the dummy observation prior to creating an observation from an MPT Plan. That will allow MPT to start fresh with a new "Observation 1".

The detailed steps for creating MOS proposals with MPT are described in detail below and in the NIRSpec MPT - Catalogs, NIRSpec MPT - Planner and NIRSpec MPT - Plans articles. 

In addition to the automatic MPT optimization options described in the prior links, it is possible to use the MPT in a Manual Planner mode. For extended or moving targets, the MSA quadrant field points can also be used with (for example) a user configured long slit of MSA shutters.

Note that loading an existing APT program containing an observation designed in MPT may take a long time (several minutes, or even tens of minutes). This happens when the catalog is large and if there are many saved plans pr several MSA configurations. Please allow the process to finish. We hope to improve load times in APT 27.2.

Accessing the NIRSpec MSA Planning Tool

For information on APT observations, proposers should read the article APT Observations. Starting from a new APT application in the Form Editor, choose 'New JWST Proposal' in the pull-down menu at the top left of the APT window called 'New Document', as shown in Figure 1, section 1 and 2. An APT Tree Editor will appear on the left side of the APT GUI window, as shown in Figure 1, section 3. The first item in the tree is 'Proposal Information' which can be filled in at any time before proposal submission. The next item, 'Targets', should be left empty—it will be populated automatically when we create MSA observations. Therefore, we proceed directly to Observations. Select 'Observations' in the Tree Editor. The only option is to click on the 'New Observation Folder', which will appear in the Tree Editor as shown in Figure 1, section 4. When the folder appears it will open in the 'Observation Summary' view. 

Figure 1. Loading the MSA Planning Tool in APT

Flow for opening the MSA Planning Tool from within APT. (1) Open APT in the Form Editor mode; (2) Select New JWST Proposal under New Document; (3) Select Observations and create a New Observation Folder; (4) select the MSA Planning Tool pane from this view.
 In the Observation Folder, there are two upper-level tabs: the 'Observation Summary' and 'MSA Planning Tool' as shown in Figure 2. 
For MOS planning, select the MSA Planning Tool tab. In this pane three lower-level tabs are displayed: 'Catalogs', 'Planner', and 'Plans'. These tabs refer to three panes in the MSA Planning Tool. Initially, you will see the Catalogs pane for ingesting a source catalog. The other tabs provide access to the Planner pane and to the Plans pane. The panes are organized from left to right in the order of the workflow required to create an observation. The lower-level tabs accessible from this page are briefly described in Table 1.

Table 1. Description and access links to lower-level tabs Catalogs, Planner, and Plans

Lower-level tab

In this section the observer imports a catalog containing sources of interest. Only one Catalog should be used to create plans, and eventually, an Observation.

It should contain a complete list of sources in the field, including: primary and secondary science sources.

Users are also able to create candidate sets in this area. Candidate sets used for planning must be derived from a single Catalog.


In this section the user defines detailed properties of the observation and configuration of the instrument. The shape of the slit used in the MSA is introduced here, the dithering strategy is selected in this section, and the exposure type is also defined. Parameters for plan generation and execution are determined here as well.


Once a plan is generated, its details appear listed under the Plans tab. Each plan that is developed can be accessed through a pull-down selection at the top of the Plans pane. Statistics of the plan are presented as well as a detailed list of the calculated pointings.

It is under this tab where the observer can create an observation based on a selected Plan.

Click on the links under Lower-level tab in Table 1 for further details.

NIRSpec MPT terminology 

NIRSpec MOS observing has introduced some new terminology. Some existing terminology in the APT has specific meaning for observations created in the MSA Planning Tool. Table 2 gives the definition of these terms and provides links for more information.

Table 2. 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.)
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. The full parent Catalog can also be a candidate set.

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 targets observed in the MOS configurations.
VisitNIRSpec MOS APT Visits within an observation are created by the MPT after clicking "create observations". Visits are observing components 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 observations" on a single preferred Plan. The NIRSpec MOS observation template is populated with the observing parameters of a single selected Plan. NIRSpec MOS observations must all be created using the same parent Catalog. 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 SetSubset of sources from the parent Catalog that are observed in all exposures over a complete set of the nods and/or dithers specified in the MPT. A target set can use multiple MSA configurations. 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

Indicates the five choices for the limiting shutter centering margin 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 in 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 open science shutter slitlet configuration (pattern of open shutters to form spectral slits).

There are three available options for acquiring NIRSpec MOS confirmation images in the 'Obtain Confirmation Image' pulldown selection:

  • No (default): No MOS confirmation images through the open/closed slitlet configurations 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 MOS open shutter pattern and science filter are configured. These images can provide verification of target positioning within the first science slitlet 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 MSA shutters into a new open/closed slitlet pattern, 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 spectral shifts can occur between multiple MOS spectra acquired with a confirmation image in between exposures.

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 3. This option should be selected after observations are created in the template by using the MPT.

Figure 3. Confirmation images in the MOS template

The Confirmation Images option tab in APT.


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



Latest updates