NIRSpec MPT - Plans
The Plans pane in the MSA Planning Tool provides the user with a view of observation planning results from the MPT, including statistical information about the generated configurations. It is in this pane where plans can be merged and observations are finally created.
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 aspects of the created Plan. Plan statistics like the total number of sources observed, the number of exposures a particular filler appears in, or the positions of each source within their shutters in an MSA configuration can be assessed before creating a final observation.
The MPT Plans tab has the format shown in Figure 1, where 5 sections are highlighted. These are described in detail below.
- Section 1: Plan & Description
- Section 2: Plan operations and Observation creation
- Section 3: Pointings
- Section 4: Targets and Coverage
- Section 5: Timing
*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. Plan and Description
This section shows a list of the plans generated in your APT session or saved in your APT file from an earlier session. Since several plans can be saved in the same APT file, the user should first select a Plan by name. The columns in the table show the number of MSA configurations 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. Selecting multiple rows in this table provides the option to send multiple Plans to an observation (see Section 2, below), and allows multiple Plans to be examined and evaluated together (Sections 3 and 4, below).
MPT Section 2. Plan operations and Observation creation
Section 2 contains five buttons:
- Create Observation
- Update Observation
- Import Plan(s)
- Describe Plan(s)
- Delete Plan(s)
This button allows the user 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 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.
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 can be useful if there is an empty observation in APT (i.e. when a new observation folder is created), and proposers wish to use this observation instead of creating a new one. Its primary use is intended for updating an observation after an aperture position angle has been assigned.
This button allows users to import one or multiple Plans that were previously saved using the "Export" buttons shown in Section 1.
This button brings up a window listing the parameters used in the highlighted Plan or Plans.
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 used to make an Observation should not be deleted without first removing the Observation.
- MSA Observations created with MPT cannot be successfully copied and pasted to another Observation in the same APT folder.
- MSA Observations created with MPT cannot be successfully copied to another APT Folder. The Plans of the parent folder will not be copied to the new 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, and shutter information can be saved to a .csv file. To do so, click on the File item from the main menu at the very top of the computer screen. From the pull-down menu, select Export → MSA Target Info. This mechanism makes it possible to track target coverage through all exposures of an Observation outside of APT. These files are ASCII and readable by Excel, for example.
MPT 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: three nods each for four configurations and 3 primary fixed dither points. These 36 exposures are listed in the Pointings table (Figure 1, Section 3) with names that concatenate the MSA configuration ID and exposure ID. For example, in this case we have three configurations c1, c2, c3 each with four exposures (e1, e2, e3, e4) for the four grating selections, and 3 nods, so the names are c1e1n1, c1e1n2, c1e1n3, c2e1n1, etc. For each exposure listed here, the Right Ascension, Declination, and Aperture Position Angle (APA) 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 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 in Aladin using the Show button. When Show is clicked, a pop-up window will open showing the MSA Shutter View.
MSA Shutter View
Figure 2 shows an MSA Shutter View of a configuration. It may take a few seconds to generate. In the MSA Shutter View, the four 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.
From the MSA Shutter view, clicking on the parent Catalog or a Candidate Set in the list will display additional sources from those lists (if it is not already shown). In order to remove the Catalog from the display, simply unclick on the Catalog that you want to remove from view. Unobserved sources will appear as small square symbols.
Zooming to shutter level, as shown in Figure 3, it is possible to view individual sources and slitlets.
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.
It is possible to save a completed MSA configuration using the Export to CSV button. Export to CSV produces an ASCII file of comma-separated values. The exported csv file has values of '0', '1', 's', or 'x' for each commanded open, commanded closed, failed open, or failed closed shutter, respectively. These exported MSA configuration files can be shared and/or imported into other proposals using the "Import Configuration(s)" button in the observation template. Additionally, exported MSA configuration files can be used with the MSAViz tool to view of how the spectra will look on the detector and obtain wavelength coverage for each slitlet.
The failed shutter positions are inherited from the current MSA shutter operability reference data that the MPT utilizes during plan creation.
Table 1. Shutter color and meaning
|Shutter color||Description/ meaning|
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 how complete is the utilization of the MSA.
|orange||The shutter is commanded open and part of the slitlet.|
|light red||The area marked in this color is impacted by the presence of a failed opens shutter (several rows may be impacted completely or partially.)|
|red||Shutter is failed open.|
|gray||Shutter 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
|green dot||Source from the Primary Candidate List that is a planned MSA source in the displayed exposure.|
|green plus symbol||Source from the Primary Candidate List that is a planned MSA source in another exposure of the Plan.|
|blue dot||Source from the Filler Candidate List that is a planned MSA source in the displayed exposure.|
|blue plus symbol||Source from the Filler Candidate List that is a planned MSA source in another exposure of the Plan.|
|black dot||Contaminant source present on this exposure.|
|black plus symbol||Contaminant source present in another exposure of the Plan.|
Collapsed Shutter View
There is a second exposure view present in the pop-up window called the Collapsed Shutter View which can be seen by clicking Collapsed Shutters icon as shown in Figures 2 and 4. This view (Figure 4) shows each planned source's position in its shutter, all plotted together in a single virtual shutter. Clicking on a symbol will indicate the source ID and will highlight it in the color magenta, in the MSA Shutter View, and the Targets Table in MPT (Section 4). It will also highlight the same source if it is present in a second pop-up exposure view of an exposure in the plan.
The APT Aladin Viewer is APT's image viewer.
The Add shutters plane to Aladin button located at the bottom of the MSA shutter view will draw a sketch of the shutters that comprise the target slitlets on the Aladin sky view, as shown in Figure 5. The shutters in this case are drawn in green while the sources from two candidate sets are shown as red and blue crosses.
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.
MPT Section 4. Targets and Coverage
Section 4 (Figure 1) 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 - Planner, the 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 8). 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 all of the Primary sources that are successfully observed through 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 filtering will be shown in the space below the filters. The number of successful sources will be summed and displayed, followed by a table with 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.
MPT Section 5. Timing
A histogram depicting number of targets as a function of its number of exposures (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 best 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