NIRSpec IFU Known Issues
Known issues specific to NIRSpec IFU 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.
On this page
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 NIRSpec IFU Calibration Status for an overview of the current astrometric, photometric, and wavelength calibration accuracy of NIRSpec IFU data products.
Artifacts
Cube building resampling artifacts
The NIRSpec IFU PSF is spatially under-sampled by the NIRSpec detector pixels, which can lead to pixel aliasing effects when resampling observed data during cube building. When in the vicinity of unresolved point sources this results in "ringing" or oscillations in the spectra of individual spaxels or in the spectra extracted from regions that are small relative to the FWHM of the NIRSpec PSF (Law et al. 2023). An example of this is shown in Figure 1 (Law & Clarke 2026). As of JWST pipeline v2.0.0 (and later versions) there is an optional pipeline step, the adaptive_trace_model step, that can be used to greatly reduce these resampling artifacts in IFU cube data as can be seen in the right-hand of Figure 1. The NIRSpec IFU pipeline notebook shows how this step can be run as part of pipeline processing.
More information about these undersampling effects and how to correct them can be found on the Resampling Artifacts page. The adaptive_trace_model step is described in more detail in the JWST pipeline ReadTheDocs and in Law & Clarke (2026).
Figure 1. An example of cube building resampling artifacts and correcting them with adaptive trace modeling.
Click on the figure for a larger view
Normalized JWST/NIRSpec G395H/F290LP spectra of standard star J1743045 (spectral type A5 IIIm) measured from an IFU cube (modified from Figure 6 in Law & Clarke 2026). The solid black lines show the aperture-integrated spectrum of the source in the cube, while the colored lines show spectra from individual spaxels in increasing brightness from purple (top) to blue (second to the bottom). (Left) spectra extracted from a standard IFU cube, demonstrating resampling artifacts that appear as oscillations in the spectra that change from spaxel-to-spaxel. (Right) spectra extracted from an IFU cube that has been built using the adaptive_trace_model step (ATM) to oversample 2-D detector data prior to cube building. Use of this step can greatly reduce the oscillating resampling artifacts.
Pipeline notes
The topics below affect imaging 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 NIRSpec Known Issues.
Cube building
The cube_build step of the pipeline combines the individual 2-D IFU slice images and creates a 3-D spectral cube. The IFU cubes are, by default, constructed with north pointing up and east to the left. Cube building can be done using either the default 3-D drizzle algorithm, or alternatively, the Shepard's method of weighting. The current pipeline default setting is the 3-D drizzle algorithm.
- To use 3-D drizzle, set weighting = drizzle
- To use Shepard's method with exponential or linear weighting, set weighting = emsm or msm
It is sometimes useful to build a cube in the detector frame (for example, when analyzing the point spread function), rather than in sky coordinates. To build the cube in detector coordinates:
Set coord_system = ifualign
The default cube building uses a linear wavelength sampling. The NIRSpec PRISM in particular has a non-linear wavelength solution, however, so the linear sampling oversample some wavelengths and can lead to strong resampling artifacts in the PRISM cubes. As of jwst pipeline version v2.0.0 (and onwards) NIRSpec IFU cubes can be built with the option linear_wave = False to use a more natural, non-linear wavelength sampling. The examples below show how to access the wavelength arrays of non-linearly sampled cubes:
cube_file = 'my_nonlinear_cube_s3d.fits' # when importing the cube using astropy.io fits: from astropy.io import fits cube = fits.open(cube_file) wavelength_array = cube['WCS-TABLE'].data['wavelength'][0] # or when opening the cube using jwst datamodels: from jwst import datamodels cube = datamodels.open(cube_file) wavelength_array = cube.wavetable['wavelength'][0]
Correlated 1/f read noise
The effects of 1/f noise for NIRSpec MOS are shown in the IFU 1/f noise cleaning notebook, which also demonstrates the use of the NSClean algorithm to remove most of this effect. NSClean is implemented in the pipeline versions from v1.13.4 through v1.20.2 as a non-default option. As of jwst pipeline v2.0.0 (and later versions) there are multiple 1/f cleaning options provided by the optional clean_flicker_noise step available in both calwebb_detector1 and calwebb_spec2. The IFU pipeline notebook shows how this step can be run as part of pipeline processing. Further information on 1/f noise can be found on the main NIRSpec Known Issues and 1/f Noise pages.
Background subtraction
ReadTheDocs documentation: Background Subtraction
Background subtraction is automatically applied by the calwebb_spec2 pipeline for nodded observations or observations with dedicated background or leakage observations. It is not automatically applied for observations that have off-scene background observations that were not linked to the target in APT. Custom background subtraction may be required depending on science use case. In particular, a 1-D master background spectrum may be specified when running the calwebb_spec3 pipeline. A notebook is currently under construction to demonstrate this workaround.
Leakage of flux through the MSA may be significant in the case of bright extended targets or point sources in stuck-open shutters. If dedicated leakage observations were obtained at every dither or nod, the pipeline will use them to subtract the leakage signal. If leakage observations were only acquired at one dither or nod, the pipeline will use that leakage observation for all dither/nod positions. If the leakage changes significantly with dither/nod position and only a single leakage observation was taken, the pipeline may not process the data correctly. In this case, custom background subtraction may be necessary.
Outliers in background and leakcal subtracted data
NIRSpec/IFU data can feature more outliers if using the default pipeline processing when nods, dedicated background exposures, or leakage exposures are subtracted. These outliers are often due to new or changing hot pixels that are not flagged by the bad pixel mask. The outlier_detection step in calwebb_spec3 is designed to identify outliers that are consistently bad in multiple exposures, such as hot pixels. However, if nod/background/leakcal subtraction is performed, the subtraction of a hot pixel often leaves large poisson noise that differs between exposures. This large poisson noise, itself, can cause a pixel to appear as an outlier, however, because it changes significantly between exposures, these outliers can be missed by the outlier_detection step and show up in the final level 3 IFU cubes.
The JWST pipeline includes an optional step, badpix_selfcal, in calwebb_spec2, which can be used to flag these hot pixels (and other bad pixels) prior to background and leakcal subtraction, reducing the number of outliers that show up in the final IFU cubes. To run the badpix_selfcal step, the calwebb_spec2 step must be run on an association listing all of the relevant exposures (e.g., the science, background and/or leakcal exposures) as "selfcal" members in the association and the badpix_selfcal parameter skip = False must be set. Note that when adding selfcal exposures to an association some exposures would show up twice in the association, once as a "science," "background," or "imprint" member and once as a "selfcal" member. More information on the badpix_selfcal step can be found on the Bad Pixel Self-Calibration ReadTheDocs page, and examples of setting up the requisite association files programmatically can be found in the NIRSpec IFU pipeline notebook.
Spectral and spatial distortions
For more information see Beck (2025).
Distortions have been seen in the spatial location of the PSF centroid as a function of wavelength and the spectral centroid of emission lines:
(i) Point sources in the NIRSpec IFU have been seen to wander in x/y positions by up to 0.5 pixels (as shown in Figure 2). This appears to be due to a chromatic effect of the NIRSpec fore-optics that is not accounted for in the NIRSpec instrument model and is therefore common to all NIRSpec filters/dispersers (T. Beck JWST Technical Report, in prep.). Investigations are underway to improve the NIRSpec instrument model and correct for these effects.
Figure 2. Spatial distortion of PSF.
The x and y position of the PSF from 2-D Gaussian fits as a function of wavelength for the NIRSpec IFU observation of the (point source) planetary nebula IRAS 05248-7007 using the PRISM+CLEAR disperser/filter combination. Each panel shows a different dither observation, combined here for illustration purposes. The color bar to the left shows the wavelengths of the measured x and y positions from 1 to 5 µm. In this view, the cross-slice direction goes from bottom to top, while the right-left direction is the axis along the IFU slices. Hence, the larger shift in the x pixel direction shows that the PSF centroid is predominantly varying within a slice, and the y shift in centroid position across slices is small and less than one slice width. Credit: Beck (2025).
(ii) Gaussian line-fit kinematic analysis of compact emission lines are showing a blue/red shifted character across slices at the 1–1.5 pixel level, as demonstrated in Figure 3. The shift is seen across the NIRSpec IFU slices, with similar shift in pixel magnitude regardless of disperser used. This effect appears to be due to uneven slice illumination effects (T. Beck JWST Technical Report, in prep.). Gradients in the illumination along the dispersion direction of a given IFU slice mean that light will be weighted towards one edge of the slice. When imaged on the detector spatial gradients along the dispersion direction of the slice are degenerate with wavelength shifts of the light and can, therefore, result in apparent kinematic shifts across sources with steep light profiles (such as the PSF of unresolved sources). The kinematic analyses of all spatially resolved emission line sources with compact morphologies can be affected at this level.
Figure 3. Spectral shift in emission lines.
Spectral shifts seen in the emission line data from the PRISM data analysis using the Brɑ emission line at 4.05 µm and the pipeline default cube building weighting (drizzle). The panel shows 4 different dither observations combined into a single FoV for illustration purposes. Each observation shows a kinematic pixel centroid shift of nearly 1.5 pixels across the PSF position from the upper left (blue shifted centroids) to the lower right (red shifted centroids). It should be noted that the maximum expected velocity and kinematic shift from this PN should have been well below NIRSpec instrument sensitivities. Credit: Beck (2025).
These issues with the NIRSpec spatial PSF wander and spectral shifts point toward a non-trivial problem in the calibration of the NIRSpec IFU instrument model, particularly the portion of the model that anchors the internal instrument model to the RA, Dec, wavelength mapping on the sky. While these issues occur independent of the filter/disperser that is used, it has been established that these issues can have a different character depending on disperser mode used, and are not related to the cube building algorithm in the pipeline. Both issues are currently under investigation via spatial and spectral IFU distortion calibration programs (PID 6641 and 6640, respectively). STScI is investigating these issues and more information will be available in an upcoming JWST Technical Report, T. Beck (in prep). Mitigation plans will be released to the community once potential solutions have been identified.
Summary of common issues and workarounds
The sections above provide detail on each of the known issues affecting NIRSpec IFU data; the table below summarizes some of the most likely issues users may encounter along with any workarounds, if available. Note that greyed-out issues have been retired, and are fixed as of the indicated pipeline build.
| Symptoms | Cause | Workaround | Fix build | Mitigation Plan |
|---|---|---|---|---|
| NS-IFU05: Spectra extracted from single spaxels on/near point sources show a sinusoidal modulation. | NIRSpec is undersampled, and distortion causes spectral traces (particularly for the gratings) to be curved on the detector. Resampling the raw data to a rectified data cube introduces artifacts (e.g., oscillations) if extracting spectra from individual spaxels or on scales smaller than the PSF. See detailed discussion by Law et al. 2023. | As of jwst 2.0.0 (and later versions), the JWST pipeline includes an optional step in calwebb_spec2 and calwebb_spec3, called adaptive_trace_model, that oversamples 2D detector data prior to cube building, which can greatly reduce resampling artifacts in IFU cubes. The JWST pipeline notebook for IFU provides examples of how to turn on the adaptive_trace_model step in calwebb_spec3 when reprocessing data. More information about these undersampling effects and how to correct them can be found on the Resampling Artifacts page, and the adaptive_trace_model step is described in more detail in Law & Clarke (2026). | N/A | Updated issue As of jwst 2.0.0 (and later versions), the adaptive_trace_model step can reduce resampling artifacts in IFU cubes. Investigations are needed to determine whether this step could be turned on by default in the pipeline. |
| NS-IFU06: The centroid of point sources appears to drift by up to 0.5 pixels as a function of wavelength. | Issue due to a chromatic effect in the NIRSpec fore-optics that is not accounted for in the optical instrument model. The drift can be up to ~30 mas over the wavelength range of a given disperser. More information will be provided in an upcoming JWST Technical Report (T. Beck, in prep.). | None at present. | N/A | Updated issue Updates are required to the NIRSpec instrument model. A potential solution has been identified and is being investigated for potential inclusion in JWST Pipeline Build 13.0 expected to be released in late Summer 2026. |
NS-IFU07: The spectral centroid of emission lines shows unexpected structure across IFU slices. | Issue appears to be due to uneven slice illumination effects where light gradients across the dispersion direction of a given slice are degenerate with wavelength shifts when imaged onto a 2D detector. More information will be provided in an upcoming JWST Technical Report (T. Beck, in prep.). | None at present. | N/A | Updated issue The root cause of this issue is has been identified. Investigations into potential mitigation plans are ongoing. |
References
Beck, T. 2025, JWST Technical Memorandum JWST-STScI-009029
Evidence for Problems in the JWST NIRSpec IFU Calibration Distortion Model
Law, D., et al. 2023 AJ 166, 45
A 3D Drizzle Algorithm for JWST and Practical Application to the MIRI Medium Resolution Spectrometer
Law, D. R. and Clarke, M. 2026, arXiv 2603.26916 (Adaptive Trace Model)
Mitigating Resampling Artifacts for the JWST IFU Spectrometers with Adaptive Trace Modeling