NIRSpec MPT - Planner
The JWST NIRSpec MSA Planning Tool planning interface is presented and described in detail. The steps to create a Plan containing targets, MSA configurations, dithering strategies, and exposure setup are discussed.
On this page
The NIRSpec MSA Planning Tool (MPT) is the official software planning tool to design a NIRSpec MOS observation. Its main purpose is to optimally plan micro-shutter assembly (MSA) observations, given a Catalog of source positions and a series of planning parameters. Constraints, such as the bars between shutters and 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 for 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.
The user must be connected to the internet when running the MPT Planner so it can check whether an aperture position angle is feasible when the user begins to create a Plan.
Words in bold are GUI menus/
panels or data software packages;
bold italics are buttons in GUI
tools or package parameters.
- Before running the Planner, the user must ingest an MSA source Catalog into the Targets folder in APT. There, APT provides tools needed to optionally filter the Catalog to subsets of sources. Users normally define a Primary Candidate List (and an optional Filler Candidate List). If no candidate sets are defined, the entire Catalog will become the Primary Candidate List.
- Next, the user should move to the MSA Planning Tool by clicking the MSA Planning Tool icon in the APT Tool bar, and select the Planner tab. The Planner pane is shown in Figure 1.
- The user specifies parameter values in the MPT Planner pane. The appropriate selection of values depends on the observer's science goals. For examples of how the choices made in the Planner affect the results, see the MPT Parameter Space, MOS Recommended Strategies, and MPT Computational Performance articles.
- 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 in the MPT Plans tab, the user can then select one or more Plans from which multi-object spectroscopy (MOS) observations will be made. When an observation is created from a Plan, (see NIRSpec MPT - Plans) fields in the observation template in APT are populated for the user.
Reminder: the MSA Planning Tool can be accessed from the icon of the same name in the APT tool bar, which spans the top of the APT GUI window. Likewise, the APT Multi-Object Spectroscopy (MOS) observation template can be accessed by clicking the Form Editor icon in the APT tool bar. The text below the selected icon appears in blue font.
Figure 1. The MPT Planner in the MSA Planning Tool
Click on the figure for a larger view.
MPT section 1: Candidate lists
The MPT is designed to create Plans that use 2 categories of science sources: a Primary Candidate List, and a Filler Candidate List. These lists are created from the input MSA source Catalog in the Targets folder of APT that was uploaded following the instructions in the article NIRSpec MPT - Catalogs.
When a user clicks the Generate Plan button at the bottom of the Planner pane, the tool will attempt to maximize the number, or the summed weight, of Primary sources obtained in the configurations it creates. For this reason, these sources will directly influence the pointing selection for either single pointing or 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 in order to observe more sources in each exposure. The algorithms will also attempt to optimize the number of fillers in all exposures of the Plan (e.g., through a set of dithers), but the fillers are selected only after the primaries are completed, and do not define the pointings. Only the Primary Candidate List determines the selected or "best" Pointings - and only the "completed Primaries", as described below.
Observers should place all sources in the field into a single parent Catalog that will be used to define observations in the field. The candidate lists (Primary Candidate List and Filler Candidate List) are derived from this single Catalog. APT is unable to work with primary candidates from one Catalog and fillers from a different Catalog. Users will not be able to make observations from Plans made with candidate lists derived from different Catalogs.
MPT section 2: Plan angle
An 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 sun shield constraints, a given orientation may only be possible for limited periods of time 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 that users experiment with several different feasible aperture position angles (Aperture PA) prior to initial proposal submission. The Planned Aperture PA field will contain the angle used during planning. Once a proposal is accepted, it will be assigned a fixed orientation (an Assigned Aperture PA) and a corresponding window of time when observations will be made. The Assigned Aperture PA will appear in the MOS observation template. MOS observations must then be re-planned to the exact Assigned Aperture PA (to four decimal places).
Note that the Planned Aperture PA has no influence on the selection of the Assigned Aperture PA. If an angle constraint is desired, the observer must add an angle special requirement to the proposal before submission. Adding an angle constraint after TAC acceptance must generally be made by request to the TTRB, and approval is not guaranteed.
For proposal planning and submission, use any feasible Aperture PA 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 Aperture PA that has been assigned to your observation by the planners and schedulers at STScI. This assigned angle will correspond to one or more plan windows for execution in the scheduling timeline. This is explained in more detail in the MOS and MSATA observing process and the NIRSpec MPT - MOS and MSATA Program Updates articles.
The Aperture PA (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.
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.
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 (Aperture PA, θ) is shown as measured on the sky.
MPT section 3: Slit setup
In this section the user defines the shape of the Slitlet and the Source Centering Constraint.
Each selected MSA target in a Plan will be observed with the same Slitlet shape and Source Centering Constraint.
Slitlet
The NIRSpec MSA is composed of nearly 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 4 selectable Slitlets, each with a different number of adjacent open micro-shutters: 1, 2, 3, or 5. The spectrum from a slitlet will be segmented, with bar shadows between the individual shutters making up the slitlet. The yellow and black sketch in the Planner, shown in Figure 3, illustrates the options for slitlet length.
MPT will, by default, avoid the selection of primary sources with close neighbors that would result in more than one primary source in the same shutter. However, there is an option in the Parameters section of the template to override the default and allow more than one primary source per shutter. For pipeline reduction purposes, just one of the sources will be selected as the primary source for the slit.
Each open micro-shutter, when projected onto the sky, has dimensions of only 0.20" 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: 1, 2, 3, and 5 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.
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, for example. However, it is important to be careful about nodding when slit lengths differ in the same MSA configuration.
Source Centering Constraint
The Source Centering Constraint in the Planner offers 5 choices of shutter margins to constrain the positioning of a planned source within the shutter to help reduce slit losses and photometric uncertainty. As shown in Table 1, the larger the margin, the more limited the area available for centering the source. Generally, larger margins result in fewer selected targets, although this effect depends strongly on the source density of the Primary and Filler Candidate Lists. The selected constraint is applied to all sources in a Plan. To work around this limitation, one could make 2 separate MPT Plans using different centering constraints that could be applied to different subsets of sources. The input Catalog would need a column or two for identifying which sources should have which source centering constraint. Then the Catalog could be filtered in MPT into 2 separate Candidate Lists for making separate Plans with the different constraints. After the Plans are made, they can be merged into a single observation. Plan merging is explained in the MOS Strategies article.
The default constraint is the Entire Open Shutter Area. The figures in column 2 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. This useful view also shows the positions of the selected targets relative to their positions in their own shutters.
To be included as a successful source in a Plan, the source center must fall within the yellow area (the central area of the shutter bound 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, anchored at 2.95 μm (column 3 of Table 1). 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
| Source centering constraint | Figure† | Minimum relative flux transmission at 2.95 μm†† | Margin | |
|---|---|---|---|---|
Unconstrained (sources can be behind the MSA bars) |
| 12% | 0 | |
Entire Open Shutter Area (default) |
| 30% | 35 | |
Midpoint |
| 62% | 59 | |
Constrained |
| 75% | 72 | |
Tightly Constrained |
| 85% | 91 | |
† The Source Centering Constraints are based on the average shutter dimensions. The path losses, indicated as the minimum relative flux transmission are for a point source. They were measured relative to a perfectly centered source at 2.95 μm. At larger wavelengths, the PSF is broader, and the slit losses are greater than those at shorter wavelengths. The sketches shown in this table are representative only and do not reflect the actual sizes. Each shutter is surrounded by MSA bars (which are not depicted in the figures). In the Unconstrained case, a source centered directly behind the MSA bar is acceptable. Due to the FWHM of the source point spread function (PSF) compared to the shutter size, part of its light will enter the MSA 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 PSF increases with wavelength, as shown in Figure 4. The "minimum 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. These values were measured from ground test data using a lamp, but the relative transmission for a source can be more accurately estimated in the ETC. The minimum transmission is for a source in the corner of the shutter for a given margin, corresponding to source offsets from shutter center of 1/2 the shutter pitch minus the margin. For reference, the shutter pitch (mid-bar to mid-bar) values are ~ 0.27" × 0.53", and the bar width is ~0.07".
* The margins shown in the last column are measured from the mid-bar position inward, toward the center of the shutter.
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
Pointing Mode
The MPT Planner offers 3 different ways to identify one or more best pointings for a MOS observation. The choices are made available by using the Pointing Mode selection: 1) a Grid Search method to find the best pointings based on the "completed Primaries" (described below in Fixed Dithers), 2) an option to use pre-selected Fixed Pointings that the user defines, and 3) an option called MOS + Fixed Slit mode, which determines MSA pointings that place one (or more) selected sources into one (or more) selected slits at a fixed specified planning angle. The default selection is a Grid Search. Together with a preferred set of pointings, Plans with optimal MSA configurations are designed for each exposure.
For all 3 Pointing Modes, the Planner provides the ability to Nod in Slitlet for any selection of Pointing Mode, while only the Grid Search selection includes an option to create Fixed Dithers. These checkbox options are described below, following the descriptions of each of the Pointing Modes.
Using a Grid Search
With this selection for the Pointing Mode, a search grid is constructed to the specification of the user. Figure 5 below shows an example. Each grid point represents a test pointing. If Fixed Dithers are added, as shown in Figure 8, MPT finds an optimal pointing on the sky at which to begin an observation with dithers.
Note that the grid axes are aligned with the dispersion and spatial axes of the MSA at the specified Aperture Position Angle. They are not aligned to RA and Dec. This is especially important for irregular catalog areas on the sky that are larger than the MSA field if view. In these cases, the user may wish to pre-select a few central pointings within the catalog area, and plan with a square grid at each to find the best pointings for their MOS observations.
At each grid point, the algorithm attempts to find the maximum number of high priority sources that can be observed given MSA and detector imperfections. 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 Primary sources, or the sum of their weights (if Weights are used in planning, see below) are tallied and saved internally at each test pointing. 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 as shown in Figure 5. The entire extent (Center RA and Dec, the Width and Height) of the input Primary Candidate List at the specified Aperture Position Angle is used to define the default 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 5. 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 milliarcsec) may provide improved results, but at the expense of computational time and memory. The computational performance was tested and guidance is provided in the article MPT - Computational Performance.
The Search Step Size can dramatically affect the time it takes to compute a Plan. A smaller value will increase the number of pointings to be tested. 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.
For any added parallels, the optimal search grid parameters may also depend on the placement and coverage in the other instrument field. The Aladin FoV tool can be used to help select the best values of the MPT search grid parameters.
Figure 5. Search Grid parameters
The parameters Width and Height are measured in units of arcsec along the MSA aperture X and Y axes as shown in Figure 2. The search grid parameters are editable to allow the user to limit the search area, or move it to a particular region on the sky. The defined area should include the area covered by any dithers. The values provided by MPT will normally 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 can help determine appropriate values for these search grid parameters.
Sometimes the catalog area is elongated in one dimension on the sky. In this case, it is recommended to divide the area up and make separate MPT plans for each area. This will lead to a better result for the best pointing (which is determined from the completed Primaries alone). You may then decide to merge multiple plans (each with its own best pointing) into a single observation. In cases where the MSA axes happen to align naturally with the major or minor axis of the catalog region, a single grid search is sufficient.
Additionally, as shown in Figure 5, the observer can optionally click checkboxes to define dither and nodding patterns for the MOS observation. The option to nod is available for any selection of the Pointing Mode, but the option to use Fixed Dithers is compatible with, and available only for, the Grid Search method. Most JWST observations will require nodding or dithering and NIRSpec users are encouraged to make use of these features. 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 articles NIRSpec Dithering Recommended Strategies and NIRSpec MOS Dither and Nod Patterns.
After starting 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.
Planning to a single fixed pointing
Note that a Plan with a single fixed pointing is obtained by specifying the pointing Center, and setting Width = Height = 0.0 arcsec. The Search Step Size should additionally be non-zero. Fixed dithers are not compatible with a fixed pointing, and should not be specified. However, using Nod in Slitlet is an option.
Fixed Pointings mode
A second Pointing Mode option is provided for those users that have already selected more than one pointing that they wish to plan to. With this option, the user-defined pointings are held fixed and MPT will attempt to optimize the MSA configurations at all pointings as a set. The nod checkbox is also provided in this case, as well as the Partially Completed Primaries and Fillers options, with fields for the Minimum Pointings for Primaries and Fillers.
Figure 6. Fixed Pointings
MOS + Fixed Slit mode
A third selectable Pointing Mode option is the MOS + Fixed Slit Mode. When this mode is used, the pointing selection is defined by the placement of a target in the fixed slit at the specified Aperture PA. The MPT Planner is then used to open shutters on targets that land in the MSA field of view. The nod checkbox is also provided in this case, as shown in Figure 7.
This mode is implemented as follows. First, for ease of planning, it is recommended to generate a short candidate list from the Catalog that includes only the sources you want to be observed with one of the slits. Next, in the Planner in MPT, select the MOS + Fixed Slit Mode (in Section 4 of Figure 1). Adding a new source to the table will open a new field for selecting the Candidate Set for your fixed slit source(s). The Planner will plan to a fixed pointing - specifically, the pointing that is required to place a selected source into a specified slit at the fixed Aperture PA (the planning angle) the user has defined. The source and slit specification will appear in the Planner, as shown in Figure 7, replacing the Search Grid parameters. Entries are added to this table using the Add button below the table. Each new row will create a new exposure in the Plan.
It is important to note that the use of this combined instrument mode will often require the observer to add a Special Requirement on the Aperture PA, to ensure that the desired targets in the fixed slit and in slits on the MSA are observed when the angle assignment is made. If the observer is satisfied to later re-plan MOS source slits at an STScI-selected Aperture PA, the proposal can be submitted without a Special Requirement (SR) on the angle. That will allow for the most flexible scheduling of the observation. But, the observer should first carefully investigate whether there are ranges of aperture position angles that may be preferable for the MOS observation when the fixed slit source is centered in the selected slit. Whenever possible, if an angle SR is warranted, providing a 20- to 30-degree range of suitable Aperture PAs is beneficial for scheduling. Because of the implications to scheduling, any angle Special Requirements must be specified in the proposal, or as soon as possible after TAC acceptance.
Figure 7. Slit Source Search window
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. This option is presented for each of the three Pointing Modes via a checkbox. If nodding is selected (by clicking the checkbox for 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, top and bottom shutters only. This field, 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 pipeline will automatically perform a background subtraction using the various nod positions. Nodding as a method for obtaining local background measurements is appropriate for point sources, but cannot be used for this purpose for more extended sources.
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 to their MPT plans and MOS observations. The Fixed Dithers option is provided only when the Grid Search pointing mode is selected.
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 from the initial pointing to apply to a new 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 will naturally result in loss of targets due to diminished areal overlap of sources in the quadrants. To create a Fixed Dither pattern, simply click the Add button and define the offsets. Offsets are in units of micro-shutters. A positive offset in dispersion moves the MSA to the right (sources to the left) in the MSA Shutter View. A positive offset in the cross-dispersion direction moves the MSA upward (sources downward) in the MSA Shutter View.
For each new dither that is added to the Pattern table in APT, an additional pointing will result in the Plan, 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 and Filler sources are observed at all dither points (These are referred to as "completed" sources). Since it is only possible to obtain completed sources in areas of the MSA that overlap at different dither points, some areas of the MSA are typically left unused. Figure 1 shows an example of 3 Fixed Dither points. The first entry is for the initial dither point. Two additional 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 Primaries has been selected, and a minimum of 2 dither points has been selected for Minimum Dither Points. This will help to fill the MSA by allowing additional primaries (but with 2/3 exposure time compared to the completed sources in the Plan). Similarly, the Fillers are partially completed in this example, with as few as 1 exposure per Filler source (1/3 the full exposure duration).
An option to improve the use of the MSA real estate is to select Partially Completed Primaries and/or Partially Completed Fillers in the Planner when Fixed Dithers are used. When Fixed Dithers are selected, there are two separate checkboxes for this below the Fixed Dithers specification shown in Section 4 of Figure 1.
When Partially Completed Primaries is selected, the Plan will include Primary sources observed at some, but not all, dither points. This is done iteratively; after determining the set of completed Primary sources, and a best pointing for each dither, MPT will add in other Primaries that appear in n-1 dither points, where n is the total number of dither points. Then, the Primary 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 Minimum Dither Points = 1 is selected, sources in areas of the MSA with no overlap between dithers can become populated with other Primary sources. If a Filler candidate set is included in the Planner, and Partially Completed Fillers is selected, they are added in using the same iterative process after the best pointings have been selected, and also after the MSA configs are filled with as many Primary sources as allowed by the Planner selections for those sources.
Adding more sources into the Primary Candidate List (perhaps with lower weights), or simply including a Filler Candidate List, may also help to fill the MSA configurations. These options are available even without dithering, and can be used in addition to partially completed sources when 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 can be used to fill the wavelength gap that are present in many medium or high-resolution grating spectra. Using this option will require a second exposure. However, APT now has an option to restrict the selection of sources to shutters that would not result in wavelength gaps in observed source spectra. See Section 6. This option does not result in new exposures. Only sources in shutters which do not suffer from gaps in the selected disperser will be selected, which can limit the number of sources in the MSA configuration.
Figure 8. Fixed dithers checkbox and parameters, available only with the Grid Search method.
Click on the figure for a larger view.
MPT section 5: Exposure setup
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.
Multiple sources per row
While the MSA Planning Tool is designed to prevent spectra from overlapping on the detector, including 2nd 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 ? | Result |
|---|---|---|
| Any grating | Yes | High (R - 2,700) and medium (R - 1,000) resolution grating data are allowed to overlap spectrally. Spectra will overlap. The user can tune the horizontal source separation using the field Min Separation ___ Shutters. A separation as small as 4 shutters in dispersion is allowed. |
| Any grating | No | High (R - 2,700) and medium (R - 1,000) resolution grating data are not allowed to overlap. Targets will be separated enough to avoid spectral contamination. |
| PRISM + grating(s) | No | Gratings 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) | Yes | The multiplexing will always be driven by the prism. This will result in overlap of grating spectra if the prism + gratings are planned together. |
| PRISM | N/A | There is no option to tune the horizontal (dispersion) separation of targets with the PRISM. The spectral range is fairly short on the detector already allowing for many targets in the MSA, and most people would want to have uncontaminated prism source spectra. Currently, APT uses a value of 181 shutters to separate targets in the dispersion direction when using the prism. |
MPT section 6: Masking setup
In Section 6 of Figure 1 the user can prevent the selection of sources in their MPT Plan that would suffer from spectral losses at wavelengths that are cut off by the detector edges anywhere over the nominal wavelength bands specified for their Plan in Section 5. There are options to independently prevent red-end and blue-end losses due to the detector edges, as well as wavelength losses between the 2 detectors (i.e., in the gap between detectors). Additionally, there is independent control using checkboxes to prevent cutoffs in both the Primaries and Filler sources. Checking any one of the checkboxes called No Red Cutoff, No Blue Cutoff, or No Gaps may result in the reduction of the number of available shutters, which will be shown in the fields labelled Available Shutters. One can select any number of checkboxes for the Primaries and Fillers. The remaining grand total of available shutters will be indicated. Each of the cutoffs, and associated number of shutters affected, is dependent upon the selected grating-filter combinations in Section 5. If multiple gratings are observed, they must all satisfy the restrictions.
Note that spectra from the medium-resolution gratings and Prism can satisfy all 3 restrictions (for a limited number of shutters), yielding complete spectra that fit within one detector. Spectra from the high-resolution gratings are longer; coverage can be maximized by avoiding the red and blue cutoffs, allowing the spectrum to span the detector gap.
The resultant map of available shutters can be exported using the Export Mask buttons. It is also possible for users to design masks of preferred shutters outside of MPT and import these using the Import Mask button. The user may then select an imported mask to be applied to Primary and/or Filler targets. The imported mask may be used on its own or in combination with the checkboxes. An input mask should be a csv format file. Values of "0" or "1" are used for shutters that are desired to be available for planning, or unavailable, respectively.
MPT section 7: Wavelength Range Setup
Wavelength cutoffs in an observed source's spectrum depend on its shutter position in the MSA. For finer control of the wavelength coverage for each source, it is now possible to define wavelength ranges in the input Catalog. Up to five wavelength ranges may be defined as (startwave1, endwave1) … (startwave5, endwave5), as shown in Figure 9. Corresponding checkboxes are available in MPT Section 7 (Figure 1) that may be selected independently for Primaries and Fillers. When selected, each wavelength range is required to be observed completely by one or more of the selected gratings (or PRISM) with no red cutoff, no blue cutoff, and no gaps. As one might expect, specifying the minimum extent required for each wavelength range of interest helps to maximize the number of observed sources.
Figure 9 shows an example Catalog setup from JWebbinar #30. For the highest priority source (id 2661), uninterrupted coverage is required from startwave1 = 3.9 µm to endwave1 = 4.9 µm. No other restrictions are required for this source, so the remaining startwave and endwave entries are set to -1. For other sources in this example, coverage may be required for one or more spectral lines. One column defined for [OIII] (not used by MPT) gives the observed wavelength as a function of redshift, for example 3.66 µm for z = 6.31 (id 1961). The user then defined startwave2 = 3.64 µm to endwave2 = 3.68 µm to cover [OIII]. Similarly, startwave3 = 4.77 µm to endwave3 = 4.81 µm is designed to cover Hα for that source at z = 6.31. When running MPT, the user may then select one or more of these ranges for inclusion in the planning.
After running MPT, the resulting wavelength coverage for each source may be checked by exporting the MSA Target Info file (via File – Export…).
There are a few specific considerations when using this Planner feature:
- The wavelength range checkboxes are enabled only if there are corresponding columns for the wavelength pairs in the Catalog.
- If the source Catalog or Candidate Set is changed, any existing checkbox selections will be cleared and the ranges that are editable will be updated to match the wavelength range columns in the new Catalog.
- Catalog columns must be labeled as startwave(n), and endwave(n), where the parenthetical n is an integer from 1 to 5. See Figure 9 below.
- Wavelength ranges for a source are ignored if the value in the wavelength start column is a negative value or 0.
- Startwave values must be < endwave values, or the range is ignored by MPT during planning.
Figure 9. Example Catalog with wavelength regions of interest
Click on the figure for a larger view.
Wavelength regions of interest are indicated in a Catalog as having up to 5 pairs of columns (startwave1, endwave1), (startwave2, endwave2), etc. in units of microns. Negative values will instruct MPT to skip planning around a given wavelength range for a given source.
MPT section 8: Other plan Parameters
Section 8 of the MSA Planning Tool is where the last remaining parameters are defined. Additional planning parameters are described in Table 3.
Figure 10. Additional planning parameters
Table 3. Additional Planning Parameters
| Parameters | Description |
|---|---|
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. |
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. The figure below 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 with a selection of sources with the same weight so that alternate source ordering will be possible.
Advantages of Monte Carlo shuffling
|
Allow the opening of shutters containing multiple sources | If this option is selected, primary and filler sources with nearby neighbors that occupy the same shutter will be allowed in the MPT Plan. Normally shutters with multiple sources are disallowed in the expectation that their spectra will overlap on the detector and would be difficult to separate. For some science cases though, it may be possible to disentangle the spectra and obtain valuable information about highly desired sources. |
Allow sources in areas affected by stuck open shutters | If this option is selected, planned sources will be allowed to occupy failed-open shutters, and the shutters around them that would normally be masked out to avoid spectral contamination. Read more about this in the MOS Recommended Strategies article. Any possible conflicts from selecting this option will be indicated in the MSA Shutter View on the MPT Plan, or when the MSA configuration is edited at the observation level in APT. See Figure 4 in NIRSpec MSA Shutter Operability. |
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 specified dithering strategy 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. Leaving 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. |
MPT section 9: Plan name and Plan Generation
Plan name
Provide 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 all of them, unless the user opts to delete 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 in the search grid parameters) and the number of science sources in the Primary and Filler Candidate Lists.
Once the Plan is generated, APT will automatically display the results in the Plans pane (NIRSpec MPT - Plans) where the proposer can examine it or compare it with others. 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, but only after the MSA configuration in progress is completed.
In order to return to the Planner, simply go to the top of the window and select one of the two tabs shown.
References
Karakla, D. et al. 2014, Proc. SPIE 9149
The NIRSpec MSA Planning Tool for multi-object spectroscopy with JWST