NIRCam Time Series Observations Pipeline Caveats

Unique features of the JWST Science Calibration Pipeline for time-series observations (TSOs) with the NIRCam instrument, and caveats for users, are covered in this article. Users should also refer to JWST Time Series Observations Pipeline Caveats for characteristics and caveats common to all instrument. This information reflects the status for the JWST pipeline version 1.4.6. 

On this page

Summary of specific NIRCam time-series issues

The information in this table about NIRCam time-series observations calibration pipeline issues is excerpted from Known Issues with JWST Data Products.  

SymptomsCauseWorkaroundMitigation Plan
NC-TS02: For grism time-series observations, extract_2d always produces a cutout that is 64 pixels in height (cross-dispersion direction), regardless of whether the original image is full frame or subarray. This may not include enough background pixels for background subtraction.

The pipeline default cutout height has been set to be equal to the height of the smallest available NIRCam grism subarray (2048 × 64 pixels)

Rerun the 2-D spectral extraction step (extract_2d) in calwebb_spec2 to produce cutouts with larger height and more background pixels using the tsgrism_extract_height parameter.

Updated issue

Default parameters are continually being examined and optimized. Investigation of the optimal extraction height is underway. 

NC-TS03: An excessive number of pixels are flagged as outliers in the subarray data, leading to a lower signal-to-noise ratio of the "rate" products (slope images) per integration.Some subarrays do not have reference pixels on all sides. Without a reference pixel correction, the data becomes noisier and the jump step in calwebb_detector1 sometimes identifies too many pixels as outliers.Rerun the jump detection step in calwebb_detector1 with an increased rejection_threshold (default is 4.0).

Updated issue

The jump step algorithm and default parameters are continually being examined and optimized; improvements are expected in future builds (winter 2023 and beyond).

NC-TS01: Wavelengths in extracted spectra ("x2d," "x1d") have incorrect dispersion relative to stellar model spectra.Operations Pipeline is using pre-launch wavelength reference data. Science Calibration Pipeline had a bug.

This workaround notebook shows how to run the calwebb_image2 and calwebb_tso3 pipelines on grism time-series data. This notebook assumes that the updated reference files (specwcs) are present in CRDS. These reference files will contain the wavelength solution derived from commissioning data.

Updated Operations Pipeline

New wavelength reference data was delivered and reprocessing with the latest Science Calibration Pipeline completed in September 2023. 

About NIRCam time-series observation pipeline caveats

Some aspects of the JWST Science Calibration Pipeline for NIRCam are highlighted below, in particular those where the treatment of TSO exposures differs from non-TSO exposures. It is also important to highlight that early in the mission, our understanding of the observatory performance is evolving quite rapidly and changes to calibration procedures are expected. 

The information presented here covers both of the NIRCam's modes available for TSOs: imaging time series and grism time-series spectroscopy.


Stage 1 processing

The pre-amplifier reset noise and 1/f noise can be the dominant noise source for some NIRCam modes, so it is important to apply some corrections to reduce these noise contributions.

In particular, the SUBGRISM128 and SUBGRISM64 subarrays (which allow bright sources without saturation) do not have bottom reference pixels on the short wavelength detectors to subtract pre-amplifier reset noise. It is beneficial to use background pixels to subtract the average counts in a given 512 pixel or 2048 pixel wide amplifier region (for Noutputs = 4 and Noutputs = 1, respectively) to remove amplifier offsets. After removing pre-amplifier reset noise, the 1/f noise is still significant. Row-by-row subtraction (which is the fast read direction) for each 512 pixel or 2048 pixel wide amplifier region (for Noutputs = 4 and Noutputs = 1, respectively) can improve the precision (Schlawin et al. 2020). Note that if one is using Noutputs = 4 (the recommended mode), the PSF for the F322W2 grism position spans 2 amplifiers so the row-by-row subtraction must be performed on the different amplifiers.

Failing to correct for pre-amplifier reset noise and 1/f noise can result in more than just excess noise. The jump step of the pipeline can erroneously flag this noise as jumps from cosmic rays. The excess flags can generate additional problems by discarding a majority of scientifically useful pixels. This excess flagging can be mitigated by skipping the jump detection step of the pipeline but this has the disadvantage of not flagging real cosmic rays. Therefore, the best solution is a row-by-row subtraction per amplifier at the reference pixel correction step of the pipeline and with normal jump step flagging to identify real cosmic rays.

Stage 3 processing

JWST target acquisition is designed to accurately center the source at the subpixel level with a small angle maneuver (SAM). This means that the source should land in a repeatable and predictable location. However, there may be offsets from a perfect centering so it is worth checking whether the XREF_SCI and YREF_SCI keywords in the header match the location of the source. Additionally, JWST pipeline version 1.4.6 does not adjust the aperture position as a function of time. If telescope motions caused by jitter and/or high gain antenna (HGA) moves occur, the position of the aperture used to extract photometric signal needs to be moved. Pointing measurements from a commissioning transit observation of HAT-P-14b demonstrate stability to 0.01 pixels (0.3 mas) in the X-direction and 0.009 px (0.3 mas) in the Y-direction over the 6hr-long visit. While variation from these values may be expected depending on the availability of guide stars, most observations with suitable guide stars would not require adjustments of the location of the extraction aperture. An HGA adjustment has been initiated during the same commissioning observation and produced a measurable with the FGS and NIRCam SW time-series centroids. However, the pointing change from the HGA move settled quickly in less than 0.5 minutes. Furthermore, the position was returned back to the original pointing to within 1 mas. The data around an HGA move can be discarded and in the case of WL photometry that is spread over many pixels, only produced a transient 500 ppm change in flux. Thus, HGA moves are not expected to cause significant issues to most time-series observations as long as the fine guide mode does not loose a guide star from its subarray (Schlawin et al. 2021, 2022).

In-flight measurements show that the jitter is smaller than predicted at 1 mas and that HGA moves settle quickly.

The weak lens point spread function can span a significant size (2.2") so the target star can blend with nearby sources. To calculate the contamination overlap, use WebbPSF to simulate background stars and scale the transit depth accordingly.


Stage 1 processing

1/f noise has considerable impact on grism time series because there are no background pixels for a given row on two to three amplifiers depending on the filter and position. Thus, the noise can be highly correlated along the dispersion (i.e., wavelength) direction. Binning N wavelengths together, therefore, may not decrease the noise by the square root of N as would be expected if each pixel is independent. While 1/f noise cannot be eliminated, it can be reduced by using small aperture sizes and reference pixel correction and row-by-row correction on amplifiers that have background pixels in the horizontal/fast-read direction. This should be performed at the reference pixel correction step of the pipeline after removing the pre-amplifier resets. The pre-amplifier resets can be estimated from either the average reference pixel or average background pixel in each 512 pixel or 2048 pixel wide amplifier region (for Noutputs = 4 and Noutputs = 1, respectively).

Stage 2 processing

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

The second stage of the pipeline truncates the array to an immediate region surrounding the source. This step can be skipped or adjusted so that more pixels are available for background subtraction. (Pipeline parameters for NIRCam grism time series are described in this Read The Docs page.) As of this writing, the value is 64 pixels tall so it will not affect the SUBGRISM64 subarray.

For the SUBGRISM128 (128 pixels tall) and SUBGRISM256 (256 pixels tall) subarrays or full frame, the extract2D step will use a 2048 × 64 cutout region. It can be advantageous to include 128 pixels for the SUBGRISM128 and 256 pixels for the SUBGRISM256 and full frame images for background subtraction, identifying possible neighboring sources and evaluating the 1/f noise in background regions. This can be changed with the tsgrism_extract_height parameter. Spectral extraction is performed in pixel coordinates without tracing the spectrum or taking partial pixels.

For each column the target flux is summed after a median background subtraction using pre-defined aperture extraction and background regions in the "_extract1d.json" file. Additionally, the photometric calibration step will convert from DN/s to MJy/sr. If there is significant jitter, this step can introduce additional noise especially near sharp gradients such as the shortest and longest wavelengths of the grism spectrum.


Schlawin, E., et al. 2020, AJ, 160, 231
JWST Noise Floor. I. Random Error Sources in JWST NIRCam Time Series

Schlawin, E., et al. 2021, AJ, 161, 115
JWST Noise Floor. II. Systematic Error Sources in JWST NIRCam Time Series

Schlawin, E., et al. 2023, PASP, 135, 8001
JWST NIRCam Defocused Imaging: Photometric Stability Performance and How It Can Sense Mirror Tilts

Latest updates
Originally published