NIRSpec MPT - Manual Planner

The JWST NIRSpec MSA Planning Tool (MPT) Manual Planner is designed to help the user manually create new plans and modify existing plans.

On this page

The MSA Planning Tool (MPT) Planner is designed to automatically create optimal plans, but it is also possible for the user to create plans manually.  Checking the Manual Planning1 box at the top of the Planner tab of MPT results in the view shown in Figure 1. 

Figure 1. MPT Manual Planner

The Manual Planning template has four sections that are described in detail below.

1  Bold italics font style is used to indicate parameters, parameter values, and/or special requirements that are set in the APT GUI.

MPT Section 1. Planning angles

Aperture PA (APA)

A given NIRSpec MSA observation must be executed at a specific telescope orientation angle so that the selected sources will fall into the open shutters as planned.  Because of the telescope's orbital position and sunshield constraints, a given orientation may only be possible for limited periods during the year or not available at all.  The Target Visibility Tools can be used to determine the range of feasible orientation angles for a target throughout the telescope's orbital cycle.

For most NIRSpec MOS observations, it is recommended to experiment with several different feasible Aperture Position Angles prior to initial proposal submission. The submitted APA is used to create place-holder or "planning visits" with MPT. Once a proposal is accepted, it will be assigned a fixed orientation and a corresponding window of time when observations will be made. 

For proposal submission, use any feasible APA from the orientation angles provided by the JWST Target Visibility Tool for the time of observation. For final program submission, use the fixed orientation APA that has been assigned to your observation by the schedulers at STScI. This assigned angle will correspond to one or more plan windows for execution in the scheduling timeline.

The APA (an angle between 0 and 360 degrees) specifies the orientation of the cross-dispersion axis of the MSA aperture measured from North in the counterclockwise direction. Figure 2 shows how this angle is measured on the sky. The "Y" axis represents the cross-dispersion direction of the MSA.

Figure 2. Aperture position angle

The black arrow represents the North direction. The blue arrows represent the direction of the Ideal X and Y axes. Dispersion is along the "X" axis. The Aperture Position Angle (θ) is shown as measured in the sky.
Programs that have an orientation or timing special requirement added to the observation can restrict scheduling opportunities. Most NIRSpec MOS programs should be submitted without added orientation restrictions, in order to allow the schedulers to find suitable windows for them. Also, when the proposal is submitted, the observer should explicitly add an "ON HOLD for aperture position angle assignmentspecial requirement to their NIRSpec spectroscopy observations.

True angle to target

The True angle to target field appears in the Planner, but is greyed out and cannot be changed by the userThis is the angle between the telescope's velocity vector at the center of the planning window and the telescope pointing.  It is used to make small corrections to source positions at the MSA resulting from the velocity of the spacecraft.

The True angle to target offers a quick way to check target visibility:  its value will not update if the selected APA is not feasible.

MPT Section 2. Primary Candidate List  

The Primary Candidate List is a candidate set that should be defined in the NIRSpec MPT - Catalogs pane.  In manual planning mode, select the appropriate list from the pull down menu.

MPT Section 3. Exposure setup  

In section 3 of the Manual Planner the observer defines the exposure specification. Click the ADD button to add a new exposure specification. Each new exposure specification results in one or more new exposures. The number of new exposures resulting from an exposure specification is determined by the dither pattern specified

The JWST Exposure Time Calculator (ETC) should be used to determine the best exposure parameters to optimize the signal-to-noise of your observation. An exposure is configured by setting the Grating/Filter combination, Readout Pattern, Number of Groups, and Number of Integrations.  

Users should ultimately use the JWST Exposure Time Calculator for all sensitivity calculations.

The exposure parameters that the observer needs to define are listed in Table 1.

Table 1. Description of Science Parameters for a given exposure

Exposure ParameterDescription
Grating/FilterSelect a grating/filter combination from the pull down menu. The article NIRSpec Dispersers and Filters describes all the available combinations for NIRSpec observing modes.
Readout Pattern

Each exposure consists of a set of one or more integrations. Integrations consists of a set of nondestructive reads of the detector.  

The detectors can be read in different ways. The available patterns are NRS, NRSRAPID, NRSIRS2, and NRSIRS2RAPID. These patterns are described in full detail in the article NIRSpec Detector Readout Modes and Patterns. The default pattern is NRS.

Select the pattern that best suits your observation.


The number of groups in an integration. The number of groups, together with the Readout Pattern (i.e. the number of frames in a group) will determine the length or duration of an integration, using the specified options for averaging or not averaging frames.

Integrations/ExpThe number of integrations comprising an exposure, where an integration is defined as a set of non-destructive reads.
AutocalThis option is available to automatically add calibration exposures to a science exposure.  For the MOS, the options are NONE, WAVECAL, FLAT, and BOTH. NONE is the default and is recommended.
ETC Wkbk.Calc IDThe user should enter the ETC calculation ID from the associated ETC Workbook. See note below.

Exposure specifications may be reorganized or removed as needed, using the New, Copy and Link, and Remove buttons, and the arrows at the left of the 'Exposure Setup' box. Each exposure specification will be used for each of the Pointing and Configurations specified below.

MPT Section 4. Pointing/Config setup  

Configurations and Pointings

NIRSpec MSA configurations are described by a configuration file.  Those configurations can be created with the Manual Planner as described below, or ingested to the Manual Planner from the automatic MPT Planner. It is possible to save a configuration off-line by exporting it from APT. A configuration file may also be imported into APT using the MPT Manual Planner. The only format supported for importing or exporting an MSA configuration file is comma-separated values (.csv).

Click New, Copy and Link, and/or Remove (as shown in Section 4 of Figure 1) to create or delete the configurations you want. New will create a new MSA configuration entry in the next row of the table. Table rows can be rearranged using the up and down arrows to the left of the table. Copy and Link can be used to make a copy of an existing configuration (first select the entry you want to copy).

Caution! Any changes made to the configuration (including renaming it) will apply to all table entries using that configuration.  

Copy and Link is provided for users who wish to create a set of offset exposures from a Base Pointing, and to save overheads by linking them as a set of dithers applied to the base pointing. The Base Pointing, Dispersion Offset, and Cross-Dispersion Offset columns can be edited directly in this table. Offsets are in units of shutters.  

By clicking on Edit config in the right column of a table entry, a window will pop open displaying the MSA shutter view for the selected MSA configuration. This window is the Manual Editor.

As an example, to create a set of nodded exposures that use the same MSA configuration in the Manual Planner -

  1. Click New to generate a new MSA configuration.
  2. Type in the base pointing.
  3. Type in "0.0" for the dispersion and cross-dispersion offsets.
  4. Click Copy and Link twice to create two new entries in the table. These will use the same MSA configuration as the first entry.
  5. Edit the second entry cross-dispersion offset to have a value of 1.0 (exactly 1 shutter up from the base pointing).
  6. Edit the third entry cross-dispersion offset to have a value of -1.0 (exactly 1 shutter down from the base pointing).
  7. Click Edit config in the right column of the first table entry (at the base pointing). Wait for the Manual Editior window to appear.
  8. Create the configuration you want by opening or closing shutters in the Manual Editor.
  9. When finished, click OK.
  10. To save this new Plan, give the plan a unique name, and click Finish Plan at the bottom of the main Planner window.

Manually editing a configuration

When the Manual Editor is open, the shutter view is presented with the sources of the candidate list used to generate the configuration, as shown in Figure 3.  Other lists may be displayed by selecting them from the Parameters tab of this window.  Note that all sources appear as black plus symbols in the Manual Editor, whether they are in configured slitlets or not.

Figure 3. Manual editor

The configuration of shutters in the four MSA quadrants is shown, using the color convention introduced in NIRSpec MPT - Plans.  Sources in the Manual Planner are always colored black. 
It is possible to zoom in to view individual shutters in the Manual Editor. Zooming in or out is accomplished by depressing the right mouse button while dragging up or down. This is usually enabled on a trackpad by depressing two fingers at once and dragging in an upward or downward motion. Hovering the mouse over a single micro-shutter provides its position in the MSA and its state (commanded open or closed, stuck open or closed, etc.)

Individual operable shutters may be commanded opened or closed with a "Left Click" on the mouse.  Also available are the Open all and Close all buttons. The metadata for each open shutter is tracked during load, so opening all shutters in the Manual Editor will be slow and is not recommended for casual use. The Manual Editor should be used to open shutters that correspond to sources of interest, as shown in Figure 4. There is a shortcut to make a long slit configuration: point the mouse at a column of shutters, and use "Ctrl+Left Click" to open (or close) the column of shutters.

For users who wish to observe moving targets with a long slit configuration at one of the Quadrant 4 Field Points in the MOS Spectroscopy template using WATA, columns can be opened in the following locations:

  • Q4 Field Point 1 corresponds to shutter q4d615s196
  • Q4 Field Point 2 corresponds to shutter q4d533s244

The  MOS Custom Configuration Process article describes the process for extended sources.

Figure 4. Manually editing the configuration file

Detail of the editing process using the Manual Editor. In this example, six shutters have been opened manually (shown in dark orange) creating slitlets around two sources. Note that the rows corresponding to those shutters will change from white to light orange to signify that they should be avoided for adding any other sources. See the note below about PRISM masking.

Options exist to export and import MSA configurations. These options, however, are intended for expert users who wish to manipulate MSA configurations outside of APT. The MSA can only be configured after applying corrections to source positions at the MSA affected by instrument and telescope geometric distortions. A completed MSA configuration can be exported using the Export to CSV button. One can be imported with the Import CSV button.  Export to CSV produces an ASCII file of comma-separated values that can be shared and imported into the Manual Planner with Import CSV. The exported CSV file has values of '0', '1', 's', or 'x' for each commanded open, commanded closed, failed open, or failed closed shutter, respectively. Additionally, an image of the configuration can be saved in SVG format.

APT files themselves can be shared;  this is the best way to share plans and configuration details.  At the bottom of this article is a tip for saving the target info from a plan to a table that can be exported and examined outside of APT.  This format is more accessible and useful for tracking observed target information.

There a a few known problems with the Manual Editor.

 Click here for current issues...

The Manual Planner does not differentiate between primary or secondary (Filler) targets because that concept does not apply here. Sources are currently shown as 'Contaminants' in the Manual Planner. This should be kept in mind when reviewing Plan results in the Plans pane of MPT. This problem does not affect observations, however. It is expected to be fixed in later versions of APT (in APT 28.0 or later).

For PRISM exposures, the masking shown in light orange in the Manual Editor is incorrect in the dispersion direction. Masking is intended to indicate areas to avoid when adding new targets to prevent spectral overlaps on the detector. We expect this will be fixed in APT 28.0 or later. The user is not prohibited, however, from creating slitlets for new targets in the masked area. For PRISM exposures, the slitlets should be separated by at least 156 shutters in dispersion to prevent spectral contamination. The equivalent distance to factor in for the MSA gap is 86 shutters. This separation will allow up to 4 sources per row (depending on the source density and spatial distribution).

It is easily possible to unintentionally click open a shutter in the Manual Editor. This can cause contamination of target spectra if the unintended shutter was opened within the masked region of another intended target. A warning will be added in later versions of APT (APT 28.0 or later) when this happens, but for now the user is advised to review the MSA configuration before finishing the Plan to avoid contaminating the spectra of an intended target.

Continuing with the Manual Editor window features - three tabs are located at the bottom of the window: Pointing, Parameters, and Collapsed.

Under the Pointing tab (Figure 5) it is possible to give a name to the configuration, and specify appropriate pointing equatorial coordinates. Base Pointing RA and Dec values are required before the MSA configuration can be saved. If other MSA configurations have already been designed, their Pointing and Configuration will be available from the pull-down menus Copy Existing Pointing and Copy Existing Configuration. If the Base Pointing coordinates are within the Catalog area, the source positions from the Catalog will appear in the shutter view.  

Figure 5. Pointing tab

Detail of the Manual Editor. The Pointing tab allows the user to view the base pointing and offsets specified in the main window of the Manual Planner, or to specify or change the equatorial coordinates (RA, Dec) and assign a unique name to the MSA configuration. Offsets can be specified or altered here, and it is possible to select an existing pointing or MSA configuration from already existing ones.

Under the Parameters tab, a Candidate set must be selected, even for plans generated with the Manual Planner. This implies that a Catalog is required as well. To further ensure that the standard calibration pipeline will not fail, there must be targets in planned slits. Figure 6 shows a detail of the Parameters tab design.  

Figure 6. Parameters tab

Detail of the Manual Editor. In the Parameters tab is shown the list of sources selected in the Manual Planner as described in Section 2. It is possible to click the Master Background button to indicate the users intent to specify multiple scattered shutters that are to be used for background measurements for all sources observed in the MSA configuration. Typically, background measurements are taken from the adjacent shutters in the same slit as a source.
From the Parameters tab:

  • The candidate set can be changed by selecting from the Candidates pull-down menu to show the positions of other sources near the sources of interest.  
  • The Master Background button, when selected, makes it possible to open scattered shutters in the MSA on areas of the sky that will be used for background measurement and subtraction from target spectra.  
  • The Add shutters plane to Aladin button will display the slitlets of each target in the Aladin viewer.  When returning from Aladin to the main APT window, remember to click 'Form Editor' in APT to see the normal Manual Planner view.

The Collapsed tab view (Figure 7) shows each target's position in its own shutter, all plotted together in a single virtual shutter.  The Source Centering Constraint is selectable, and though it has no effect by itself, it can be used to identify which planned sources fall outside the margin of interest.  These shutter constraints are described in the NIRSpec MPT - Planner.

Figure 7. Collapsed tab

Detail of the Manual Editor. The Collapsed tab shows the distribution of planned sources in a single virtual shutter (i.e. only those targets in shutters which the user clicked open in the Manual Editor window). This view is currently not working but we expect it to be fixed in APT 27.3.
Finally, to confirm and accept this new configuration, click the OK button at the bottom of the Manual Editor window.  This will return you to the Manual Planner view in APT, shown in Figure 1.

Generating a plan

Under Plan Name in the main window of the Manual Planner, assign a name to this manual plan and click Finish Plan.  This will process and generate the plan and direct the user to the Plans pane of MPT, where it is possible to review and assess the quality of the plan. 

After the Plan is saved, and an Observation is created from it, there is also a mechanism for saving the planned target info from exposures made with the Manual Planner or those automatically-generated using the MPT.  The target positions, pointing, and shutter information can be saved to a .csv file. To do so, click on the "File" item from the main menu at the very top of the computer screen.  From the pull-down menu, select Export → MSA Target Info.  This mechanism makes it possible to track target coverage through all exposures of an Observation outside of APT. These files are ASCII and readable by Excel, for example.


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



Latest updates
    Modified warning in MPT Section 4: Pointing/config setup