NIRSpec MPT - Plans

The Plans pane in the MSA Planning Tool (MPT) provides the user with a view of observation planning results from the MPT, including statistical information about the generated configurations. It is here where plans can be merged and observations are created from selected plans. Observations created in the MOS template, entirely without the use of the MPT Planner, can also be examined in the Plans pane of MPT.

On this page

The Plans pane in MPT

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

Once a Plan is created using the Planner in the MSA Planning Tool (MPT), the user can review the results in the Plans tab. This tab contains information and tools to help assess the created Plan. Plan statistics, like the total number of sources observed, the number of exposures a particular source appears in, or the positions of each source within their shutters in an MSA configuration can be evaluated before creating a final observation.

The MPT Plans tab has the format shown in Figure 1, where 5 sections are highlighted in red. These are described in detail below.

Figure 1. The Plans pane

Section 1. Plan summary  

This section shows a list of Plans. Typically, these are Plans created natively in the MPT. However, it is also possible to examine an observation created in the MOS observation template as a new Plan by highlighting it in the tree editor while viewing the MPT Plans pane. This feature allows users to quantitatively compare observations as Plans alongside other MPT-generated Plans. 

The columns in the summary table show the number of MSA configurations and exposures in the Plan, as well as the number of Primary and Filler sources that are observed. In the second to last column, the Export button is a convenience feature that allows the entire Plan to be exported, so that it can be easily used in another proposal. In the last column, the Replan button is a convenient way to send the planning parameters for the given Plan back to the Planner for making a new Plan, perhaps with some tweaks.

Several Plans can be saved in the same APT file. To view the details of a Plan, first select it by highlighting the row in the Plan Selection table. The sections below (Sections 3 and 4) in the Plans pane will then show the details of the selected Plan. Selecting multiple rows in this table allows multiple Plans to be examined and compared. Multiple Plans can also be highlighted here and merged into a single observation (see Section 2, below). Note that this merge Plans feature can help to save visit overheads, but can only be done if all selected Plans have been derived from the same parent MSA Catalog or its daughter candidate sets, and have the same aperture position angle. This includes both custom MOS Plans designed at the MOS Observation level in APT and MPT-generated MOS Plans.

Section 2. Plan operations

Section 2 contains 5 buttons:

  • Create Observation
  • Update Observation
  • Import Plan(s)
  • Describe Plan(s)
  • Delete Plan(s)

Create Observation

This button can be used to create a new observation from a selected Plan or multiple selected Plans. MPT will send the pointings and configurations to the observation template, and automatically bring up the new observation in the Form Editor. At a minimum, the exposure parameters will need to be filled out. But users may wish to further customize their observation by adding or deleting exposures, adding confirmation images, including special requirements, or designing NIRCam or MIRI parallel images. Creating an observation from MPT will construct visits within the observation. The visit structure will depend on the list and order of pointings in your observation, the length of the exposures, and the visit splitting distance for the observation pointing. You may learn more about this in the article APT Visit Planner. To return to the Plans pane in MPT, click the MSA Planning Tool icon in the tool bar at the top of the APT window. (Likewise, you may return to the observation template view by clicking the Form Editor icon.)

Update Observation

Update observation is similar to Create Observation except this button will send Plan information to an existing observation, overwriting any previously existing data in the observation template. This feature's primary use is intended for updating an older observation from the proposal after replanning at an assigned Aperture PA in preparation for the MOS program update submission.

Import Plan(s)

This button allows users to import one or multiple Plans that were previously saved using the Export buttons shown in section 1.

Describe Plan(s)

This button brings up a window listing the parameters used in the highlighted Plan.  Multiple plans can be highlighted and the pop-up will contain the parameters used to plan all of the highlighted plans.

Figure 2.  Sample output from "Describe Plan(s)" button

Delete Plan(s)

This button allows the user to discard the selected Plan. In cases where many test Plans have been created, deleting unused Plans can improve APT performance. In particular, opening a saved APT file can take a long time when it contains many MPT Plans.


  • MPT-created observations are linked to the Plans used to make them. The Plan or Planshould not be deleted if they were used to create an observation in your program, unless the observation has first been deleted. 
  • MSA observations created with MPT cannot be copied and pasted to another observation in the same APT folder, or to another APT folder.

After the Plan is saved, and an observation is created from it, there is also a mechanism for saving the planned source info from exposures made with the MSA Configuration Editor or those automatically generated using the MPT. The target positions, pointing, shutter ID and shutter positional 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.

Section 3. Pointings

The MPT generates configurations based on the parameter Number of Configurations defined in the Planner pane. For the example shown in Figure 1, 36 exposures were generated: 3 nods each for 4 gratings at 3 primary dither points. These 36 exposures are listed in the Pointings table (Figure 1, Section 3) with names that concatenate the MSA configuration number and exposure number and nod number. For example, in this case we have 3 configurations—c1, c2, c3—for the different primary dither points. Each has 4 exposures (e1, e2, e3, e4) for the 4 grating selections, and 3 nods. Note that the ordering of exposures changes the MSA configuration least rapidly. A series of nods is executed before the grating is changed, and all gratings are executed before the primary dither point and MSA configuration are changed. For each exposure listed here, the Right Ascension, Declination, and Aperture PA are shown, along with the Grating/Filter pair to be used in that exposure.

The Target set size indicated on each exposure line gives the number of targets in the exposure, and the Total Weight indicates the sum of all target weights in the exposure, including the fillers and contaminants. (The Weight of each target is assumed to be 1 if target weights are not present in the MSA Catalog or are not used during planning). Some of the targets in each exposure may not be found in other exposures (e.g., if they are Fillers, or even Primary sources in a case where the user had multiple dithers and selected Partially-Completed Sources in the Planner); therefore the Total Weight may be different for different exposures in the list. Each exposure can be visualized using the Show button. When Show is clicked, a pop-up window will open showing the MSA Shutter View with source positions overlaid.

MSA Shutter View

Figure 3 shows the MSA Shutter View of a configuration. In the MSA Shutter View, the 4 MSA quadrants are shown. From left to right and top to bottom, the quadrant ID is : 3, 1, 4, 2. Over-plotted are the Primary sources (green), the Filler sources (blue), and the Contaminants (black). A source is classified as a contaminant if it is a source in the Catalog that falls into an open shutter but is not the source that the shutter was intended for.

Tables 1 and 2 explain the color codes for shutters and sources, respectively.

Figure 3. MSA Shutter View

This view shows a sketch of the source positions in the MSA plane. Note that stuck-closed shutters and shorted rows and columns are shown in grey, and sources appear as filled circles in blue (Fillers), green (Primaries) and black (Contaminants) symbols. Light orange shutters are areas which have been masked out to prevent spectral contamination from sources in dark orange slitlets (seen in zoomed view in Figure 4).

MSA Shutter View tips and tricks:

  • From the MSA Shutter view, clicking on the parent MSA Catalog or a Candidate Set in the list near the bottom of the window will toggle the display of additional (unobserved) sources from those lists. Unobserved sources will appear as small square symbols.
  • Zooming in to the shutter level, as shown in Figure 4, is accomplished by clicking the right mouse button and dragging downward. This is usually enabled on a trackpad by using two fingers at once and dragging in a downward motion. Use the upward motion to zoom back out. Another option is to click Command-"+" to zoom in, Command-"-" to zoom out, and Command-"0" to reset or re-initialize the display. Using the arrow keys to zoom in and out is another possible option.
  • Note that hovering with the mouse over a shutter will display the shutter location in the MSA (quadrant, shutter ID in dispersion, shutter ID in cross-dispersion). Hovering the mouse directly over a target symbol will display the Source ID from the input Catalog. 

The MSA Shutter View grid is rendered as an exact fixed grid, which is not strictly accurate. This means that the source positions are correctly computed in the MSA plane, but that they are not rendered exactly correctly with respect to the regular grid in the MSA shutter view.  

However, the positions are  accurately rendered in the Collapsed Shutter View, because that view does not involve any grid spacing assumptions in order to render the view.  The positions within a shutter are accurately computed and presented in the MSA Target Info file, as well. The origin of in-shutter positions is the (mid-bar) upper right corner of each shutter in the MSA Shutter View. 


Figure 4. Zoomed section of the MSA Shutter View

Zooming to the micro-shutter level in the MSA Shutter View will reveal individual shutters. Sources are plotted with colors that distinguish them as Primaries, Fillers, or Contaminants. See Tables 1 and 2 for a description of the colors and symbols.

An MSA configuration can be exported using the Export to CSV button. An ASCII file of comma-separated values is produced that has values of "0", "1", "s", or "x" for each commanded-open, commanded-closed, failed-open, or failed-closed shutter, respectively. These exported MSA configuration files can be shared and/or imported into other proposals using the Import Configuration(s) button in the MOS observation template.

The failed-open and failed-closed shutter positions are inherited from the current MSA shutter operability reference data that the MPT utilizes during Plan creation. APT retrieves the current reference file from a database. The reference data will be monitored on a regular cadence, and these reference files will evolve over time.

Table 1. Shutter color and meaning

Shutter colorDescription/ meaning
Light orange

This color indicates shutters that were masked during the creation of the MSA configuration.  

Adding a new source slitlet anywhere in this area will cause spectral contamination on the detector of the added source's spectrum and spectra of other existing targets in the MSA configuration.  

The number of shutters in light orange indicates the level of completeness in the utilization of the MSA.

OrangeThe shutter is commanded open and part of the slitlet.
Light redThe area marked in this color is impacted by the presence of a failed-open shutter (several rows may be impacted completely or partially.)
RedShutter is failed-open.
GrayShutter is either failed-closed, vignetted, or is in a shorted row or column. These types of shutters are avoided during planning. They cannot be used in any observation.

This area is available. MPT did not find sources to fill this space.

Only the white areas of the MSA configuration would be available to add extra background shutters, for example, with the MSA Configuration Editor.

Table 2. Symbol color and meaning

SymbolDescription/ meaning
Green dotSource from the Primary Candidate List that is a planned MSA source in the displayed exposure.
Blue dotSource from the Filler Candidate List that is a planned MSA source in the displayed exposure.
Black dotContaminant source present on this exposure.

Collapsed Shutter View

Another exposure view offered in the pop-up window is called the Collapsed Shutter View which can be seen by clicking the Collapsed Shutters icon as shown in Figures 3 and 5. This view (Figure 5) shows each planned source's position in its own shutter, all collapsed together into a single virtual shutter. Clicking on a symbol in this view will indicate the source ID and will highlight it in magenta in the MSA Shutter View, and the Targets table in MPT (Section 4). The source will also be highlighted in other exposure views from the Plan if it is observed.

Figure 5. Collapsed shutter view

This view shows a sketch of observed targets in an exposure showing the position of the sources, all plotted within a single "virtual" micro-shutter. See Tables 1 and 2 for a description of the colors. The grey bars represent the bars between shutters in the MSA. The bar width shown here includes the portion associated with adjacent shutters. The white dashed line represents the shutter centering constraint used in planning.

Aladin Viewer

The APT Aladin Viewer is APT's image viewer.

At the bottom of the window there is a button labeled Add shutters plane to Aladin (shown in Figures 3 and 5). Clicking this button creates an Aladin plane displaying the slitlets used for this exposure as shown in Figure 6The shutters in this case are drawn in green while the sources from 2 candidate sets are shown as red and blue crosses.

All Aladin features are available to the observer. One useful feature consists of overlaying the sources and slitlets on top of an actual image of the region of interest. In order to load an image from your computer, simply click on the Server selector form—this is the yellow "file" icon on the top left corner of the GUI as shown in Figure 6. It will open a new window shown in Figure 7. Select the tab File on the top of this window. From here you may browse to the location of the FITS file in your computer and select it. To display it in the Aladin Viewer, click on the "SUBMIT" button at the bottom of the window.

Downloading images from the server to Aladin can sometimes cause APT to come to a halt if the image is large. Make sure to save your APT session before attempting to load an image, or load the image before running MPT.

Figure 6. Displaying slitlets using Aladin

Figure 7. Aladin server selector

The File tab is shown here for selecting a FITS file from your computer. There are several image server options available from the menu on the left side of the window. Catalog servers are listed on the menu in the right side of the window.
Aladin visualizes the ingested data in a stack of "planes" located to the right of the window. Each plane represents a catalog or image or other graphic. It is possible to reorder the planes by clicking and dragging them. The user's eye is on the top of this stack and sees all activated planes by transparency. Figure 8 (left) shows an example of the Aladin Viewer where a candidate set is displayed and the 3-shutter slitlets are over-plotted. In Figure 8 (right) we display the HST image that was used to create the parent Catalog as background. The same sources are displayed and the slitlets are also shown for comparison. Note that the image must be below the graphics in the stack. Planes can be clicked on or off for display, and their transparency can be adjusted with the tiny slide bars on the plane icon in the stack. A more complete description of Aladin in APT is found in the article APT Aladin Viewer.

Figure 8. Displaying slitlets using Aladin

Aladin allows the user to display "planes" that contain useful information such as background image(s), catalog(s), and MSA slitlets. These can be turned on or off.

Section 4. Targets

Section 4 contains basic statistics about the Plans and target sets. A target set is the subset of sources from the input Catalog that are observed over a complete set of dithers specified in the Plan. During Plan generation, one or more target sets may be created depending on the number of MSA configurations the user specified. For example, if a set of dithers requires 3 MSA configurations to complete a target set, then if the user had specified 6 MSA configurations as the Number of Configurations in the NIRSpec MPT - Plannerthe final Plan would contain two target sets with unique Primary sources.

Target results can be filtered in different ways to help users assess their Plans: 

  • First, click to highlight exposures you are interested in within the Pointings table (Section 3) (e.g., all exposures for the first target set). The NIRSpec MOS observation sequences are ordered to minimize the reconfiguration of the MSA, with nod position changing most frequently from row to row in the table, then grating, then MSA configurations (for each primary dither). 
  • Next, select the Target Set Operation that you would like to perform on the selected exposures, along with a Target type (see Figure 9)

Figure 9. Target Set Operations

For example, suppose you have a Plan constructed with a single primary dither, and a set of 3-shutter nods at each primary pointing. It would have 2 MSA configurations, each with 3 exposures. If you are interested in seeing just those Primary sources that are successfully observed in all the dithers, highlight all the exposures, choose Target Set Operation = Targets in all selected exposures, and select Target type = Primary targets.

The results of the filtering step will be shown in the "Targets" table below the filters. The number of successful sources will be summed and displayed, and the table will show an "x" indicating which exposures contain a given target.

MPT has an added feature that could be useful for visualizing the location of sources on the MSA or within slitlets: If the MSA Shutter View or Collapsed Shutter View are open, clicking a source in the Targets table will highlight it in magenta on the viewer. Likewise, clicking on a source in the viewer will highlight it in the Targets table.

Section 5. Coverage

A histogram depicting the number of targets as a function of the number of exposures it appears in (the coverage) is also plotted at the bottom of the Plans pane. This plot is useful to rapidly assess the completeness of the sources in the Plan. It is especially useful when assessing multiple Plans together. The Send to Aladin button shows the targets using the Aladin interface as described in section 3.

Below the histogram, section 5 includes timing and other results used for testing purposes (not shown in Figure 1). It lists the number of configurations that were generated in the Plan, the number of targets that are observed, the durations, and a score for the Plan. The iteration duration is the time it took to create the first target set, and the Planning Duration gives the total time it took to make the Plan. The score is a number used by MPT to quantify and help select the most successful Plan. Plan assessment should not rely on this value. Instead, the Number of Primaries and Secondaries reported for the Plan, and the Total Weight of each exposure in the Plan should help the user identify a preferred Plan.


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

Latest updates
    Added figure 4 and renumbered other figures.

    Described MSA Shutter View in-shutter target position issue

    Reviewed and minor edits made.

    Clarified a number of sections and re-organized material for readability.

    Added description of pushing Observations to a Plan for examination in the Plans pane, and plan merging of like or unlike plan types to save overheads.

    Updates for mpt-rewrite. 
Originally published