NIRCam Time-Series Observation Recommended Strategies

Best practices for developing time-series observations (TSOs) with JWST's Near Infrared Camera (NIRCam), relevant for both time-series imaging and grism time-series observations (exceptions are noted), are provided in this article.

On this page

The following "best practices" for NIRCam time-series observations (TSOs) are procedures recommended as being correct or most effective in addressing key issues in observation planning for most science cases. Such issues include (1) balancing long wavelength (LW) and short wavelength (SW) exposure times and filter choices, (2) avoiding saturation, and (3) dealing with target acquisition requirements and limitations. In addition, data volume may be an issue for long NIRCam TSO observations, and may require adjusting readout pattern and number of groups to avoid over-filling the solid state recorder (SSR). Finally, most TSOs are time critical observations and require a continuous data collection on-target between particular times. Therefore, most TSOs including observations of exoplanet transits, secondary eclipses, stellar occultations by solar system minor bodies should have timing constraints along with the relevant instrument setting.  

JWST NIRCam offers 2 observing modes for precision NIRCam TSO observationstime-series imaging and grism time series. The unique features of all TSOs are long observing times, lack of dithering, and target acquisition to improve calibration stability. Observations using these modes can be specified using APT templates for time-series imaging and grism time series. In the former, both the short wavelength (SW) and long wavelength (LW) channels are configured for photometry, while for grism time series, the SW channel is configured for photometry and the LW channel is configured with the slitless grism. In both modes, the SW channel may be configured for normal imaging or with one of NIRCam's weak lenses (only the TSO templates offer this option). In both templates SW and LW detectors will be configured using the same readout pattern and exposure time parameters (e.g., Ngroups, Nints), as well as subarray dimensions.

Example Exposure Time Calculator (ETC) workbooks for TSOs and detailed planning templates for NIRCam TSO observations are accessible from these articles (and their child pages): NIRCam Grism Time-Series Observations of GJ 436b and NIRCam Time-Series Imaging of HAT-P-18 b.

Observers are encouraged to make use of the PandExo tool specifically for grism time-series spectroscopy. PandExo uses the ETC Pandeia engine, but provides built-in functionality relevant for planning spectroscopy of transiting exoplanets with JWST. When employing PandExo, observers have two options: (1) determine optimal observing settings via the Groups & Integrations Calculator, and/or compute expected precision of JWST observations with the same optimal settings and compare to theoretical transmission or emission spectra via PandExo's New JWST Calculation

The JWST ETC includes 3 calculation types for estimating SNR and saturation for NIRCam TSO observations:

  • SW time series: for the SW channel for either the time-series or grism time-series APT templates
    • includes the NIRCam weak lenses, which are only available in the TSO observation templates
    • requires observers to choose whether the calculation is part of a time-series or grism time-series observation in order to present appropriate filter/weak lens choices
  • LW time series: For the LW part of the time-series APT template
  • LW grism time series: For the LW part of the grism time-series APT template

When using the ETC, users must use the same exposure parameters, including subarray size, for both the SW and LW calculations. APT imposes this limit on exposures taken in the 2 channels, but the ETC treats the calculations independently, as if there is no such constraint. Users should also follow the ETC note directing them on how to estimate SNR: the relevant calculation is for the light curve sampling time they wish to achieve. For example, if a 2-hour-long transit is to be observed and a measurement is needed every 1,000 s, the user should configure the exposure parameters in the ETC to give a 1,000 s exposure time.


Balancing LW and SW exposure times

Because integration times in both the SW and LW channels of NIRCam are the same for a given observation, filters with similar sensitivities and saturation limits should typically be used in the 2 channels. The ETC should be used to optimize exposures in a SW and a LW filter while using the same exposure parameters in the 2 calculations.

In time-series imaging, it might be appropriate to choose either a pair of wide filters (e.g., F150W and F356W) or 2 narrow filters (e.g., F212N and F323N), although for stellar sources the lower flux in the LW channel could allow for combining a medium with a wide, or a narrow with a medium, SW and LW filter. This template also allows users to select the WLP8 element (a weak lens) in the SW channel, allowing very bright sources to be observed without saturation. The weak lens also spreads the light out on the detector, and may provide higher precision by mitigating flat field uncertainties. When WLP8 is selected, the LW channel is limited to one of the narrow filters to help avoid saturating the in-focus images in that channel.

In grism time series, the LW channel is configured with the slitless grism, which can be paired with one of 4 wide filters: F277W, F322W2, F356W, or F444W. Because the resolving power of the grism is approximately 1,600, exposures that significantly fill the well of pixels on the LW detector would normally strongly saturate the SW channel. To mitigate saturation in the SW channel, observers must select a weak lens (which spreads the light out over many pixels), paired with one of the SW filters.

Observers should avoid saturation of any part of their data that occurs in less than 4 groups of their integrations. This will provide 3 groups for determining the flux while avoiding undue reliance on the linearity correction. While the APT templates for both the time-series and the grism time-series modes provide some guidance intended to prevent heavily saturating one NIRCam channel when the other channel is exposed to nearly the full-well limit, observers must refer to the ETC to make sure that neither channel is saturating. Users must use the same exposure parameters, including subarray size, for both the SW and LW calculations.

SW subarrays and weak lens PSF size

NIRCam TSO mode observations allow the use of the WLP4 or WLP8 weak lenses in the SW channel. These produce images 66 pixels (2") or 132 pixels (4") across. Depending on the subarray selected, significant portions of the weak lens PSF may fall outside the subarray, or fill enough of it that measuring sky background will be difficult. For comparison, the NIRCam TSO subarray sizes which may result in these problems are:

Grism time series

  • 2048 × 128 – width is smaller than the WLP8 image
  • 2048 × 64 – width is smaller than the WLP8 image, comparable to the WLP4 image

Time series

  • 160 × 160 – comparable in size to the WLP8 image, probably OK for determining background
  • 64 × 64 – smaller than the WLP8 image, comparable to the WLP4 image. Source is not centered in the subaray.

Target acquisition and proper motion

Target acquisition (TA) should normally be specified for NIRCam time-series imaging and grism time-series observations. TA will guarantee that all TSO observations utilize the same detector pixels, and over the long term it will be possible to combine many observations to provide very high-precision calibration for those regions of the detectors. TA will also guarantee that science and calibration observations are taken in exactly the same way, providing better removal of instrumental signatures early in the mission, and maximizing reproducibility when coadding multiple transits to improve SNR, and when comparing transits of different exoplanets.

To ensure that target acquisition is successful, the observer should take care to provide accurate coordinates and proper motion for the target. In addition, providing an annual parallax is highly recommended particularly for bright stellar sources to guarantee an accurate target acquisition. The NIRCam TSO target acquisition subarrays have a 2" × 2" field of view, so the target location at the epoch of observation should ideally be specified with a 1-sigma radial accuracy no worse than about 0.25". When combined with the nominal  0.14" 1-sigma radial pointing accuracy of JWST, that should be enough to guarantee success of the TA. It is highly recommended that observers provide target coordinates, proper motion, and annual parallax from the Gaia (DR2) catalog, or other catalogs or observations with high accuracy.

The bright limit using the F405N filter for TA in the NIRCam TSO modes is approximately mK(Vega) = 3.5 – 4.0, depending on spectral type of the target. This should be adequate to allow direct TA on currently known exoplanet host stars, but may not be for newer discoveries, e.g., from TESS. For host stars too bright for direct TA, an offset star can be used. If an offset target is used for TA, the same (if not higher) accuracy as discussed above is needed for both the TA and science targets.

Grism time-series observations

Filter choices

The LW grism must be used with one of NIRCam's LW channel wide filters; the 2 most functional filters for time-series spectroscopy are the F322W2 (2.4–4.0 μm) and F444W (3.9–5.0 μm) filters. The F277W and F356W filters are also available for time-series observations, but their wavelength coverage is fully included within the range covered by the F322W2 filter. The F277W and F356W filters could potentially be used to block the 2nd order spectrum from nearby targets from overlapping the spectrum of the science target, or to reduce background noise for targets in regions with high background emission. Because the filter choice is specified at the observation level for the NIRCam TSO APT templates, if coverage of the entire 2.4–5 μm region is desired for a target, multiple observations, covering separate transit events, must be specified.

In the SW channel, users must select either the WLP4 or WLP8 weak lenses. These lenses defocus the image, resulting in PSFs approximately 66 pixels (2") and 132 pixels (4") across, respectively. The WLP4 element has an integrated narrowband filter at 2.12 μm; the WLP8 element may be paired with most of the SW filters.

Spectroscopic and image overlap 

The NIRCam LW grisms are slitless, so there is the potential for spectra from sources near the science target to overlap with its spectrum. Observers should determine valid orientations for observations of their target using the General Target Visibility Tool (GTVT), and then visualize their observation using APT/Aladin while specifying a position angle range special requirement that is consistent with the output of the GTVT. The dispersion orientation of the grism can be verified by specifying one of the subarrays for the observation: dispersion is parallel to the long axis of any of the subarrays. Sources within about 10" of either end of the subarray are likely to result in spectral overlap, either with the spectrum of the science target or contaminating the area that would normally be used for the sky measurement. That said, for a given LW filter, only one sources near one end of the subarray can cause contamination, as illustrated in the NIRCam WFSS Field of View article. Careful tuning of the position angle of the observation may be necessary to avoid such contamination, particularly for targets in regions with a high density of stars of comparable brightness to the science target.

In the SW channel the weak lenses also disperse the light (spatially) over far more pixels than for in-focus images. See the time-series imaging section below for guidance on assessing overlap of the PSF of the science target with those of nearby sources.

Saturation limits 

Saturation for the LW grism begins to set in near a Vega magnitude of mK ~ 4.5, and is likely to affect wavelengths <3.0 μm first, depending on the spectrum of the target. Users should use the JWST ETC LW grism time-series calculation to check for saturation as a function of wavelength for their chosen integration times. Alternatively, the PandExo package referenced earlier can be used, but is not directly maintained by STScI. The ETC SW time-series calculation includes the ability to calculate SNR and saturation for SW imaging through the weak lenses. Users must use the same exposure parameters, including subarray size, for both the SW and LW  ETC calculations

Time-series imaging observations

Filter choices

Filter choices for NIRCam time-series mode include all of the SW filters in addition to the WLP8 weak lens element, which produces an image approximately 132 pixels (4") across. It may be challenging to perform photometry on such a large image, but in principal the relative photometric precision could be significantly enhanced by spreading the light out over so many pixels. Because the WLP8 element is in the SW pupil (not filter) wheel, it cannot be paired with the F162M or F164N. filters; most other SW filters are available. When the SW WLP8 element is chosen only the 4 narrow filters are available in the LW channel because images there will be in-focus, and any well-exposed WLP8 SW image would be highly saturated in the LW channel if a medium or wide LW filter were used.

Image overlap

As with the slitless LW grism case above, the spatially dispersed images from the WLP8 element create difficulties with overlap between signal from the science target and other nearby targets. Observers should carefully consider the potential impact of nearby sources that could overlap with their science target or contaminate sky background regions. Visualization of the region around the target (e.g., using APT/Aladin) is recommended in order to assess possible impacts of image overlap related to use of the weak lens.

Saturation limits

The JWST ETC includes the ability to calculate TSO saturation limits using the SW WLP8 element in the NIRCam SW time-series calculation, as well as for LW TSO observations using the LW time-series calculation. Users must use the same exposure parameters, including subarray size, for both the SW and LW calculations

Data volume

For NIRCam grism TSO mode, data is saved from 3 detecors (2 SW + one LW). This can generate substantial amounts of data for long observations, and may result in a data volume warning or error in APT. The data volume warning can be addressed during the planning phase of the observations, but observers should include a justification stating why the data volume can't be reduced without impacting science return. If APT generates a data volume error, the observer must address the issue directly as the observation would generate more data than can be stored on the solid state recorder.

Strategies that can be used, singly or combined, for reducing data volume for a given grism TSO observation are:

  1. Choose a readout pattern with a longer readout time, e.g., switch to SHALLOW2 if you encounter a warning for BRIGHT2.

  2. Select No. of Output Channels = 1. This option is only available in the NIRCam TSO templates, and has the effect of cutting the data rate (and therefor data volume for a fixed-duration observation) by a factor of 4.

  3. Switch from the grism TSO mode to the imaging TSO mode.

For the NIRCam imaging TSO mode data is saved from one SW and one LW detector, so data volume issues are somewhat less likely to crop up. If data volume is an issue in the imaging TSO template, it can be reduced by:

  1. Choosing a readout pattern with a longer readout time, e.g. switch to BRIGHT1 if you encounter a warning for RAPID.

  2. If the warning is for an observation using the FULL subarray, selecting one of the smaller subarrays (this effectively switches from No. of Output Channels = 4 for FULL, to 1 for the subarray.)

For the brightest targets options 1 and 2 above may not be practical because increasing the group time, or the frame readout time, worsens the saturation limits.


Observation duration

At the beginning of TSO observations the detector response will stabilize after a "settling time." Measurements of the settling time on NIRCam commissioning TSO data indicate that the settling time is in the range 5–15 min for the SW channel and almost instantaneous for the LW channel. These empirical settling times are half or shorter compared to the pre-flight expectation of 0.5 hr for NIRCam's H2RG detectors. Observers are advised to continue assuming the more conservative pre-flight settling time of 30 minutes. Separate from this settling time, it is necessary to observe an exoplanet transit/eclipse event for the duration of the event, plus the event duration both before and after, for a total of 3 times the event duration. This provides enough out-of-transit/eclipse baseline data, such that the in-transit/eclipse signal to noise isn't significantly degraded by the uncertainty of the determined out-of-transit/eclipse baseline. In addition, the longer baseline data provides the ability to correlate any flux variations caused by instabilities in the instrument response (if any), and to characterize shorter-term variations, if they are present.

Based on these considerations, and allowing for some conservatism regarding the settling time of the detectors, it is recommended that high-precision TSO observations be specified with a duration 3 times the duration of the event (transit, eclipse) plus 1 hr. Once on-orbit observations have been obtained early in the JWST mission this guideline will be re-evaulated.

JWST TSO observations automatically get a time-series observation special requirement in APT that allows the observation to exceed 10,000 s in duration. For other types of observations visits are not allowed to exceed that duration because the observatory must autonomously re-point the high gain antenna (HGA) on approximately that cadence. As a result, TSO observations exceeding 10,000 s duration should expect that the HGA will be re-pointed during their observation, with an impact on pointing stability lasting approximately 60 s. Such pointing excursions are not expected to cause loss of fine guidance, but will probably result in slightly degraded precision in the science data during the time of the disturbance. An analysis of commissioning data confirms the aforementioned expectation. The timing of HGA re-points is not known ahead of time, but will be reported in the engineering telemetry associated with the science data.

Constraining the observation start time

TSO observers will typically use a phase timing special requirement (SR) to constrain the start time of their observation. The parameters for the Phase SR are an ephemeris reference time, period, and a range for the starting phase. The phase is defined as spanning the range 0–1 of the specified period, with zero phase corresponding to the ephemeris reference time. Most observations are scheduled at the start of the user provided phase range in APT.

As an example consider a system with a transit every 100 hours, an event duration of 2 hours, and a user-specified reference time (phase = 0) corresponding to the center of a transit event. The starting phase of the events is then 0.99, and the duration of the event in phase units is 0.02. From the above guidance, the starting phase of the observation should be 1.0 − (1.5 × 0.02 + 1hr/100hr) = 0.96. Similarly the end of the observation should occur at a phase of 1.0 + (1.5 × 0.02) = 1.03, for a total phase duration of 1.03 − 0.96 = 0.07, or 7 hours given the 100 hour period between transits. Note that values for the starting phase can only be specified in the range 0–1, so it isn't possible to specify a phase constraint starting at -0.04 as might be convenient for this example.

Because APT imposes a one hour direct scheduling overheads for constraints that restrict observation start times to less than one hour, TSO observers may wish to specify their phase constraints with wider windows that guarantee starting their observations no later than discussed above, but with the possibility of getting a somewhat longer baseline measurement prior to the event they wish to study.

The ExoCTK Phase Constraint Calculator is recommended for estimating the phase range (specified in APT under Special Requirements) for exoplanet transits and eclipses.

Notable updates
    Added clarification details regarding the time-critical aspect of most TSOs and phase range 
    Updated based on commissioning results
Originally published