Known issues specific to NIRCam time-series (imaging and grism) data processing in the JWST Science Calibration Pipeline are described in this article. This is not intended as a how-to guide or as full documentation of individual pipeline steps, but rather to give a scientist-level overview of issues that users should be aware of for their science. 

Specific artifacts are described in the Artifacts section below. Guidance on using the pipeline data products is provided in the Pipeline Notes section along with a summary of some common issues and workarounds in the summary section.

Please also refer to NIRCam Calibration Status for an overview of the current astrometric, photometric, and target acquisition accuracy of NIRCam data products.

Artifacts

Information on NIRCam instrument artifacts are found on the main NIRCam Known Issues page.

Pipeline notes

The topics below affect time-series observations and reflect common questions about how to improve the quality of the data from the pipeline. For issues that affect all observing modes, see NIRCam Known Issues.

Jump step

Several steps in the pipeline are dependent on actual on-orbit performance and noise properties of the instruments; among these, the jump step is one of the more important to be wary of. The goal of this processing step is to detect the anomalous jumps in flux between groups due to cosmic rays. A specific threshold is used to detect such jumps.

The performance of this step can have a dramatic effect on the derived SNR for reduced observations. One recommendation is to be mindful of the thresholds used to detect jumps, and test different values on your dataset to find the optimum value; bear in mind that different jump thresholds can result in different outcomes further downstream in the pipeline. Information on where jumps were flagged by this processing step can be found in the "DQ" (data quality) extension of the "rateints.fits" file. In Python, this can be achieved with the following code:

from jwst import datamodels
 
data = datamodels.open(‘file_rateints.fits’)
whereJump = data.dq & 2**2

More information and suggestions about common issues with cosmic ray flagging are provided in the general NIRCam Known Issues article. 

Photometry

Stage 1 processing

See also: NIRCam 1/f Noise Removal Methods

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 N_outputs = 4 and N_outputs = 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 N_outputs = 4 and N_outputs = 1, respectively) can improve the precision (Schlawin et al. 2020). Note that if one is using N_outputs = 4 (the recommended mode), the PSF for the F322W2 grism position spans two 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.

Pointing jitter or drift

See also: JWST Pointing Performance, JWST Communications Subsystem, JWST Attitude Control Subsystem

The JWST calibration pipeline currently assumes that the pointing of the telescope is perfect and constant over the course of an observation. Only the target acquisition procedure includes a source-finding and centroiding step; once the target has been placed into the science aperture, the pipeline assumes that its location is fixed. In reality, the initial target placement may be imperfect, and over many hours the pointing may be subject to drifts, jitter, or jumps. The high gain antenna repointing, for example, has been observed during commissioning to have some impact on the telescope pointing when it is moved. This might have some consequences for time-series observations. 

For imaging, the automated photometry step in calwebb_tso3 assumes a fixed location of the target in the field of view. If this location changes significantly over the course of the time-series observation, the photometry measurement will be performed off-center and return inaccurate results. 

For spectroscopy, the wavelength calibration and photometric calibration factors are applied to the data assuming perfect and constant target placement in the field. Any drifting behavior or jitter, therefore, might introduce systematic noise in the final time series. There is currently no mitigation for this in the calibration pipeline; any pointing changes must therefore be measured and corrected manually in the time series. A suggested workaround is to skip the photometric calibration step by modifying the execution parameters for the calwebb_spec2 stage since for many science needs it is the relative variations that are of most interest. Further pipeline work in this area is planned. 

In practice, a good recommendation is to monitor the JWST guide star data which can be retrieved via MAST, and use it to study any significant pointing aberrations that might be impacting a given TSO. Details on how to perform this data retrieval can be found in JWST Time-Series Observations Noise Sources.

Spectroscopy

Stage 1 processing

See also: NIRCam 1/f Noise Removal Methods

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 N_outputs = 4 and N_outputs = 1, respectively).

Stage 2 processing

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.

Summary of common issues and workarounds

The sections above provide detail on each of the known issues affecting NIRCam TSO data; in this table we summarize some of the most likely issues for users to encounter along with any workarounds if available.  Note that greyed-out issues have been retired, and are fixed as of the indicated pipeline build.

References

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