NIRSpec Bright Object Time-Series APT Template

Detailed step-by-step instructions are available for filling out the JWST NIRSpec Bright Object Time-Series APT template.

On this page

See also: NIRSpec Bright Object Time-Series Spectroscopy, JWST Time-Series Observations RoadmapNIRSpec BOTS Observations of WASP-79b

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

The JWST NIRSpec bright object time-series (BOTS) mode is designed for observations of bright sources that require high throughput and stable time-resolved spectroscopy. A BOTS observation is carried out with NIRSpec's S1600A1 aperture. This is a 1.6" square aperture that can be accessed in both the fixed slits (FSs) and BOTS modes. More information on the BOTS observing mode can be found in the article NIRSpec Bright Object Time-Series Spectroscopy. Additional information on the S1600A1 aperture can be found in the article NIRSpec Fixed Slits.

This article deals with the preparation of a NIRSpec bright object time-series observation using the NIRSpec BOTS Astronomer's Proposal Tool (APT) template.

Step-by-step APT instructions

We assume the observer has already defined Target(s) to be observed, created an Observation folder, and loaded the NIRSpec BOTS template. Instructions for doing this are presented in the JWST Astronomers Proposal Tool.

The BOTS template can be divided into 4 sections, as shown in Figure 1. 

  • Section 1: this section shows that the NIRSpec BOTS spectroscopy template has been selected, along with a Target defined by the user. 
  • Section 2: the area defined as section 2 contains parameters that are for the proposer's information. The observer cannot edit this section.
  • Section 3: in this section the observer enters the Target Acquisition Parameters.
  • Section 4: in this section the user defines the Science Parameters that determine the specifics of the observation.

Section 3 and 4 fall are under the NIRSpec Bright Object Time Series tab. There are 2 additional tabs (Special Requirements and Comments) that are discussed at the end of this article.

Figure 1. The NIRSpec BOTS spectroscopy template

IFU template tabs

Different sets of parameters are available when the following tabs (between sections 2 and 3) are selected: NIRSpec Bright Object Time Series shows target acquisition and science observation parameters for the IFU. Mosaic Properties displays parameters required for mosaics. Special Requirements are used to place constraints on the observations, and Comments are for observing notes.

BOTS template section 1: Generic information

The following parameters are generic to all templates: Observation Number, Observation LabelTarget name, and ETC Workbook Calculation ID (ETC Wkbk. Calc ID). The Target is defined in the Targets folder of the APT file. The ETC Workbook IDs are entered in sections 3 and 4 (Figure 1). 

BOTS template section 2: Observation information

These fields are included for information only, they are common to all templates and cannot be edited. These items are discussed in articles on Visit Splitting, Duration, and Data volume. 

BOTS template section 3: Target acquisition parameters

See also: NIRSpec Target Acquisition, NIRSpec Wide Aperture Target AcquisitionNIRSpec Target Acquisition Recommended Strategies

Section 3, as shown in Figure 1 is where the user specifies the Target Acquisition Parameters. For the NIRSpec bright object time-series observation mode, the TA method called WATA is recommended. Suggested absolute coordinate accuracies for the acquisition target are on the order of 150 milliarcsec or better to ensure that the acquisition target falls into the S1600A1 acquisition aperture. 

NONE is an option for the TA method, though it is not recommended until it has been demonstrated that the expected blind pointing accuracy has been realized. The resulting pointing accuracy will be then delivered by the GS acquisition at the start of the observation. For reference, the absolute pointing accuracy of JWST is expected to be 0.1" (one sigma, per axis), compared to the 1.6" square aperture. 

The WATA procedure typically starts with placing the science target in the S1600A1 aperture and centering it with onboard software. In this case, the Acq Target is the science target. It is also possible to use WATA with an offset target. In that case, the offset target is defined in the Targets folder of the APT proposal, and can then be selected as the Acq Target in APT. When using an offset target, it is important to ensure that the relative astrometric accuracy of the 2 targets is sufficient to place the science target in the S1600A1 aperture. In either case, WATA is appropriate for targets that are point sources or nearly point sources.

When selecting WATA as the TA Method, parameters for section 3, as shown in Figure 1, are displayed. In this section, observers can define the remaining TA parameters: the Acq Subarray, AcqFilter, and the Acq Readout Pattern. The options for the subarray are SUB32, SUB2048, and FULL. Options for filter are F110W, F140X, and CLEAR. The available Readout Patterns are NRS and NRSRAPID. These will be used to calculate the TA exposure time. 

The WATA procedure will always acquire a 3-group exposure using the AcqFilter and Acq Readout Pattern selected by the user. The JWST Exposure Time Calculator (ETC) in target acquisition imaging mode should be used to estimate the exposure parameters. The desire is to produce a suitably strong signal (minimum of S/N = 20) in each group of the 3-group image without saturating the exposure. For quick reference, approximate magnitude ranges for S/N = 20 to saturation for WATA are given in the article NIRSpec Wide Aperture Target Acquisition.

BOTS template section 4: Science parameters

See also: Understanding JWST Exposure Times, NIRSpec Detector Recommended Strategies

The Science Parameters are shown in section 4 of the BOTS spectroscopy template and a detail of this section is shown in Figure 2.

Figure 2. The Science Parameters for the NIRSpec BOTS template

Science Parameters section the BOTS APT template. This is where the BOTS exposure parameters are defined.
BOTS observations always use the NIRSpec S1600A1 slit. For this reason, there is no slit option in the BOTS APT template. The JWST ETC should be used to determine the best exposure configuration to optimize the signal to noise of the integrations in the time-series exposure. Once the number of groups in an integration is known (from the ETC), the number of integrations can be calculated to span the necessary time series. If 65,535 integrations or less is enough to cover the necessary time series, then only one exposure is needed. If not (e.g., for long phase curves), the time series should be split into 2 or more exposures. In the Science Parameters section of the template, the user needs to specify several parameters that define the exposure parameters. A BOTS exposure is configured by setting the Subarray, the Grating/Filter combination, Readout PatternGroups/IntIntegrations/Exp , and Exposures/Dith as shown in Table 1.  


Table 1. Definition of parameters needed to fill out Science Parameters (section 4) of the BOTS template

Exposure parameterDescription
The options for the subarray using slit S1600A1 in BOTS mode are SUB512, SUB512S, SUB1024A, SUB1024B, and SUB2048. The recommended choice is to use the largest subarray possible that does not saturate. The subarray properties and the exposure parameters for a BOTS observation are listed in the article NIRSpec Detector Subarrays.

Select a grating/filter combination from the pull-down menu.

As for all other NIRSpec modes, the observer can select between PRISM (low resolution, full wavelength coverage) and medium and high resolution gratings (in 4 different bands).


The number of exposures to be taken in this observation. Each exposure contains the same number of integrations as specified below. Multiple exposures are used to span the necessary duration of the requested time series.
Readout Pattern

The default value is NRSRAPID, but NRS is also available. NRSRAPID can provide the highest time resolution and sensitivity and is generally recommended for BOTS observations. Proposers are encouraged to use the ETC to verify the best readout mode for their observations.

The IRS2 readout patterns cannot be used with subarrays, and therefore are not available in BOTS mode.

Groups/IntThis represents the number of groups during an integration, and determines the length of a single integration. The value to be used to achieve a given SNR and avoid saturation in that integration can be determined using the ETC.  
Integrations/ExpThis represents the number of integrations during an exposure, where integration is defined as the time between the detectors' resets. This number determines the total length of the exposure and the level of sensitivity that can be achieved. The number of integrations per exposure should be set to span the length of the transit. The minimum number of integrations allowed per exposure is 2 and the maximum number is 65,535.

Other important parameters for BOTS mode

Special requirements

Specification of the proper starting point and phase coverage of a time series requires addition of Timing special requirements to the BOTS observations in APT. The Special Requirements for time-series observations that likely need to be defined are described (and linked) in Table 2.  

Table 2. The special requirements to specify observation timing in the BOTS template 

Exposure ParameterDescription
Specification of the earliest time for the start of the first BOTS science action in the visit.

Specification of the latest time for the start of the first BOTS science action in the visit.


PERIOD specifies the period of the time series source (in days)

Specifies the time of the nominal zeropoint reference for the target (as a Heliocentric Julian Date).

For example, PHASE RANGE (Start) = 0.0 to PHASE RANGE (End) = 0.1 would specify that the start of the first science activity must be scheduled within the first 10% of the time-series period. Another example for a transiting exoplanet observation is discussed in the article Step-by-Step APT Guide for NIRSpec BOTS Observations of WASP-79b.

Tight timing constraints that result in a narrow observation execution window (less than 24 hrs) will result in a direct scheduling overhead of 1 hour. All tightly constrained NIRSpec BOTS observations will be affected by this overhead.


The Comments field should be used only to record observing notes.

Latest updates
    Figure 1 and 3 updated.
    BOTS template section 1 updated.
    Minor updates to Table 1.
Originally published