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.

Introduction

Purple text indicates the parameter is Limited Access.

Boldface italics type indicates the name of an APT parameter or a value for a parameter.

(warning)Red text indicates restrictions on a parameter.

(red star) 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 article.

The NIRSpec Fixed Slit Spectroscopy template consists of the following parameters:

FieldDetailsValues Notes
General Information   
Observation Numberassign observation number

number



Observation Label provide observation labeltextoptional
Observation Commentsprovide observation commentstextoptional
Target Nameselect Target Namechoose from listfrom Target List

ETC Wkbk. Calc. ID

specify ETC Workbook Calculation IDnumberfor science exposures (optional) and target acquisition exposures
Mosaic Propertiesspecify mosaic parametersnumberif needed
Special Requirementsspecify special requirementschoose from listif needed
Template Specific Information   
Target Acquisition Parameters
 Target Acquisition Methodselect target acquisition methodchoose from list
MSA Target Acquisition Parameters
Reference Star Bin

list of reference stars and configuration 

choose from list
Acquisition Filterfilter name
set based on Reference star bin
Acquisition MSA Configuration Filename

select MSA configuration 

choose from list
Acquisition Readout Patternreadout pattern
set based on Reference star bin
WATA Target Acquisition Exposure Parameters


Acquisition Targetselect acquisition targetchoose from list
Acquisition Subarrayselect subarraychoose from list
Acquisition Filterselect filter namechoose from list
Acquisition Readout Patternselect readout patternchoose from list
Science Parameters
select slit name

choose from list


select subarray

choose from list


Dither Parameters
select number of dither positions

choose from list


select sub-pixel dither pattern

choose from list


Exposure Specifications
select grating/filter name

choose from list


select readout pattern

choose from list


specify number of groups/integration

number


specify number of integrations/exposure

number


select Auto Calibration option

NONE, WAVECAL


General Information 

The following parameters are generic to all templates, and are not discussed in this article:  Observation Number,  Observation Label , Observation Comments, Target NameETC Wkbk. Calc. ID, Mosaic Properties, and Special Requirements.

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 must specify a target acquisition for each individual Visit, the specification is done at the Visit level. Prior to specifying the acquisition, you must import a catalog including reference stars via the  MSA Planning Tool (see NIRSpec MPT - Planner). 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.

Note for developers: Give a warning when the MAXIMUM REFERENCE STARS special requirement is present for observations that are not NIRSpec TA Method=MSATA.

(red star) 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.

Acquisition Filter 

 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 NRSRAPID

or NRSRAPIDD6.

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 factFollowing 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.

Acquisition Target

The default for this parameter is "Same Target as Observation." 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.
  • 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.

Acquisition Subarray

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.

Acquisition Filter

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] = NRSRAPID (default), NRSRAPIDD6

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

Science Parameters

Slit 

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

SlitDefault SubarrayAllowed Subarrays
S200A1

SUBS200A1

SUBS200A1, ALLSLITS,FULL
S200A2

SUBS200A2

SUBS200A2, ALLSLITS,FULL
S200B1

SUBS200B1

SUBS200B1, ALLSLITS,FULL
S400A1

SUBS400A1

SUBS400A1, ALLSLITS,FULL
S1600A1SUB2048SUB2048, ALLSLITS,FULL, SUB512, SUB1024A, SUB1024B
S200A1 and S200A2

ALLSLITS

ALLSLITS, FULL

Subarray 

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.

 Dither Pattern 

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,  NUMBER OF INTEGRATIONS/EXPOSURE, and AUTOCAL. For the grating/filter bandpasses, see NIRSpec Dispersers and Filters. For more information on defining an exposure specification, see Create an exposure configuration.

Note for developers: users can specify one or more combinations of the parameters below.

Grating/Filter Name 

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.  

(warning) 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 [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.

(warning)Note that NUMBER OF GROUPS/INTEGRATION x NUMBER OF INTEGRATIONS/EXPOSURE must be less than 204 for NRISIRS2 and 1024 for NRSIRS2RAPID.

(warning) 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. (warning)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. (warning)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.

Change log

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 11 (May 11, 2022)

  1. PROPINSTJWST-91468  In Acquisition Target section, removed visit splitting error from developer note.  


Version 10 (October 20, 2021)

  1. PROPINSTJWST-91497 Removed developer note about error/warning.


Version 9 (August 9, 2021)

  1. Editorial change - Anchor links fixed in parameter table by removing pagename from link.


Version 8 (June 19, 2020)

  1. PROPINSTJWST-91483 Added developer note for MAXIMUM REFERENCE STARS special requirement. 


Version 7 (October 2, 2020)

  1. PROPINSTJWST-89341  Changed NGroups*Nints limit for NIRSIRS2 readout pattern from 256 to 204. 


Version 6 (September 17, 2019)

  1. PROPINSTJWST-91408 - Replaced NRS with NRSRAPIDD6 in TA Readout Pattern.


Version 5 (April 19, 2019)

  1. Editorial change (moved change log to main article)


Version 4 (April 16 2018)

  1. Editorial change (fixed bad links)


Version 3 (October 16 2017)

  1. PR 85458 - added TA and other parameters to support WATA
  2. PR 87895 - updated terminology for Exposure parameters
  3. PR 88968 - revised overhead time for switching between IRS and IRS2 readout patterns
  4. PR 88047 - added restriction on NGroups x NINTs for IRS2 readout pattern
  5. PR 86097 - added TA=NONE option
  6. PR 79392 - added S1600A1 aperture
  7. PR 79393 - added table of allowed Subarrays for each slit


Version 2 (July 12, 2017)

  1. Fixed Target Acquisition to match GUI.
  2. PR 87895 - revised names of exposure parameters


Version 1 (June 7, 2016)

This is the converted Word File from Chapter 30.