NIRSpec MPT - Manual Planner
The JWST NIRSpec MSA Planning Tool (MPT) Manual Planner is designed to help the user manually create new plans and modify existing plans.
The MSA Planning Tool (MPT) Planner is designed to automatically create optimal plans, but it is also possible for the user to create plans manually. Checking the Manual Planning1 box at the top of the Planner tab of MPT results in the view shown in Figure 1.
- Section 1: Planning Angles
- Section 2: Primary Candidate List
- Section 3: Exposure Setup
- Section 4: Pointing/Config Setup
1 Bold italics font style is used to indicate parameters, parameter values, and/or special requirements that are set in the APT GUI.
MPT Section 1. Planning angles
Aperture PA (APA)
A given NIRSpec MSA observation must be executed at a specific telescope orientation angle so that the selected sources will fall into the open shutters as planned. Because of the telescope's orbital position and sunshield constraints, a given orientation may only be possible for limited periods during the year or not available at all. The Target Visibility Tools can be used to determine the range of feasible orientation angles for a target throughout the telescope's orbital cycle.
For most NIRSpec MOS observations, it is recommended to experiment with several different feasible Aperture Position Angles prior to initial proposal submission. The submitted APA is used to create place-holder or "planning visits" with MPT. Once a proposal is accepted, it will be assigned a fixed orientation and a corresponding window of time when observations will be made.
For proposal submission, use any feasible APA from the orientation angles provided by the JWST Target Visibility Tool for the time of observation. For final program submission, use the fixed orientation APA that has been assigned to your observation by the schedulers at STScI. This assigned angle will correspond to one or more plan windows for execution in the scheduling timeline.
The APA (an angle between 0 and 360 degrees) specifies the orientation of the cross-dispersion axis of the MSA aperture measured from North in the counterclockwise direction. Figure 2 shows how this angle is measured on the sky. The "Y" axis represents the cross-dispersion direction of the MSA.
True angle to target
The True angle to target field appears in the Planner, but is greyed out and cannot be changed by the user. This is the angle between the telescope's velocity vector at the center of the planning window and the telescope pointing. It is used to make small corrections to source positions at the MSA resulting from the velocity of the spacecraft.
The True angle to target offers a quick way to check target visibility: its value will not update if the selected APA is not feasible.
MPT Section 2. Primary Candidate List
The Primary Candidate List is a candidate set that should be defined in the NIRSpec MPT - Catalogs pane. In manual planning mode, select the appropriate list from the pull down menu.
MPT Section 3. Exposure setup
In section 3 of the Manual Planner the observer defines the exposure specification. Click the ADD button to add a new exposure specification. Each new exposure specification results in one or more new exposures. The number of new exposures resulting from an exposure specification is determined by the dither pattern specified.
The JWST Exposure Time Calculator (ETC) should be used to determine the best exposure parameters to optimize the signal-to-noise of your observation. An exposure is configured by setting the Grating/Filter combination, Readout Pattern, Number of Groups, and Number of Integrations.
Users should ultimately use the JWST Exposure Time Calculator for all sensitivity calculations.
The exposure parameters that the observer needs to define are listed in Table 1.
Table 1. Description of Science Parameters for a given exposure
|Grating/Filter||Select a grating/filter combination from the pull down menu. The article NIRSpec Dispersers and Filters describes all the available combinations for NIRSpec observing modes.|
Each exposure consists of a set of one or more integrations. Integrations consists of a set of nondestructive reads of the detector.
The detectors can be read in different ways. The available patterns are NRS, NRSRAPID, NRSIRS2, and NRSIRS2RAPID. These patterns are described in full detail in the article NIRSpec Detector Readout Modes and Patterns. The default pattern is NRS, which will average 4 frames on board (i.e. there are 4 frames in one Group).
Select the pattern that best suits your observation.
The number of groups in an integration. The number of groups, together with the Readout Pattern (i.e. the number of frames in a group) will determine the length or duration of an integration, using the specified options for averaging or not averaging frames.
|Integrations/Exp||The number of integrations comprising an exposure, where an integration is defined as a set of non-destructive reads.|
|Autocal||This option is available to automatically add calibration exposures to a science exposure. For the MOS, the options are NONE, WAVECAL, FLAT, and BOTH. NONE is the default and is recommended.|
|ETC Wkbk.Calc ID||The user should enter the ETC calculation ID from the associated ETC Workbook. See note below.|
Exposure specifications may be reorganized or removed as needed, using the New, Copy and Link, and Remove buttons, and the arrows at the left of the 'Exposure Setup' box. Each exposure specification will be used for each of the Pointing and Configurations specified below.
MPT Section 4. Pointing/Config setup
Configurations and Pointings
NIRSpec MSA configurations are described by a configuration file. Those configurations can be created with the Manual Planner as described below, or ingested to the Manual Planner from the automatic MPT Planner. It is possible to save a configuration off-line by exporting it from APT. A configuration file may also be imported into APT using the MPT Manual Planner. The only format supported for importing or exporting an MSA configuration file is comma-separated values (.csv).
Click New, Copy and Link, and/or Remove (as shown in Section 4 of Figure 1) to create or delete the configurations you want. New will create a new MSA configuration entry in the next row of the table. Table rows can be rearranged using the up and down arrows to the left of the table. Copy and Link can be used to make a copy of an existing configuration (first select the entry you want to copy).
Caution! Any changes made to the configuration (including renaming it) will apply to all table entries using that configuration.
Copy and Link is provided for users who wish to create a set of offset exposures from a Base Pointing, and to save overheads by linking them as a set of dithers applied to the base pointing. The Base Pointing, Dispersion Offset, and Cross-Dispersion Offset columns can be edited directly in this table. Offsets are in units of shutters.
By clicking on Edit config in the right column of a table entry, a window will pop open displaying the MSA shutter view for the selected MSA configuration. This window is the Manual Editor.
As an example, to create a set of nodded exposures that use the same MSA configuration in the Manual Planner -
- Click New to generate a new MSA configuration.
- Type in the base pointing.
- Type in "0.0" for the dispersion and cross-dispersion offsets.
- Click Copy and Link twice to create two new entries in the table. These will use the same MSA configuration as the first entry.
- Edit the second entry cross-dispersion offset to have a value of 1.0 (exactly 1 shutter up from the base pointing).
- Edit the third entry cross-dispersion offset to have a value of -1.0 (exactly 1 shutter down from the base pointing).
- Click Edit config in the right column of the first table entry (at the base pointing). Wait for the Manual Editior window to appear.
- Create the configuration you want by opening or closing shutters in the Manual Editor.
- When finished, click OK.
- To save this new Plan, give the plan a unique name, and click Finish Plan at the bottom of the main Planner window.
Manually editing a configuration
When the Manual Editor is open, the shutter view is presented with the sources of the candidate list used to generate the configuration, as shown in Figure 3. Other lists may be displayed by selecting them from the Parameters tab of this window. Note that all sources appear as black plus symbols in the Manual Editor, whether they are in configured slitlets or not.
Individual operable shutters may be commanded opened or closed with a "Left Click" on the mouse. Also available are the Open all and Close all buttons. The metadata for each open shutter is tracked during load, so opening all shutters in the Manual Editor will be slow and is not recommended for casual use. The Manual Editor should be used to open shutters that correspond to sources of interest, as shown in Figure 4. There is a shortcut to make a long slit configuration: point the mouse at a column of shutters, and use "Ctrl+Left Click" to open (or close) the column of shutters.
For users who wish to observe moving targets with a long slit configuration at one of the Quadrant 4 Field Points in the MOS Spectroscopy template using WATA, columns can be opened in the following locations:
- Q4 Field Point 1 corresponds to shutter q4d615s196
- Q4 Field Point 2 corresponds to shutter q4d533s244
The MOS Custom Configuration Process article describes the process for extended sources.
Options exist to export and import MSA configurations. These options, however, are intended for expert users who wish to manipulate MSA configurations outside of APT. The MSA can only be configured after applying corrections to source positions at the MSA affected by instrument and telescope geometric distortions. A completed MSA configuration can be exported using the Export to CSV button. One can be imported with the Import CSV button. Export to CSV produces an ASCII file of comma-separated values that can be shared and imported into the Manual Planner with Import CSV. The exported CSV file has values of '0', '1', 's', or 'x' for each commanded open, commanded closed, failed open, or failed closed shutter, respectively. Additionally, an image of the configuration can be saved in SVG format.
APT files themselves can be shared; this is the best way to share plans and configuration details. At the bottom of this article is a tip for saving the target info from a plan to a table that can be exported and examined outside of APT. This format is more accessible and useful for tracking observed target information.
Continuing with the Manual Editor window features - three tabs are located at the bottom of the window: Pointing, Parameters, and Collapsed.
Under the Pointing tab (Figure 5) it is possible to give a name to the configuration, and specify appropriate pointing equatorial coordinates. Base Pointing RA and Dec values are required before the MSA configuration can be saved. If other MSA configurations have already been designed, their Pointing and Configuration will be available from the pull-down menus Copy Existing Pointing and Copy Existing Configuration. If the Base Pointing coordinates are within the Catalog area, the source positions from the Catalog will appear in the shutter view.
Under the Parameters tab, a Candidate set must be selected, even for plans generated with the Manual Planner. This implies that a Catalog is required as well. To further ensure that the standard calibration pipeline will not fail, there must be targets in planned slits. Figure 6 shows a detail of the Parameters tab design.
- The candidate set can be changed by selecting from the Candidates pull-down menu to show the positions of other sources near the sources of interest.
- The Master Background button, when selected, makes it possible to open scattered shutters in the MSA on areas of the sky that will be used for background measurement and subtraction from target spectra.
- The Add shutters plane to Aladin button will display the slitlets of each target in the Aladin viewer. When returning from Aladin to the main APT window, remember to click 'Form Editor' in APT to see the normal Manual Planner view.
The Collapsed tab view (Figure 7) shows each target's position in its own shutter, all plotted together in a single virtual shutter. The Source Centering Constraint is selectable, and though it has no effect by itself, it can be used to identify which planned sources fall outside the margin of interest. These shutter constraints are described in the NIRSpec MPT - Planner.
Generating a plan
Under Plan Name in the main window of the Manual Planner, assign a name to this manual plan and click Finish Plan. This will process and generate the plan and direct the user to the Plans pane of MPT, where it is possible to review and assess the quality of the plan.
After the Plan is saved, and an Observation is created from it, there is also a mechanism for saving the planned target info from exposures made with the Manual Planner or those automatically-generated using the MPT. The target positions, pointing, and shutter information can be saved to a .csv file. To do so, click on the "File" item from the main menu at the very top of the computer screen. From the pull-down menu, select Export → MSA Target Info. This mechanism makes it possible to track target coverage through all exposures of an Observation outside of APT. These files are ASCII and readable by Excel, for example.
Karakla, D. et al. 2014, Proc. SPIE 9149
The NIRSpec MSA Planning Tool for multi-object spectroscopy with JWST