The calwebb_spec2 module is stage 2 of the JWST Science Calibration Pipeline for all spectroscopic observations. The input to this stage is the uncalibrated slope images (calwebb_detector1 output) and the output is individual calibrated slope images. An association (ASN) file is required to run this step on multiple slope images, or if an associated source catalog is specified for spectral extraction as in the case of WFSS modes. The steps are listed in Figure 1 with the flow from the top to the bottom.

Unless otherwise stated, the algorithms described are the baseline version.

A brief description of each of the steps within calwebb_spec2 can be found below, along with links to further details (e.g., the relevant reference files) that can be found on the corresponding ReadTheDocs pages. Note, however, that the reference files themselves are all provided via CRDS. For instrument mode-specific notes on these pipeline steps, see the corresponding known issues with JWST data articles.

---

Steps for both NIR and MIR data

WCS information

ReadTheDocs documentation: Assign WCS 
Package name: assign_wcs

The information to transfer pixel coordinates to astronomical coordinates (e.g., RA, Dec, and wavelength) is added to data with this step. This combines instrument distortion model information from calibration reference files (augmented by an instrument model for NIRSpec) with attitude information about where in the sky JWST was pointing to create a full chain of transforms from detector pixels to on-sky coordinates. This attitude information is drawn from a set of 5 header keywords describing the sky position (RA_REF, DEC_REF) at a given location in the JWST telescope frame (V2_REF, V3_REF) and the relative angle between those spherical coordinate systems (ROLL_REF). Additional corrections are made for effects such as velocity aberration and spacecraft motion, such that the final wavelength solution is given in vacuum relative to the Solar System barycenter.

The final transformation chain is encoded in the ASDF format and attached as an extension to the data that can be queried using the JWST data models. The WCS information and distortion model are provided by instrument and detector specific calibration reference files. The image data itself is not modified by this step.

Background subtraction

ReadTheDocs documentation: Background Image Subtraction 
Package name: See the link above for details

An observed or modeled background image is subtracted from the target exposure. 

If an APT-specified background target was observed, a combined background image constructed from all exposures of that target is subtracted from the science target exposure.

For NIRISS WFSS, NIRISS SOSS, and NIRCam WFSS, a master version of the dispersed background is used, scaled to match the background in the science target exposure.

For NIRSpec MSA, NIRSpec IFU, NIRSpec fixed slit, and MIRI LRS, if observations were taken at 2 or more nod positions, the associated nod position or sum of nod positions is subtracted.

For MIRI MRS this pixel-based background subtraction step is not run by default; MRS instead uses the master background subtraction step in the stage 3 pipeline.

Flat field correction

ReadTheDocs documentation: Flat field correction 
Package name: flat_field

The flat field corrects for the pixel-to-pixel variations and large scale variations in the instrument+telescope responsivity. The flat field image is taken from instrument and detector specific calibration reference files. For NIRSpec, the flat field is created on-the-fly from reference files and the instrument model and includes spectrophotometric calibration as part of the F-flat.

Point vs extended decision

ReadTheDocs documentation: Source Type 
Package name: srctype

Some of the calibration pipeline steps rely on knowing if the target is a point or extended source (e.g., spectral extraction). The determination of a source as point or extended can be informed by setting the extended tag in APT (see APT Targets), from simultaneous imaging (NIRISS and NIRCam WFSS), from the NIRSpec MSA tool output, or if no other information is available, by using defaults by instrument mode. The default is to assume a point source except for NIRSpec MSA backgrounds and MIRI IFU observations. This decision is attached to the data using the SRCTYPE header keyword and used by later steps in the JWST Science Calibration Pipeline. When manually rerunning the JWST Science Calibration Pipeline, this step can be set by the user.

Path loss correction

ReadTheDocs documentation: Path loss Correction 
Package name: pathloss

The loss of signal in the path is corrected here. The causes of signal loss include the finite slit width (NIRSpec, MIRI), the diffracted slit image being larger than the gratings (NIRSpec), the MSA bar shadow (NIRSpec MSA), and cases where the PSF wings may extend beyond the subarray size in the cross-dispersion direction (NIRISS SOSS). The correction values are provided by instrument- and mode-specific calibration reference files.

Flux calibration (photom)

ReadTheDocs documentation: Photometric Calibration 
Package name: photom

For most spectroscopic modes, the multiplicative conversion factor between counts/s and MJy/sr as a function of wavelength is attached to the data as FITS header keywords. A second conversion factor between counts/s and micro-Jy/sq arcsec as a function of wavelength is also attached. The pixel area reference file is attached to the data allowing conversion between surface brightness and flux density for each pixel.

For MIRI MRS, the pixel array values are instead multiplied by a reference array derived from observations of spectrophotometric standards to convert the detector image to units of MJy/sr.

For NIRSpec data, the spectrophotometric conversion factor is instead applied as part of the F-flat correction in the flat field step. The photom step will instead be used to apply a residual correction for systematic differences among standard stars, once multiple standards have been observed and analyzed.

Rectified 2-D/3-D product

ReadTheDocs documentation: Resampling, Cube Building
Package names: resample_spec, cube_build

As a product for the Archive, rectified 2-D (all modes except IFUs) or 3-D (IFUs) data products are created from individual exposures using the attached WCS information. These rectified 2-D/3-D products are not used in the calibration pipeline itself (other than to create 1-D extracted spectra from IFU data for later use in the calwebb_spec3 master_background step) and are created as they are useful for visual inspection of the data.  Note, however, that such intermediate single-exposure products can have undersampling artifacts and are not generally recommended for science.

Spectral extraction

ReadTheDocs documentation: Extract 2D Spectra and Extract 1D Spectra 
Package name: extract_2d, extract_1d

Just as the pipeline builds rectified 2-D/3-D products from individual exposures for visual inspection, it likewise extracts 1-D spectra for these individual exposures as well. As for the 2-D/3-D data products, these intermediate products are not generally intended for scientific use.

This spectrum is extracted by summing the signal in an aperture centered on the sky coordinates (RA & Dec) of the targets. For IFU data, the extraction is performed on the rectified 3-D data cubes.  Note that background data extracted in this way for IFU observations is then used later in the calwebb_spec3 master_background step. For modes where the extractions are done from individual unrectified images, the WCS information is used to map the projected aperture from the sky to detector coordinates.

---

NIR-specific steps

Imprint subtraction

ReadTheDocs documentation: Imprint Subtraction 
Package name: imprint

The MSA shutters are not completely dark allowing a small amount of light to leak through causing an imprint. When there is a dedicated imprint exposure taken (all MSA shutters closed and IFU closed), this will be subtracted from the target exposure.

MSA failed open flagging

ReadTheDocs documentation: MSA Flag Open Correction 
Package name: msa_flagging

The MSA failed open shutters will result in an elevated level of light to fall on the detectors. This step flags the pixels that are affected by these failed open shutters. And it uses the list of failed open shutters and the NIRSpec instrument model to flag the affected pixels.

Subwindow extraction

ReadTheDocs documentation: Extract 2D 
Package name: extract_2d

The region of interest around each source is cut out from the larger detector image for multi-object spectroscopic modes NIRISS/NIRCam WFSS, NIRISS SOSS, and NIRSpec MSA/fixed slit data. The location of the sources for the WFSS observations is provided using the direct imaging observations taken as part of the observations. The NIRSpec MSA configuration file provides the location of the sources for this MOS mode. The other modes have fixed locations for sources. This subwindow extraction assumes that sources are isolated and not confused with other sources (such confused sources will need to be extracted with a post-pipeline tool). The main impact of this step is to provide single sources to the rest of the calibration pipeline providing a uniform treatment of all spectra from the observation modes listed.

MSA master background subtraction (NIRSpec MOS only)

ReadTheDocs documentation: Master Background Subtraction 
Package name: master_background_mos

Master background subtraction for NIRSpec MOS comes from designated background MSA slitlets contained with the same exposure as the science targets or are supplied by the user. Processing for MOS mode is done within the calwebb_spec2 pipeline when processing individual MOS exposures, resulting in background-subtracted and fully calibrated 2-D cutouts and extracted 1D spectra.

Wavelength assignments (NIRSpec only)

ReadTheDocs documentation: Wavelength Assignments 
Package name: wavecorr

This step updates the wavelength assignments for NIRSpec fixed slit (FS) and MOS point sources that are known to be off-center (in the dispersion direction) in their slit. For NIRSpec MOS observations, wavelength assignments are initially created assuming that the source is perfectly centered in a slitlet. Most sources, however, are not perfectly centered in every slitlet in a real observation, therefore this step carries out a computation aimed at providing a more accurate determination of the source position in the slitlet, which is then used for the subsequent steps in the pipeline.

MSA bar shadow correction

ReadTheDocs documentation: MSA Bar Shadow Correction 
Package name: barshadow

For NIRSpec MSA observations, there are losses in the case of extended sources arising from the imperfect profile of the shutter. The shadow bar correction is derived from the instrumental mode for the target shutter and adjacent shutters, and is applied to the 2-D cutouts.

WFSS contamination removal

ReadTheDocs documentation: WFSS Contamination Removal 
Package name: wfss_contam

This step is applied to WFSS observations (NIRISS and NIRCam) to correct effects due to contamination resulting from overlapping spectral traces from objects that are near the source of interest. This can happen, for example, in observations of crowded fields. In this step, source fluxes from a direct image of the field are used to simulate the WFSS spectra for each of the overlapping nearby objects. Each spectrum of the source of interest is then corrected by subtracting the simulated spectra of these nearby contaminating objects.

---

MIR-specific steps

Stray light subtraction

ReadTheDocs documentation: Stray Light Correction 
Package name: straylight

As discussed in MIRI Known Issues, the MIRI detectors exhibit scattering inside the detector substrate that produces a cruciform-shaped artifact around bright sources. In the MRS, the interleaving of the slices on the detector means that this cross artifact is non-local in sky coordinates and can produce banding in the rectified 3-D data cubes. The stray light step estimates the cross artifact signal via convolution of the data with a model cruciform kernel and subtracts it from the MIRI MRS data. Likewise, it subtracts any pedestal residual count rate due to variations in the dark current over time using regions of the detector that do not directly see light from the sky.

Fringing removal

ReadTheDocs documentation: Fringe Correction and Residual Fringe Correction
Package names: fringe, residual_fringe

As discussed in MRS Known Issues page, there are significant fringes in the MIRI IFU data. These fringes are removed to first order by dividing the exposures by a static fringe flat contained within the detector-specific calibration reference file. This fringe flat only performs well for uniform extended sources however, and leaves significant residual fringes remaining for point sources or sources with complex spatial structure.

There are two residual fringe removal steps that can correct for many of these residual fringe features using a periodogram-based analysis of the data. Two-dimensional residual fringe correction can be performed by the calwebb_spec2 pipeline; this step is not run by default but can be enabled by users in offline reprocessing (see the MRS Known Issues page). Note also that a 1-D residual fringe correction is available as an option during 1-D spectral extraction from the data cubes.

---

---