NIRSpec Fixed Slit Spectroscopy Template Parameters
JWST's NIRSpec Fixed Slit Spectroscopy template, available in the Astronomer’s Proposal Tool (APT), has parameters for specifying and scheduling observations.
Purple text indicates the parameter is Limited Access.
Boldface italics type indicates the name of an APT parameter or a value for a parameter.
text indicates restrictions on a parameter. Red
Black text indicates an important note.
Brown text indicates notes for the developers.
Green text indicates the name of the parameter used by Commanding.
Items in brackets - <value> - are required values.
Items in square brackets - [<value>] - are optional.
The NIRSpec Fixed Slit Spectroscopy template is to be used for all observations using the fixed slit spectroscopy mode of NIRSpec, and this article describes allowed values for all parameters. Advice on how to choose values which optimize your science can be found in the NIRSpec Fixed Slit Spectroscopy APT Template.
The NIRSpec Fixed Slit Spectroscopy template consists of the following parameters:
|assign observation number|
|Observation Label||provide observation label||text||optional|
|Observation Comments||provide observation comments||text||optional|
|select Target Name||choose from list||from Target List|
|specify ETC Workbook Calculation ID||number||for science exposures (optional) and target acquisition exposures|
|specify mosaic parameters||number||if needed|
|specify special requirements||choose from list||if needed|
|Template Specific Information|
|Target Acquisition Parameters|
|Target Acquisition Method||select target acquisition method||choose from list|
|MSA Target Acquisition Parameters|
|Reference Star Bin|
list of reference stars and configuration
|choose from list|
|Acquisition Filter||filter name||set based on Reference star bin|
|Acquisition MSA Configuration Filename|
select MSA configuration
|choose from list|
|Acquisition Readout Pattern||readout pattern||set based on Reference star bin|
|WATA Target Acquisition Exposure Parameters|
|Acquisition Target||select acquisition target||choose from list|
|Acquisition Subarray||select subarray||choose from list|
|Acquisition Filter||select filter name||choose from list|
|Acquisition Readout Pattern||select readout pattern||choose from list|
|select slit name|
choose from list
choose from list
|select number of dither positions|
choose from list
|select sub-pixel dither pattern|
choose from list
|select grating/filter name|
choose from list
|select readout pattern|
choose from list
|specify number of groups/integration|
|specify number of integrations/exposure|
|select Auto Calibration option|
Target Acquisition Parameters
Target Acquisition (TA) Method
TA METHOD [TA METHOD] = NONE, MSATA, WATA (default)
For NIRSpec Fixed Slit Spectroscopy there are three options: NONE which performs no target acquisition, the standard MSA Target Acquisition (MSATA) that uses reference stars observed through the MSA, and the Wide Aperture Target Acquisition (WATA) that observes the target or a reference object through the wide aperture, and calculates an offset to the science aperture to be applied to the subsequent science exposures.
Select the target acquisition method to be used; see FS Template Section 3: Target Acquisition Parameters. The standard MSA TA is used for observations that require high precision . When roll correction is not required, WATA provides a means to acquire a target or a reference target without the need for Reference Stars.
Note that MSA target acquisition is not allowed for moving targets. WATA can be used for moving targets, but offset acquisition targets are not allowed when the science target for fixed slit spectroscopy is a moving target. The acquisition target must be the same as the science target in that case.
Note for developers: TA METHOD is a required parameter. If WATA is selected, APT should accept WATA Target Acquisition parameters below. If MSATA is selected, APT should accept MSA Target Acquisition parameters below.
MSA Target Acquisition Exposure
If TA METHOD = MSATA then the standard MSA target acquisition uses reference stars located in the MSA field of view to acquire the target. Since you). Note that, after the acquisition is complete, an image will be obtained to allow observers to check the status of the acquisition; see FS Template Section 3: Target Acquisition Parameters.
Note that MSATA is not allowed with moving targets.
|The following TA parameters for MSATA are selected at the *Visit Level* of the program.|
Reference Star Bin
A Reference Star Bin contains valid reference stars (i.e. they are of a limited brightness range appropriate for a particular ACQUISITION FILTER and READOUT PATTERN) and the NIRSpec configuration that will be used for the acquisition. The MSA Planning tool will generate multiple options of different combinations of references stars, ACQUISITION FILTER, and READOUT PATTERN for you to choose from. While all combinations containing one or more reference stars will be presented, the only viable choices are those with more than 5 reference stars.
Note for developers: If the user selects a bin with fewer than 5 reference stars an error will be shown. If they select one with 5-8 reference stars they will get a warning.
The TARGET ACQUISITION FILTER [TACQ FILTER] is automatically set based on your choice of Reference Star Bin, and can be CLEAR, F140X, or F110W.
Acquisition MSA Configuration Filename
The ACQUISITION MSA CONFIGURATION [TACQ MSAFILE] field specifies the MSA configuration to be used for target acquisition (to mask bright stars in the field). Select a configuration previously defined in the MPT, or select ALLOPEN (which leaves all shutters open). If no selection is made, then all shutters will be open.
Acquisition Readout Pattern
The ACQUISITION READOUT PATTERN [TACQ PATTERN] is automatically set based on your choice of Reference Star Bin, and can be NRS, NRSRAPID, NRSIRS2, NRSIRS2RAPID, NRSRAPIDD1, or NRSRAPIDD2.
Note that the ACQUISITION NUMBER OF GROUPS/INTEGRATION is automatically set to 3 and ACQUISITION NUMBER OF INTEGRATIONS//EXPOSURE is automatically set to 1.
Note for developers: Note that while the SUBARRAY is not explicitly given, its value is FULL for the purposes of calculating exposure time.
WATA Target Acquisition Exposure
If TA METHOD = WATA, the wide aperture target acquisition places the acquisition target (which may be the science target) into the NIRSpec wide aperture. A target acquisition exposure is taken through this aperture to derive a centroid, to center the acquisition target in this wide aperture. After the target acquisition completes, a “reference image” of the acquisition target centered in the wide aperture is obtained to allow observers to check the status of the acquisition after the fact. Following that, the spacecraft will be repointed to put the science target in the selected slit prior to the start of the science exposures; see FS Template Section 3: Target Acquisition Parameters.
For this method of TA, the following parameters are used to define NIRSpec WATA Target Acquisition observations.
If instead of the target of the observation, an offset star is to be used for the target acquisition, select the ACQUISITION TARGET [TACQ TARGET] from the list of targets previously entered.
Note that for observations of moving targets, the ACQUISITION TARGET cannot be an offset target.
Note for developers: For APT, the ACQUISITION TARGET field should always be present, but should be defaulted to the SAME TARGET AS OBSERVATION.
Note for developers: If the acquisition target is different from the science target, APT should provide a warning if the slew distance between the ACQ pointing (to place the acquisition target in the acquisition aperture) and Science pointing (to place the science target in the science aperture) is greater than the Visit splitting distance found in the PRD. But if the separation is greater than 2 arcminutes, an error should be provided. Also, if there are multiple pointings within a visit, then the rules have to apply to the greatest separation between acq target and pointing within the visit.
TARGET ACQUISITION SUBARRAY [TACQ SUBARRAY] = SUB32, SUB2048, FULL
This field specifies the subarray region on the detector to be used to obtain the acquisition data.
TARGET ACQUISITION FILTER [TACQ FILTER] = F140X, F110W, CLEAR
This field specifies the filter to be used to obtain the acquisition data.
Acquisition Readout Pattern
TARGET ACQUISITION READOUT PATTERN [TACQ PATTERN] = NRS, NRSRAPID
This field specifies the readout pattern to be used to obtain the acquisition data.
Note that the TARGET ACQUISITION NUMBER OF GROUPS/INTEGRATION is automatically set to 3 and TARGET ACQUISITION NUMBER OF INTEGRATIONS/EXPOSURE is automatically set to 1.
SLIT [SLIT] = S200A1, S200A2, S200B1, S400A1, S1600A1, S200A1 AND S200A2
This parameter specifies the slit you wish to use for the science observations. Note that there is an option which will fill in the wavelength gap by using both the S200A1 slit and the S200A2 slit.
Table 1 shows the default and allowed SUBARRAYs for each SLIT.
Table 1. Subarrays allowed for each Slit
|Slit||Default Subarray||Allowed Subarrays|
|S1600A1||SUB2048||SUB2048, ALLSLITS,FULL, SUB512, SUB1024A, SUB1024B|
|S200A1 and S200A2|
SUBARRAY [SUBARRAY] = SUBS200A1, SUBS200A2, SUBS200B1, SUBS400A1, FULL, ALLSLITS, SUB512, SUB1024A, SUB1024B, SUB2048
This parameter specifies the region of the detector that is to be read out. The default subarray matches the slit chosen. The SUBARRAY selection should generally match the slit used, or a larger subarray can be used instead. However, if the readout pattern is NRSIRS2 or NRSIRS2RAPID, then SUBARRAY must be to FULL. For more details about these subarrays, see Slit and subarray.
Most NIRSpec Fixed Slit Spectroscopy observations will require dithering; see Dither parameters for details. Note that the dither pattern does NOT apply to the target acquisition image.
Primary "Down-the slit" Dither Positions
PRIMARY DITHER POSITIONS [PRIMARY_DITHER_POSITIONS] = NONE, 2, 3, 5
This parameter specifies the number of primary dither positions along the spatial (Y-axis) of the slit.
Note for developers: PRIMARY DITHER POSITIONS should be a required field, and there should be no default value (i.e. do not make NONE the default).
Sub-Pixel Dither Pattern
SUB-PIXEL DITHER PATTERN [SUBPIXEL_DITHER_PATTERN] = NONE, SPECTRAL, SPATIAL, BOTH
This parameter specifies whether or not to execute a sub-pixel dither pattern at each primary. This pattern is executed at each of the primary dither positions.
Note for developers: SUB-PIXEL DITHER PATTERN should be a required field, and there should be no default value (i.e. do not make NONE the default).
Note for developers: see NIRSpec Dithering Details for dithering details.
Science Exposure Specification
For each exposure to be executed at each position in a dither pattern, specify the GRATING/FILTER, READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION,
Note for developers: users can specify one or more combinations of the parameters below.
GRATING/FILTER [GRATING, FILTER] = G140M/F070LP, G140M/F100LP, G235M/F170LP, G395M/F290LP, G140H/F070LP, G140H/F100LP, G235H/F170LP, G395H/F290LP, PRISM/CLEAR
Select the name of the grating/filter combination you wish to use for the science observations.
In the case of choosing the slit option S200A1 and S200A2 only the high resolution gratings will be available.
Note for developers: When multiple gratings *and* the slit option S200A1 and S200A2 are chosen, minimize grating and filter wheel mechanism motion and lower the telescope slews by creating the activities in the following order: For each grating observe the two slits, then move to the next grating. For the next grating ensure that the slits are observed in the opposite order as the previous grating.
READOUT PATTERN [READOUT PATTERN] = NRS(default), NRSRAPID, NIRSIRS2, NIRIRS2RAPID
This field specifies the readout pattern to be used to obtain the science data. Note that there is a 100s overhead associated with switching between IRS2 and non-IRS2 readout patterns in an observation.
Note that NUMBER OF GROUPS/INTEGRATION x NUMBER OF INTEGRATIONS/EXPOSURE must be less than 256 for NRISIRS2 and 1024 for NRSIRS2RAPID.
SUBARRAY = FULL is the only legal value for the two IRS2 readout patterns.
Notes for developer: If the readout pattern is IRS2 or NRSIRS2, give an error if the SUBARRAY is not FULL . If there is interleaving of IRS2 and non-IRS2 readout patterns, issue a warning alerting the user to the 100 second overhead.
Number of Groups/Integration
NUMBER OF GROUPS/INTEGRATION [NGROUPS] specifies the number of groups in an integration. The maximum number of GROUPS/INTEGRATION is 65535.
Number of Integrations/Exposure
NUMBER OF INTEGRATIONS/EXPOSURE [NINTS] field specifies the number of times the integration is repeated. The maximum number of INTEGRATIONS/EXPOSURE is 65535.
Auto Calibration Exposure
The following parameter is used to request optional auto calibration exposure in order to compensate for the inaccuracy of the grating wheel sensors during data analysis.
AUTOCAL [AUTOCAL] = NONE(default), WAVECAL
This parameter specifies whether automatic wavelength calibration exposure(s) will be acquired after all science exposure readouts have been obtained for each grating/filter combination.
If NONE is chosen, then no automatic wavelength calibration exposures will be obtained.
If WAVECAL is chosen, the lamp used and the exposure time for calibration will be compatible with the selected science grating.
Note to developer: if AUTOCAL is not NONE, then the observation should get an implicit NO PARALLEL special requirement attached.
The documents used in preparing this chapter were the Preliminary Definition of Observing Templates for JWST Science Programs (Fullerton, Nov. 28, 2007) and the NIRSpec OCD (Boker and Valenti, V5, July 1, 2008).
Version 5 (April 19, 2019)
- Editorial change (moved change log to main article)
Version 4 (April 16 2018)
- Editorial change (fixed bad links)
Version 3 (October 16 2017)
- PR 85458 - added TA and other parameters to support WATA
- PR 87895 - updated terminology for Exposure parameters
- PR 88968 - revised overhead time for switching between IRS and IRS2 readout patterns
- PR 88047 - added restriction on NGroups x NINTs for IRS2 readout pattern
- PR 86097 - added TA=NONE option
- PR 79392 - added S1600A1 aperture
- PR 79393 - added table of allowed Subarrays for each slit
Version 2 (July 12, 2017)
- Fixed Target Acquisition to match GUI.
- PR 87895 - revised names of exposure parameters
Version 1 (June 7, 2016)
This is the converted Word File from Chapter 30.