NIRSpec MPT - Planner

The JWST NIRSpec MSA Planning Tool main interface is presented and described in detail. All steps to create a plan containing targets, slitlet structure, dithering strategies, and exposure configuration are discussed.

On this page

The NIRSpec MSA Planning Tool (MPT) is the official software tool to design a NIRSpec MOS observationThe main purpose of MPT is to optimally plan micro-shutter assembly (MSA) observations, given source positions and the limitations of the MSA. Constraints, such as the bars in between shutters and the inoperable shutters, are fully accounted for in MPT. MPT contains the precise coordinate transformation between the MSA plane and the sky plane, taking into account the distortion of the combined optical path of the telescope and NIRSpec optics.

An overview of the MPT Planner

The purpose of the MPT Planner* is to allow the user to define parameters that are the input to the algorithms that produce the final pointings, MSA configurations, and target sets. An "MSA configuration" is defined as a set of open and closed micro shutters in the MSA. Once a set of Planner parameters are defined, a Plan can be generated. Observers can generate several Plans which are saved when they save their APT file. After assessing the quality of individual Plans, the user can then select one or more Plans from which observations will be made. When an observation is generated, see NIRSpec MPT - Plans, some parts of the the observation template in APT are automatically completed for the user. An observation in APT can be created from one or more plans in MPT.

For MPT to work, the user must be connected to the internet so MPT can check whether an aperture position angle is feasible when the user begins to create a plan.

The appropriate selection of the Planner parameters discussed throughout this article depends on science goals. Consult NIRSpec MOS Recommended Strategies for further advice. For examples of how the choices below affect the results of the Planner, see the Parameter Space article.

After having ingested a Catalog and created a Primary candidate set (and a Filler candidate set, if desired), the user should move on to the Planner tab in the MSA Planning Tool. The Planner is shown in Figure 1. 

Reminder:  MPT can be accessed from the tool bar, which runs along the top of the APT GUI window.

Figure 1. MPT Planner

*Bold italics style indicates words that are also parameters or buttons in software tools (like the APT and ETC). Similarly, a bold style represents menu items and panels.

MPT Section 1: Candidate lists

The MPT is designed to create plans that use two levels of priority for science sources: a "Primary" candidate list, and a "Filler" candidate list. These lists are created from the input Catalog that was uploaded following the instructions in the article NIRSpec MPT - Catalogs.

The tool will attempt to maximize the number or the summed weight of Primary sources obtained in the configurations it creates. Therefore, these sources will directly influence the pointing selection for both single pointing and dithered observations. The Primary candidate list is required to generate a plan in MPT. At the derived best pointings, MPT will use the (optional) Filler candidate list to fill available areas in the MSA configuration, to observe more sources in each exposure. There is no attempt by the algorithms to complete the sources from the Filler list (i.e. to observe them through all dithers) in the same way that the primary sources are completed. Fillers do not define the pointings, they are only selected to maximize MSA usage. Only the Primary candidate set determines the selected pointings.

Observers should be aware that they should have all sources of interest in a single parent Catalog for a given observation or a set of observations. The candidate lists (Primary Candidate List and Filler Candidate List) are derived from this single Catalog. Using Primary candidates from one Catalog and Fillers from a different parent Catalog will cause errors in APT. Users will not be able to make observations from Plans made with candidate lists derived from different Catalogs.

MPT Section 2:  Aperture Position Angle  (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 JWST 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 (APA) prior to initial proposal submission. The "Planned APA" was that used during planning. Once a proposal is accepted, it will be assigned a fixed orientation (an "Assigned APA") and a corresponding window of time when observations will be made. 

For proposal planning and 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 (containing flight-ready program updates), use the fixed orientation Assigned 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 East of North. 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.

MPT Section 3: Slit Setup

In this section the user defines the shape of the slitlet and the Source Centering Constraint.


The NIRSpec MSA is composed of ~250,000 micro shutters. By commanding open micro shutters, it is possible to create longer slits (in the cross-dispersion direction only) which are referred to as "slitlets". There are four selectable Slitlets, each with a different number of adjacent micro shutters that are open: 1, 2, 3, or 5. The spectrum from a slitlet will be segmented, with bar shadows between the individual shutters making up the slitlet.

Each selected MSA target in a Plan will be observed with the same Slitlet shape and Source Centering Constraint (see below). MPT will not select primary targets with close neighbors that would result in more than 1 primary source per shutter.

Slitlets of any size may be created, modified, or deleted using the MSA Configuration Editor, which is available at the observation level in APT. The MSA Configuration Editor can be used to append a new set of MSA sources to an existing MSA configuration designed with the automatic MPT Planner, for example. Or, it can be used from scratch to design a custom MSA configuration with slits of different lengths for different size sources. It is important however to be careful about nodding when slit lengths differ in the same MSA configuration.

The yellow and black sketch in the Planner, shown in Figure 3, illustrates the options for slitlet length. 

Each open micro shutter, when projected onto the sky, has dimensions of only 0.2" in the dispersion direction by 0.46" in cross-dispersion. These are the internal (open) dimensions. Each shutter is bordered by a bar of width ~0.07", which vignettes a small area of the sky around it. In any given exposure, a particular source may fall anywhere inside a given shutter, or behind the bars. The position of the source with respect to the shutter will affect its observed flux. 

Figure 3: Options of available NIRSpec MOS Slitlet shapes

The available MOS Slitlet shape options are: one, two, three, and five shutters. Open shutters are shown in yellow. These are the only slitlet lengths that are available. If longer slitlets are needed, the MSA Configuration Editor can be used to design an MSA configuration.

Source Centering Constraint

The Source Centering Constraint in the Planner presents five increasingly limited choices for the shutter margin to constrain the positioning of the source within the shutter to help reduce slit losses. As shown in Table 1, the larger the margin, the more limited the area available for centering the sourceIn general, larger margins result in fewer selected targets, although this effect depends strongly on the source density of the Primary and Filler candidate lists.

The default constraint is the Entire Open Shutter AreaThe figures in column two of Table 1 represent a single micro shutter. The yellow area represents the area available to a potential target corresponding to the indicated Source Centering Constraint. The exact dimensions of the constrained area in the figure are not precise, they are just suggestive. The actual applied source centering constraint can be seen as a dashed white line when viewing the "Collapsed Shutter View" in a MOS exposure.

To be included as a successful source in a plan, the source center must fall within the central area of the shutter defined by the specified margin. A more restrictive shutter margin will limit the photometric error, but may also cause the overall efficiency of the plan to drop. This parameter is relevant primarily for point sources, which can suffer from large photometric inaccuracies due to limitations in the pointing accuracy, especially if a source happens to be centered near the shutter edge where the throughput drops quickly. The shutter margin translates to a minimum possible slit transmission of a point source relative to a perfectly centered point source (column 3 of Table 1), anchored at 2.95 μm. Of course, the actual throughput will depend on the wavelength of the observation and the source shape (point vs. extended).

Users observing extended sources should avoid over-constraining the shutter margin since source centering is less critical, and it could decrease the overall number of targets observed per MSA configuration. 

Table 1
. Source centering options within an individual micro shutter.  

Column two shows a sketch of the open micro shutter area (yellow area) for each margin; the black region in the figure represents the margin.  

Source Centering ConstraintFigure Minimum Relative Flux Transmission at 2.95 μm




(sources can be behind the MSA bars)



Entire Open Shutter Area (default)

30% 38


62% 59


75% 72

Tightly Constrained

85% 91

 The source centering constraints were updated in APT 25.4 according to the most precise knowledge of the average shutter dimensions. The path losses at these margins are for a point source. They were measured at 2.95 μm, relative to a perfectly centered source. At larger wavelengths, the PSF is broader, and the slit losses are greater than those at shorter wavelengths. However, the relative slit losses for different constraint margins are less discrepant. The sketches shown in this table are representative only and may not reflect the actual sizes. The margins shown in the last column are measured from the mid-bar position inward, toward the center of the shutter.

As a result of the tiny size of a micro shutter, moderate flux can be lost outside of the shutter. Slit losses depend not only on the location of the source in the slit, but also the wavelength, since the point spread function (PSF) increases with wavelength as shown in Figure 4. The "relative flux transmission" value in the table is the minimum percentage of flux at 2.95 μm that makes it through the MSA shutter, compared to a perfectly centered point source

Figure 4. Slit losses and wavelength

The NIRSpec PSF at 5 wavelengths. The rectangle is the size of a micro shutter. Slit losses and total transmission depend critically on wavelength. The throughput can be affected by diffraction at the aperture edges. These effects depend on the location of the source within the shutter.

MPT Section 4: Pointing Setup

In this section, the observer can define dither and nodding patterns for the observation. Most JWST observations will require dithering and NIRSpec users are encouraged to make use of this feature. Not only is dithering critical for improving the sampling, but it can help to estimate and remove light leakage through the MSA's finite contrast shutters in MOS mode. More information on the advantages of dithering can be found in the article NIRSpec MOS Dither and Nod Patterns.

Nod in Slitlet

The telescope can be repositioned slightly between exposures to place the targets into different shutters within their respective slitlets in an MSA configuration. This is called nodding. If nodding is selected (by clicking the checkbox Nod in Slitlet in the Planner), the same MSA configuration will be used to observe the target in multiple exposures, usually once for each open shutter in the slitlet. In the 5-shutter slitlet, there is also the option of just 3 exposures, with nod positions in the central, uppermost and lowest shutters only. This option, called exposures per configuration is visible only when the 5 Shutter Slitlet and the Nod in slitlet options are selected.

When nodding is selected, the default pipeline will automatically perform a background subtraction using the various nod positions.

Fixed Dithers

In addition to nodding, which moves the telescope very slightly to observe sources in different shutters within their respective slits, users have the ability to add larger dithers

Fixed, or primary, dithers will require a reconfiguration of the MSA in order to re-observe the same targets at a different location in the MSA field-of-view. Fixed dithers are specified in units of integer shutters in the dispersion and/or cross-dispersion direction, and represent average offsets to apply to the next pointing. The offsets are "average" in the sense that each MSA source may move by a slightly different amount between pointings due to optical distortions. The dither algorithm accounts for relative distortions between pointings, so dithers of any size can be specified. There is no limit to the size of the dither that may be specified, but larger dithers may naturally result in some loss of targets due to diminished areal overlap of sources in the quadrants at very large separations. To create a Fixed Dither pattern, simply click the ADD button and define the offsets. Offsets are in units of micro-shutters. Figure 5 shows an example with two added dither points.

For each new dither that is added to the Pattern table in APT, an additional primary pointing will result, along with an associated MSA configuration. This in turn results in an additional exposure or a set of nodded exposures. The number of (MSA) configurations needed to execute the entire set of dithers is computed and displayed beneath the table of dithers shown in the GUI. 

With Fixed Dithers, the default behavior is that all planned Primary sources are observed at all dither points (i.e they are "completed"). Since it is only possible to obtain completed sources in areas of the MSA that overlap at different dither points, this will leave areas of the MSA unused.

An option to improve the use of the MSA real estate is to select Partially Completed Sources in the Planner. In that case, Primary sources observed at some, but not all, dither points will be included in the Plan. This is done iteratively - after determining the best pointings for the dithers from the set of completed Primary sources, MPT will add in Primary sources that appear in n-1 dither points, where n is the total number of dither points. Then, the sources in n-2 dither points are added, and so on. The user-specified number of Minimum Dither Points is provided to limit how far this process is allowed to go. If a value of 1 Minimum Dither Points  is selected, sources in areas of the MSA with no overlap between dithers can become populated with other Primary sources. Finally, if Fillers are included in the Planner, they are added in using the same iterative process, to maximize the number of exposures of these as well.

The option to add more sources into the Primary Candidate set (perhaps with lower weights), or simply including a Filler Candidate List, may help to fill the MSA configurations as well. These options are available even without dithering ,and can be used in addition to Partially Completed Sources if dithering is used. Finally, the MSA Configuration Editor can be used after the fact to add slitlets to the MSA configuration(s) designed with MPT to observe additional sources.

A dispersion-direction offset of 80 or more shutters will create a fixed dither pattern that covers NIRSpec's two detectors, removing the wavelength gap that will be present in many spectra.

Figure 5. Fixed dither parameters

In this figure there are three dither points. The first entry is for the initial dither point. Two dithers have been specified, resulting in 3 entries in the table, which will require 3 MSA configurations to execute the observation, which is indicated in the text below the Pattern specification.  In this example, Partially Completed Sources has been elected, and a minimum of 1 dither point has been selected for Minimum Dither Points. This will help to fill the MSA by allowing sources with as little as 1/3 of the exposure time compared to the completed sources in the Plan.

MPT Section 5: Gratings and Filters

In section 5 of Figure 1, the observer should select the gratings and filters that will be used in the Plan. This step is necessary to prevent spectral overlap, as the traces of the Prism, medium resolution, and high resolution spectra have different length and curvature. Consequently, configurations should not be used with gratings that were not originally specified in the Planner.  

While the MSA Planning Tool is designed to prevent spectra from overlapping on the detector, including second order spectra, there are some science cases where overlapping spectra can be tolerated. The checkbox Multiple Sources per Row (shown in section 5 of Figure 1) is offered to optionally allow for overlap in these cases. The behavior of this option depends on the choice of dispersing element or elements. In the case where the Prism is used exclusively, the Multiple Sources Per Row option is not available. The Prism allows multiple sources per row by default because the spectra do not extend beyond ~500 pixels in the dispersion direction. In the case of the gratings, or gratings plus the Prism in the same Plan, the behavior of the Multiple Sources Per Row checkbox is summarized in Table 2.

Table 2. Using the Multiple Sources Per Row Option

Grating option"Multiple Sources Per Row" Selected ?Description
Any gratingYesHigh (R-2700) and medium (R-1000) resolution grating data are allowed to overlap spectrally. A separation as small as 4 shutters in dispersion is allowed. Spectra will overlap. The user can additionally tune this separation using the field "Min Separation ___ Shutters".
Any gratingNoHigh (R-2700) and medium (R-1000) resolution grating data are not allowed to overlap. Targets will be separated enough to avoid spectral contamination.
PRISM + grating(s)NoGratings drive the multiplexing and no spectra will overlap (including the short Prism spectra). There will be significant unused space on the detectors in the prism exposures.
PRISM + grating(s)YesThe multiplexing will always be driven by the Prism. This will result in overlap of grating spectra if the Prism + gratings are planned together.

MPT Section 6: Search Grid

In order to find the best pointing on the sky at which to begin our observation with dithers, a search grid is constructed to the specification of the user.  Each grid point represents a test pointing. The grid is aligned with the orientation of the dispersion and spatial axes of the MSA at the specified Aperture Position AngleFor each point, the algorithm attempts to find the maximum number of high-priority sources that can be observed given constraints imposed by the MSA and the detectors. As part of this process, the tool avoids inoperable shutters and will attempt to prevent overlapping spectra, unless otherwise specified by the user.

The total number of observed sources, or the sum of their weights (if Weights are used in planning, see below) are tallied and saved at each test pointing. The result is called a "heat map". The heat map is used internally, but is not a delivered product. There are a few critical parameters that affect the computational time needed to create a plan. The size of the Primary Candidate List, the number of MSA configurations, and the number of grid points are the most relevant.

In this section of the MSA Planning Tool the user defines the size of the search grid, its Center, and the Search step size mentioned above as shown in Figure 6. The entire extent (Center RA and Dec, the Width and Height) of the input Catalog at the specified Aperture Position Angle is used to define the area over which test pointings are examined. The default value of Search Step Size is 30". If the default grid spacing value is changed, the tool will re-compute the number of grid points that will be searched, and will display the result next to the selected spacing as shown in Figure 6.  Normally, reducing the step size will improve target numbers. Grid step sizes in the range of 2" - 12" give similar plan results in many fields, for typical source densities. Even reducing to a step size as small as 1/3 of a shutter width (~85 milli-arcsec) may provide improved results, but at the expense of computational time and memory.

The Search Step Size can dramatically affect the time it takes to compute a Plan. A lower value will increase the number of pointings to be tested. A higher value will decrease the number of pointings. The number of pointings in the grid is calculated and displayed next to the selected Search Step Size. Keeping the search grid to less than 10,000 total pointings is advised for MPT plans to run in a reasonable amount of time on most computers, with moderately sized catalogs of about 10K sources.  Users should experiment in any case.

Search grids that subtend RA = 0.0 will cause MPT to fail. A workaround may be to break up the source catalog and plan separately.

Figure 6. Search Grid parameters window

These parameters are editable by the observer in case they want to limit the search area, or move it to a particular region on the sky. The defined area should typically be within the area covered by the dither pointings.

Note that a Plan with a single fixed pointing plan may be obtained by specifying the pointing Center, and setting Width = Height = 0.0 arcsec.

The parameters Width and Height are measured in units of arcsec along the MSA aperture X and Y axes as shown in Figure 2. Typically the values provided by MPT will suffice, but it is sometimes useful to visualize the footprint of the MSA at a specific position using Aladin, the viewer provided by APT, when choosing these search grid parameters. There are additional drawing tools in Aladin that could help determine appropriate values for these search grid parameters.

After invoking Aladin from APT, note that the default view in the APT GUI changes from Form Editor to View in Aladin. In order to return to the MPT, click on the Form Editor at the top left of the main APT window and make sure the correct Observation Folder is selected or highlighted.

MPT Section 7: Other Plan Parameters

Section 7 of the MSA Planning Tool is where the last remaining parameters are defined, the Plan is named, and finally generated. Additional planning parameters are described in Table 3.

Table 3. Additional Planning Parameters

Use Weights
If this option is selected, the MSA Planning Tool will reorder the Primary Candidate List based on weight and will select pointings that observe the highest sum of source weights. Typically, weights are present as a column in the input catalog, and are inherited by the Primary Candidate List as explained in the article NIRSpec MPT - Catalogs
In the absence of weights (or given equal weights), MPT will prioritize sources based on their order in the Primary Candidate List. The weights of the Fillers are not used to select the best pointing, but are tallied in the Total Weight shown on each exposure.  
Enable Monte-Carlo
If the user chooses to enable Monte Carlo shuffling, the tool will attempt to optimize the number of sources observed in an MSA configuration by shuffling the Primary Candidate List before selecting sources. The number of Monte Carlo trials can be adjusted by the user. The default is 10 trials. The results of all trials are evaluated and the best result is selected. Figure 7 shows the advantages of enabling Monte Carlo shuffling. After shuffling, sources are ordered by weights if weights are also selected. Therefor combining the use of weights and shuffling is appropriate only for Catalogs that include multiple sources with the same weight so that alternate source ordering will be possible.

Figure 7. Advantages of Monte Carlo shuffling

Re-ordering the Primary Candidate List at a given pointing can increase the number of sources observed at that pointing.  The planning tool will save the option that gives the most sources.

Random shuffling is applied independently at each test pointing when Monte Carlo shuffling is enabled. Monte Carlo shuffling works best with intermediate-sized Primary Candidate lists. It needs enough alternate sources in the dispersion direction to select from while attempting to pack the MSA more efficiently.
Allow sources in areas affected by stuck open shuttersIf this option is selected, planned sources will be allowed to occupy stuck open shutters, or the shutters that would normally be masked out around the stuck open shutters to avoid spectral contamination.

Number of Configuratons

The number of MSA configurations to generate.

There is a default Number of Configurations computed for the user. This is the minimum number needed for the dithering strategy specified and will result in one target set. Selecting more than this minimum (a multiple of the default minimum) will result in additional target sets observed with the same dithering strategy, but different pointings. Making this field empty will cause MPT to calculate as many MSA configurations as required to completely observe all the Primary Candidates. Note that once included in a target set, Primary sources will be excluded from subsequent target sets. 

Plan Name

A user-defined name for a Plan. Use a meaningful and unique name for each Plan. An APT file can contain several Plans and will save them.

Generating a Plan

After the plan parameters are fully specified, plan generation is begun by clicking Generate Plan. While the MPT is generating a Plan, a dialog window shows the progress. The length of time it takes to generate a Plan depends on the number of points searched (shown by the search grid parameters) and the number of science sources in the Primary and Filler Candidate Lists.  

Note that it is possible to start generating a MPT Plan that will take an extremely long time to create. Keep the number of search grid pointings to <10,000 and the number of catalog sources below 20,000 for MPT Plans that will take a reasonable amount of run-time on most computers.
It is good practice to save your APT session after generating your Plan, and as you generate more plans or create new observations.

Once the Plan is generated, APT will automatically display the results in the Plans pane (NIRSpec MPT - Plans) where the proposer can examine planning results to assess the quality of the Plan. If users wish to stop plan generation once started, the Cancel button can be clicked in the pop-up progress window. This will stop the MPT to allow user interaction. 

In order to return to the Planner, simply go to the top of the window and select one of the two tabs shown.


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



Latest updates

  • Added note that only one primary target per target shutter will be allowed.
  • Added row to Table 2 for any grating with "No" selected for "multiple sources per row" to clarify behavior.


  • Update for MPT Rewrite