NIRSpec Bright Object Time Series Template Parameters

JWST's NIRSpec Bright Object Time Series 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 Bright Object Time Series template is to be used for all observations using the bright object 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 Bright Object Time-Series APT Template article and in NIRSpec Bright Object Time-Series Spectroscopy.

The NIRSpec Bright Object Time Series 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
Special Requirementsspecify special requirementschoose from listif needed
Template Specific Information   
Target Acquisition Parameters
 Target Acquisition Methodselect target acquisition methodNONE, WATA
WATA Target Acquisition Parameters
Acquisition Targetselect acquisition targetchoose from list
Acquisition Subarrayselect subarraychoose from list
Acquisition Filterselect filterchoose from list
Acquisition Readout Patternselect readout patternchoose from list
Science Parameters 
select subarray

choose from list


select grating/filter name

choose from list


Number of Exposures/Ditherspecify the number of times to repeat the exposure at each dither positionnumber
select readout pattern

choose from list


specify number of groups per integration

number


specify number of integrations per exposure

number


Note for developer: This template cannot be used in parallel and cannot have parallels attached to it; the NO PARALLEL special requirement should be added. The TIME SERIES OBSERVATION special requirement should also be added.

General Information   

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

Target Acquisition Parameters

Target Acquisition (TA) Method

TA METHOD [TA METHOD] = NONE, WATA (default)

For NIRSpec Bright Object Time Series spectroscopy there are two options: NONE which performs no target acquisition, or 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 BOTS Template Section 3: Target Acquisition Parameters. 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 WATA can be used for moving targets, but offset acquisition targets are not allowed when the science target for time series 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.

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 aperture prior to the start of the science exposures; see BOTS Template Section 3: Target Acquisition Parameters .

For this method of TA, the following parameters are used to define NIRSpec 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.

Notes for developers:

  • For APT, the ACQUISITION TARGET field should always be present, but should be defaulted to SAME TARGET AS OBSERVATION.
  • 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 into the S1600A1 aperture) and Science pointing (to place the science target into the same 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 acquisition target and pointing within the visit.

Acquisition Subarray

TARGET ACQUISITION SUBARRAY [TACQ SUBARRAY] = SUB32 (default), 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

Subarray 

SUBARRAY [SUBARRAY] = SUB512, SUB512S, SUB1024A, SUB1024B, SUB2048 

 This parameter specifies the region of the detector that is to be read out. For details, see Subarray in Table1  of the NIRSpec Bright Object Time-Series APT Template article.

Grating/Filter 

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. For the grating/filter bandpasses, see NIRSpec Dispersers and Filters.

Number of Exposures/Dither

NUMBER OF EXPOSURES/DITHER [NEXPspecifies the number of exposures at each dither point. (warning)The maximum NUMBER OF EXPOSURES/DITHER is 50.

Exposure Specification

For each exposure, specify the READOUT PATTERN, NUMBER OF GROUPS/INTEGRATION, and NUMBER OF INTEGRATIONS/EXPOSURE.

 Readout Pattern 

READOUT PATTERN [READOUT PATTERN] = NRS, NRSRAPID  (default)

 This field specifies the readout pattern to be used to obtain the science data.

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.

Change log

The initial version of this chapter was provided by Dennis Garland.


Version 8 (May 11, 2022)

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


Version 7 (September 17, 2019)

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


Version 6 (April 19, 2019)

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


Version 5 (December 27, 2017)

  1. PR 88411 - added developer note about TSO and NO PARALLEL requirements


Version 4 (September 15, 2017)

  1. PR 88069 - added TA and other sections to support WATA
  2. PR 87895 - updated terminology for Exposure parameters
  3. PR 88762 - added limit to Num of Exp/Dither
  4. PR 86097 - added TA=NONE option
  5. PR 82876 - added Number of Exposures/Dither parameter


Version 3 (May 11, 2017)

  1. PR 85270 - added new Subarray (SUB512S)


Version 2 (February 21, 2017)

  1. PR 87071 - removed mosaics option


Version 1 (June 9, 2016)

This is the converted Word File from Chapter 33.