NIRCam Grism Time-Series APT Template
Instructions for designing JWST NIRCam grism time-series observations using APT, the Astronomer's Proposal Tool, are provided in this article.
Starting in Cycle 4 (APT 2024.5) the template offers slitless grism spectroscopy in the short wavelength channel as well as in the long wavelength channel. See NIRCam Short Wavelength Grism Time Series
On this page
See also: NIRCam Grism Time Series, NIRCam Short Wavelength Grism Time Series, JWST Time-Series Observations Roadmap, NIRCam Time-Series Observation Recommended Strategies, NIRCam Grism Time-Series Observations of GJ 436b and NIRCam Short Wavelength Grism Time Series Observing Strategies
Grism time series is one of the 5 NIRCam observing modes and one of 2 NIRCam time-series observing modes. Each mode has a corresponding template in APT for users to design their observing programs.
This mode uses only module A, with the GRISMR element in the long wavelength channel (2.4–5.0 µm). The LW grism is paired with either one of the NIRCam weak lenses, or (new for Cycle 4) with the Dispersed Hartmann Sensor (DHS) grisms in the short wavelength channel (0.6–2.3 µm). The SW and LW data are obtained simultaneously.
No telescope moves (dithering nor mosaics) are allowed during NIRCam time-series observations.
Lists of allowed values for each input parameter are documented and maintained in the NIRCam Grism Time-Series Imaging Template Parameters article.
Step-by-step APT instructions are provided below.
Generic parameters
Words in bold are GUI menus/
panels or data software packages;
bold italics are buttons in GUI
tools or package parameters.
NIRCam Grism Time Series tab
SW Channel Mode selector
This is a new selector available starting with Cycle 4. If IMAGING is selected, the template works as it has in previous cycles: the LW grism is paired with weak lens imaging in the SW channel. If GRISM is selected the SW channel will be configured with the Dispersed Hartman Sensor (DHS) grisms, which provide spectra of the target. For details on how the SW DHS grisms work in coordination with the LW grism for time-series observations, see NIRCam Short Wavelength Grism Time Series.
If an older proposal is used as a template for a new proposal that will use the DHS grisms, users must set the Cycle to 4 (or greater) on the Proposal Information form in APT. Failure to do the first will prevent the SW Channel Mode selector from appearing on the Grism Time Series Observation Template. If the older template proposal was accepted, the Proposal ID will also have to be deleted from the new proposal.
Target Acquisition Parameters
Target ACQ
See also: NIRCam Grism Time-Series Target Acquisition, JWST ETC NIRCam Target Acquisition
Users can opt to do target acquisition (TA) on the science target or a nearby object. Target acquisition (TA) occurs with a 32 × 32 pixel subarray on the long wavelength channel of module A located near the grism field positions. If the SW Channel Mode selector is set to IMAGING, the TA subarray (and science subarrays) is located near the -V3 edge of the LW detector; if it is set to GRISM the TA subarray (and science subarrays) is located near the center of that detector (see Figure 1). Other than using different TA subarrays, all other TA parameters are the same regardless of the SW Channel Mode value.
A target acquisition object other than the science target should be defined in the Targets form in order for it to appear in the Acq Target pull-down menu. If the science target is used for target acquisition, set the Target Acq field to Same Target as Observation.
The filter for TA is set using the Acq Filter pulldown. The F405N filter is used to perform TA on very bright targets that would saturate if observed with the F335M filter. Saturation limits should be assessed using the ETC.
Acq Exposure Time
Acq Readout Pattern: The NIRCam detectors are read out continuously using readout patterns. Patterns with longer exposure times typically average more frames to reduce data volume (which is less of a concern for subarrays).
Acq Groups/Int: This value is the number of groups to include during an integration. Each group results in a saved image, which may be averaged from multiple frames (reads), depending on the readout pattern.
Only one integration per exposure is permitted.
Grism Time Series Parameters
While many of the menus and parameter fields in the template are the same regardless of whether SW Channel Mode is IMAGING or GRISM, in several instances the available values are completely different depending on that setting. Where there are differences, they will be described separately with an informational note that there is a dependence.
Subarray
See also: NIRCam Detector Subarrays, NIRCam Multistripe Subarrays
Available subarrays depend on whether SW Channel Mode is set to IMAGING or GRISM.
Subarrays for the Grism Time Series template have the same number of columns (2048 in all cases) and rows of pixels on each of the active detectors. Because of the difference in pixel scale in the SW and LW channels the dimensions on-sky are about 1/2 as large in the SW channel relative to the LW channel.
Subarrays for SW Channel Mode = IMAGING
In this case, detectors A1, A3 and ALong are read out, and observers can choose to use the full detector or more quickly read out much smaller detector subarrays; the subarrays provide brighter saturation limits in each integration.
The SW subarrays are centered vertically within the long wavelength subarray's footprint on the sky.
Note that the weak lenses WLP4 and WLP8 produce defocused images roughly 66 and 140 pixels across, respectively. Therefore, WLP8 images would be significantly truncated by the smallest subarray SUBGRISM64.
Table 1. Subarrays characteristics for SW Channel Mode = IMAGING
Grism | Size in pixels | Short-wavelength | Long-wavelength | Frame | No. of output channels |
|---|---|---|---|---|---|
| FULL | 2048 × 2048 | 64" × 64" | 129" × 129" | 42.23000 10.73677 | 1 4 |
| SUBGRISM256 | 256 × 2048 | 8.1" × 64" | 16.6" × 129" | 5.31480 | 1 4 |
| SUBGRISM128 | 128 × 2048 | 4.1" × 64" | 8.1" × 129" | 2.67800 0.67597 | 1 4 |
| SUBGRISM64 | 64 × 2048 | 2.0" × 64" | 4.0" × 129" | 1.35960 0.34061 | 1 4 |
Subarrays for SW Channel Mode = GRISM
See also: NIRCam Multistripe Subarrays. and NIRCam Short Wavelength Grism Time Series
In this case, all 5 module A detectors are read out, and only subarrays (not full-frame) are available. An advantage of these subarrays over those in Table 1 is that all of these include 4 rows of reference pixels.
The three larger subarrays in this mode are split into multiple "substripes" as indicated in Table 2, below. The SW channel substripes sample 2, 4 or 8 of the DHS spectra, while on the LW detector a single substripe, centered on the single grism spectrum, is read out each time one of the SW substripes is read out.
All of these subarrays have stripe sizes that are smaller than the subarray sizes available when SW Channel Mode = IMAGING, so the bright limits are brighter when the SW channel is configured with the DHS grisms.
Table 2. Subarray characteristics for SW Channel Mode = GRISM
Subarray APT Name | Stripe size in pixels | Short-wavelength FOV per stripe | Long-wavelength stripe FOV | # Substripes per SCA | # SW Spectra sampled | Subarray frame time (tFrame) |
|---|---|---|---|---|---|---|
SUB40S1_2-SPECTRA | 36 x 2048 | 1.1" x 64" | 2.3" x 129" | 1 | 2 | 0.21485 |
SUB80S2_4-SPECTRA | 38 x 2048 | 1.2" x 64" | 2.4" x 129" | 2 | 4 | 0.42445 |
| SUB160S4_8-SPECTRA (SUB160STRIPE4_DHS) | 39 x 2048 | 1.2" x 64" | 2.5" x 129" | 4 | 8 | 0.84365 |
| SUB256S4_8-SPECTRA (SUB256STRIPE4_DHS) | 63 x 2048 | 2.0" x 64" | 4.0" x 129" | 4 | 8 | 1.34669 |
* Nrows excludes 4 rows of reference pixels that are read prior to reading the substripe(s). The stripe time is given by (tFrame - 0.02096 s) / nStripes.
. Refer to the "Multistripe timing equations" section in NIRCam Multistripe Subarrays for full detail.
Number of output channels
See also: NIRCam Detector Readout, JWST Data Volume and Data Excess
Subarrays with 2048 columns, as all grism time series subarrays do, may be read out through a single output channel or more quickly through 4 output channels simultaneously. The latter produces roughly 4 times as much data for a given exposure time, and allows non-saturating integrations on targets about 4 times (1.5 magnitudes) brighter. Data rates and data volumes are calculated by APT and warnings occur if certain thresholds are crossed due to limited down-link bandwidth (see JWST Data Volume and Data Excess).
When SW Channel Mode is IMAGING, either 1 or 4 output channels can be selected; when it is GRISM, 4 output channels are used because they are only expected to be used for the very brightest targets, and those will saturate in the LW channel unless 4 outputs are used.
Number of exposures
Multiple exposures may be performed in sequence to increase the total length of the time series observation. Each exposure is executed as defined in the remaining sections below, with only very short interruptions between the exposures. No reconfigurations of the subarrays, pupil or filter wheels, or changes in pointing occur between these exposures.
In APT, this section is named Exposures/Dith (exposures per dither) for consistency with other observing modes, even though no dithering is allowed in this mode.
Short pupil + filter
Available short wavelength pupil and filter choices depend on whether SW Channel Mode is set to IMAGING or GRISM
When SW Channel Mode is IMAGING, the SW channel must be configured using a weak lens (these are elements included in NIRCam to enable phasing of the primary mirror segments). Two weak lenses are available :
- WLP8 (8 waves of defocus at 2.12 µm)
- WLP4 + F212N2 (4 waves of defocus at 2.12 µm; coupled to a 2.12 µm narrowband filter with a 2.3% bandpass)
The weak lenses defocus incoming light, mitigating uncertainties (jitter and flat fields) and allowing for observations of brighter objects before saturation in a given integration time.
WLP4 includes a narrowband filter similar to F212N, but with a 2.3% bandpass (compared to the 1% bandpass F212N filter). WLP4 + F212N2 is used in combination with the CLEAR element in the pupil wheel.
WLP8 is located in the pupil wheel and can be used in combination with one of a variety of medium- or narrowband filters as shown in the table below.
| Short wavelength pupil wheel | Short wavelength filter wheel |
|---|---|
| WLP8 | F070W, F0140M, F182M, F187N, F210M, or F212N |
| CLEAR | WLP4 + F212N2 |
When SW Channel Mode is GRISM, the SW channel will be configured with the GDHS0 element in the pupil wheel, which can be paired with several blocking filters in the filter wheel as shown in the table below. See the NIRCam Short Wavelength Grism Time Series article for more details on the sensitivity and saturation limits for the various combinations.
| Short wavelength pupil wheel | Short wavelength filter wheel |
|---|---|
| GDHS0 | F070W, F090W, F115W, F150W, F150W2, F200W |
Long pupil + filter
The row dispersion grism GRISMR (in the pupil wheel) is used in combination with a wide long wavelength filter (in the filter wheel): F277W, F322W2, F356W, or F444W. See NIRCam Grism Time Series for more details.
Exposure time
See also: Understanding JWST Exposure Times
Each exposure is defined as a Readout Pattern, number of groups (Groups/Int), and number of integrations (Integrations/Exp). The resulting Total Exposure Time is reported. This readout configuration applies to both wavelength channels (short and long); the observations are obtained simultaneously using a dichroic.
Users should consult the Exposure Time Calculator (ETC) to achieve a sufficient signal-to-noise ratio for their science without saturating during each integration. Approximate saturation limits may be found in the NIRCam Grism Time Series article.
Each group yields saved data. Each integration accumulates charge for its duration, preceded and followed by detector resets. Shorter integrations may prevent saturation. Saturated sources may be recovered (unsaturated) in earlier groups during the integration.
Each exposure is performed without moving the telescope nor any mechanisms, with one exception; exposures of more than 10,000 s are permitted in this observing mode, but users are warned that the high gain antenna (HGA) may need to move during a longer exposure. That movement has an impact on pointing stability lasting approximately 60 s during which light curve scatter can be increased. An analysis of commissioning data indicates that the target location on the detector is restored to 1 mas following an HGA move (Schlawin et al., 2022).
Other tabs
Special Requirements
A variety of observatory level Special Requirements may be chosen under the Special Requirements tab.
When NIRCam is used in the time-series mode, two special requirements are automatically included and required: Time Series Observation and No Parallel. Users are encouraged to determine Phase limits by making use of the ExoCTK's Phase Constraint Calculator.
Mosaics are not available for NIRCam time-series imaging.
Comments
The Comments field (under the Comments tab) should be used for observing notes.
References
Schlawin, Everett, et al., 2022, PASP, 135, 018001
JWST NIRCam defocused imaging: photometric stability performance and how it can sense mirror tilts.