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

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 2019-10-07_22-13-22_JWST Astronomers Proposal Tool Overview OLD.

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

  • Section 1: this section shows that the NIRSpec BOTS Spectroscopy Template has been selected, along with a Target1 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 within the "NIRSpec Bright Object Time Series" tab. There are two additional tabs ("Special Requirements" and "Comments") which are discussed at the end of this article.

Figure 1. The NIRSpec BOTS spectroscopy template

1  Bold italics font style is used to indicate parameters, parameter values, and/or special requirements that are set in the APT GUI.

BOTS template section 1: generic


The following parameters are generic to all templates, and are not discussed in this article: Observation Number, Observation LabelObservations CommentsTarget Name, ETC Workbook Calculation ID, Mosaic Properties, and Special Requirements.

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

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

NONE is also an option for the TA method, though it is not recommended in most cases. The resulting pointing accuracy will be that delivered by the GS acquisition at the start of the Observation. For reference, the absolute pointing accuracy of JWST is expected to be 0.45 to 0.3 arcseconds (one sigma, per axis), compared to the 1.6" square aperture. A three-sigma excursion in the blind pointing could place the source outside the 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 Target 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 two 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, Section 3 looks as it does in Figure 1. In this section, observers can define the remaining TA parameters: the Acq Subarray, Acq Filter, and the Acq Readout Pattern. The options for Subarray are SUB32, SUB2048, and FULL. The 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 three-group exposure using the Acq Filter 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 three group image without saturating the exposure. For quick reference, approximate magnitude ranges for S/N = 20 to saturation for WATA are shown in Table 2 of the article NIRSpec Wide Aperture Target Acquisition.

BOTS template section 4: science parameters

The Science Parameters are defined 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 must be defined.
BOTS observations always use the NIRSpec slit S1600A1. 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 the number of integrations is small enough (<65535)  for one exposure to cover the necessary time series, then one exposure only is needed.  If not (e.g., for long phase curves), the time series should be split into two 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 SubarrayGrating/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 four 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 maximum number of integrations allowed per exposure is 65535.

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 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 zero-point 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 NIRSpec BOTS Observations of GJ 1214b.

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 updated
    BOTS template section 1 updated
    Figure 3 updated
    Minor updates to Table 1