The JWST NIRSpec MPT Manual Planner is designed to help the user manually create new plans and modify existing plans.
The MPT Planner is designed to automatically create optimal plans, but it is also possible for the user to create plans manually. Checking the Manual Planning box at the top of the Planner tab puts the planner into the manual planning view. Figure 1 shows MPT in the Manual Planning view.
The Manual Planning template has four sections that we discuss in detail below.
- Section 1: Planning Angles
- Section 2: Primary Candidate List
- Section 3: Exposure Setup
- Section 4: Pointing/Config Setup
MPT Section 1. Planning angles
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 initial proposal submission, an Aperture PA is selected by the user to create a 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.
At program submission (Phase II), the user will be working with the Aperture PA that has been assigned to their observation by the schedulers, and will use that precise angle in MPT to make detailed MSA configurations at the planned pointings.
For any NIRSpec MSA observation, it is highly recommended to experiment with a range of Aperture Position Angles as opposed to one single fixed angle.
For proposal 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, use the Aperture PA that has been assigned to your observation by STScI.
Here, the user enters the Aperture PA (an angle between 0 and 360 degrees), which 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.
Since programs that specify fixed orientations can restrict scheduling opportunities, most NIRSpec MOS programs will be submitted without orientation restrictions, in order to allow the schedulers to find suitable windows for them. When the proposal is submitted, the NIRSpec spectroscopy observations should have an "ON HOLD for Orient Assignment" special requirement.
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 motion at the center of the planning window and the telescope pointing. It is used to make small corrections to source positions at the MSA.
The true angle to target box offers a quick way to check target visibility: its value will not update if the chosen Aperture PA is not allowed.
MPT Section 2. Primary candidate list
The list of Primary Candidates is a catalog or 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 the observer defines the exposure specification. In the table in this section, each new exposure specification results in one or more new exposures. The number of new exposures is determined by the dither pattern specified. Click the ADD button to add a new exposure.
The 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 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.
This represents the number of groups during 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||This represents the number of integrations comprising an exposure, where 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.|
Exposures may be reorganized and removed if necessary, using the Duplicate, Insert Above, and Delete buttons.
MPT Section 4. Pointing/Config setup
Pointings and configurations
NIRSpec MSA configurations are described by a configuration file. Those configurations are created by APT when the MPT is used. It is possible to save a configuration off-line by exporting it from APT. An edited configuration file may also be imported into APT. The only format supported for importing or exporting an MSA configuration file is comma-separated values (.csv).
Note that it is possible to create then upload your own MSA configuration in the .csv file. Keep in mind that if a configuration file is created or edited outside of the MPT, geometric distortions will not be accounted for. Doing this is only advised for science sources that are spatially extended where spectra will not be adversely impacted by distortion.
Click 'Add', 'Duplicate', 'Insert Above', and/or 'Delete' to create the configurations you want. By double clicking on a row, a window will pop open. This is the manual editor.
Manually editing a configuration
When the manual editor is open, the shutter view is presented with the sources from the Primary List over-plotted, as shown in Figure 3.
The configuration of shutters is shown for the four MSA quadrants, using the color convention introduced in NIRSpec MPT: Plans. Here it is possible to zoom in and out to the shutter level. Zooming is accomplished by clicking the right mouse button and dragging up and down. This is usually enabled on a trackpad by depressing two fingers at once and dragging in an upward or downward motion. Hovering the mouse over a single micro-shutter, provides its identifier and state (open, closed, stuck_closed, etc).
Individual available shutters may be opened/closed with a "Left Click" on the mouse. Use "Ctr+Left Click" to open/close rows. Also available are the "Open all" or "Close all" buttons. The idea is to open shutters that correspond to sources of interest, as shown in Figure 4.
Once a configuration is complete, it is possible to save it using the "Export to CSV" button. This produces an ASCII file of comma-separated values that can be shared and read in APT. 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.
Three tabs are located at the bottom of the window: 'Collapsed', Pointing', and 'Parameters'.
The 'Collapsed' view (Figure 5) shows each target's position in its own shutter, all plotted together in a single virtual shutter.
Under the 'Pointing' tab (Figure 6) it is possible to give a name to the configuration, and specify appropriate pointing equatorial coordinates. If the pointing is not already populated, it is mandatory to add appropriate RA and Dec values.
Under the 'Parameters' tab, it is currently required that a Candidate set be selected, even for plans generated with the Manual Planner. This implies that a catalog is required as well. In a future version of MPT, it will no longer be required for manual planning. To further ensure that the standard calibration pipeline will not fail, there must be targets in planned slits. Figure 7 shows a detail of the Parameters tab design.
Confirm this new configuration by clicking on the OK button.
Generating a plan
Under Plan Name, assign a name to this manual plan and click on Finish Plan. This will process and generate the plan and direct the user to the Plans tab, where it is possible to assess the quality of the plan.