Page tree

Versions Compared


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

Content Block

The roadmap to plan a JWST NIRSpec MOS observation using the MSA Planning Tool in the APT Template is introduced. New MOS related terminology is defined. 

Content Block


See Also: NIRSpec MOS proposal checklist

All proposed JWST observations are created and verified in the Astronomer's Proposal Tool (APT). Additional information is provided by the article JWST Astronomers Proposal Tool Overview.

The NIRSpec MOS proposal and observing update process

Proposals for the NIRSpec MOS Mode: The NIRSpec 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 and create observations that request the observing time necessary to execute the science.

An outline of the MOS proposal process and instructions to use the MPT are linked in the NIRSpec MOS proposal checklist.

The present article covers the following sections:

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 interaction process 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 in this flight update process, not in the proposal. See the description of the NIRSpec multi-phase MOS observing process in NIRSpec MOS Operations.

 The MSA Planning Tool: a roadmap 

In NIRSpec's Multi-Object Spectroscopy observing mode it is possible to obtain spectra of many sources at the same time. Early in the development of NIRSpec observation planning, it became apparent that specifying MOS slits on science targets using the fixed grid of shutters in the Micro-shutter Assembly would benefit greatly from an automated software planning tool. In this article we describe how to use the MSA Planning Tool (MPT) that is built into the Astronomer's Proposal Tool (APT) for NIRSpec MOS planning. Additional information on the MOS hardware is described in the article NIRSpec Micro-Shutter Assembly (MSA).

In brief, the steps to create a NIRSpec MOS observation using MPT are as follows:

  1. Create and upload a complete catalog of sources.
  2. Define appropriate candidate sets with primary sources and filler sources.
  3. Use the MPT Planner to create a variety of observing Plans. For MPT to work, the user must be connected to the internet so MPT can check whether a selected aperture position angle is feasible.
  4. Assess the quality of the Plans.
  5. Create an observation from a selected Plan. 

Observations created using the MPT will send pointing positions, MSA shutter configurations, instrument setups and exposure information to the MOS template as a new Observation. The information from MPT automatically populates the template fields to estimate the science execution time and derive the appropriate information for observation overheads.


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 steps for using the MPT for MOS proposals 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.


this is from Alaina:

and somewhere in this table...

an observation can contain only one plan. 

 but a plan can contain multiple configurations.

 the observation/plan may be split into multiple visits, each requiring TA.

 Maybe link to observatory level documentation on visits/observations. Even though they are not nirspec specific, I think it is important to show people how everything nests.

 I wonder if we need a flow chart or something?

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 container

Figure title

Figure 1. Loading the MSA Planning Tool in APT

Image Modified

Figure caption

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. 

Figure container

Figure title

Figure 2. MSA Planning Tool

Image Modified

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 container

Figure title

Figure 3. Confirmation images in the MOS template

Image Modified

Figure caption

The Confirmation Images option tab in APT.


Content Block


Related links

JWST User Documentation Home
NIRSpec Micro-Shutter Assembly (MSA)
NIRSpec Multi-Object Spectroscopy
NIRSpec MOS Proposal Checklist
NIRSpec MPT: Catalogs
NIRSpec MPT: Planner
NIRSpec MPT: Plans
MPT Catalogs - Examples
NIRSpec MOS Confirmation Images
NIRSpec MOS Dither and Nod Patterns



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

Content Block

Multiexcerpt include
MultiExcerptNameAPT icon and name
PageWithExcerptMR:APT icon and name

Content Block



Last updated

Published June 2, 2017


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