JP-3433: pixel_replace doc updates (#7990)

Author: hbushouse

CHANGES.rst

@@ -1,7 +1,13 @@
 1.12.3 (unreleased)
 ===================
 
--
+documentation
+-------------
+
+- Updated the ``calwebb_spec2`` pipeline docs to indicate that the ``pixel_replace`` step is
+  applied to NIRSpec IFU data, and made minor wording updates to the ``pixel_replace`` step
+  docs.  [#7990]
+
 
 1.12.2 (2023-10-02)
 ===================
@@ -166,7 +172,7 @@ datamodels
 - updated ``stdatamodels`` pin to ``>=1.8.0`` [#7854]
 
 documentation
-------------
+-------------
 
 - Fixed a reference to the ``ramp_fitting` module in the user documentation. [#7898]
 

docs/jwst/pipeline/calwebb_spec2.rst

@@ -77,7 +77,7 @@ TSO exposures. The instrument mode abbreviations used in the table are as follow
 +----------------------------------------------------------+-----+-----+-----+-----+-----+-----+-----------------+------+--------+-----+
 | :ref:`residual_fringe <residual_fringe_step>` \ :sup:`2` |     |     |     |     |     | |c| |                 |      |        |     |
 +----------------------------------------------------------+-----+-----+-----+-----+-----+-----+-----------------+------+--------+-----+
-| :ref:`pixel_replace <pixel_replace_step>` \ :sup:`2`     | |c| | |c| |     | |c| | |c| |     |                 | |c|  |  |c|   |     |
+| :ref:`pixel_replace <pixel_replace_step>` \ :sup:`2`     | |c| | |c| | |c| | |c| | |c| |     |                 | |c|  |  |c|   |     |
 +----------------------------------------------------------+-----+-----+-----+-----+-----+-----+-----------------+------+--------+-----+
 | :ref:`resample_spec <resample_step>`                     | |c| | |c| |     | |c| |     |     |                 |      |        |     |
 +----------------------------------------------------------+-----+-----+-----+-----+-----+-----+-----------------+------+--------+-----+
@@ -92,7 +92,8 @@ For NIRISS and NIRCam WFSS, as well as NIRCam TSO grism exposures, the order is
 flat_field, extract_2d, and srctype (no wavecorr).
 For all other modes the order is extract_2d, srctype, wavecorr, and flat_field.
 
-:sup:`2`\ By default this step is skipped in the ``calwebb_spec2`` pipeline.
+:sup:`2`\ By default this step is skipped in the ``calwebb_spec2`` pipeline, but
+is enabled for some modes via overrides provided in parameter reference files.
 
 :sup:`3`\ NIRISS SOSS can have multiple spectral orders contribute flux to one pixel; because
 photometric correction values depend on the spectral order assigned to a pixel, the order of

docs/jwst/pixel_replace/main.rst

@@ -4,15 +4,19 @@ Description
 :Classes: `jwst.pixel_replace.PixelReplaceStep`
 :Alias: pixel_replace
 
-During spectral extraction, pixels flagged as bad are ignored in the summation process.
+During 1-D spectral extraction (:ref:`extract_1d <extract_1d_step>` step),
+pixels flagged as bad are ignored in the summation process.
 If a bad pixel is part of the point-spread function (PSF) at a given wavelength, the
-absence of the signal in the flagged pixel will lead to a divot at that wavelength in
+absence of the signal in the flagged pixel will lead to a hollow space at that wavelength in
 the extracted spectrum.
 
 To avoid this defect in the 1-D spectrum, this step estimates the flux values of pixels
-flagged as ``DO_NOT_USE`` in 2-D extracted spectra, prior to rectification in the
-``resample_spec`` step. ``pixel_replace`` inserts these estimates into the data array,
-unsets the ``DO_NOT_USE`` flag and sets the ``FLUX_ESTIMATED`` flag for each pixel affected.
+flagged as ``DO_NOT_USE`` in 2-D extracted spectra using interpolation methods,
+prior to rectification in the :ref:`resample_spec <resample_step>` step.
+``pixel_replace`` inserts these estimates into the 2-D data array,
+unsets the ``DO_NOT_USE`` flag, and sets the ``FLUX_ESTIMATED`` flag for each affected pixel.
+
+This step is provided as a cosmetic feature and, for that reason, should be used with caution.
 
 Algorithms
 ==========
@@ -22,11 +26,11 @@ Adjacent Profile Approximation
 
 This is the default (and most extensively tested) algorithm for most spectroscopic modes.
 
-First, the input 2-d spectral cutout is scanned across the dispersion axis to determine
+First, the input 2-D spectral cutout is scanned across the dispersion axis to determine
 which cross-dispersion vectors (column or row, depending on dispersion direction) contain
 at least one flagged pixel. Next, for each affected vector, a median normalized profile is created.
 
-First, the adjacent arrays (the number of which is set by the step argument
+The adjacent arrays (the number of which is set by the step argument
 ``n_adjacent_cols``) are individually normalized. Next, each pixel in the profile is set to
 the median of the normalized values. This results in a median of normalized values filling the vector.
 
@@ -36,7 +40,7 @@ estimated from the scaled profile.
 Minimum Gradient Estimator
 --------------------------
 
-In the case of the MIRI MRS, NaN-valued pixels are partially compensated during the cube building process
+In the case of the MIRI MRS, NaN-valued pixels are partially compensated during the IFU cube building process
 using the overlap between detector pixels and output cube voxels.  The effects of NaN values are thus not
 as severe as for slit spectra, but can manifest as small dips in the extracted spectrum when a NaN value
 lands atop the peak of a spectral trace and cube building interpolates from lower-flux adjacent values.