DOC: Complete API for pixel_replace

docs/jwst/pixel_replace/api_ref.rst

@@ -0,0 +1,15 @@
+===
+API
+===
+
+Public Step API
+===============
+
+.. automodapi:: jwst.pixel_replace.pixel_replace_step
+   :no-inheritance-diagram:
+
+Complete Developer API
+======================
+
+.. automodapi:: jwst.pixel_replace.pixel_replace
+   :no-inheritance-diagram:

docs/jwst/pixel_replace/arguments.rst

@@ -4,8 +4,8 @@ Step Arguments
 The ``pixel_replace`` step has the following step-specific arguments:
 
 ``--algorithm`` (str, default='fit_profile')
-  This sets the method used to estimate flux values for bad pixels. The default 'fit_profile' uses a profile
-  fit to adjacent column values.  The minimum gradient ('mingrad') method, developed for MIRI MRS data, may
+  This sets the method used to estimate flux values for bad pixels. The default ``'fit_profile'`` uses a profile
+  fit to adjacent column values.  The minimum gradient (``'mingrad'``) method, developed for MIRI MRS data, may
   also be used for all instruments and modes.
 
 ``--n_adjacent_cols`` (int, default=3)

docs/jwst/pixel_replace/index.rst

@@ -9,5 +9,4 @@ Pixel Replacement
 
    main.rst
    arguments.rst
-
-.. automodapi:: jwst.pixel_replace
+   api_ref.rst

docs/jwst/pixel_replace/main.rst

@@ -1,7 +1,7 @@
 Description
 ===========
 
-:Classes: `jwst.pixel_replace.PixelReplaceStep`
+:Classes: `jwst.pixel_replace.pixel_replace_step.PixelReplaceStep`
 :Alias: pixel_replace
 
 During 1-D spectral extraction (:ref:`extract_1d <extract_1d_step>` step),

jwst/pixel_replace/pixel_replace.py

@@ -10,7 +10,7 @@
 
 log = logging.getLogger(__name__)
 
-__all__ = ["PixelReplacement"]
+__all__ = ["PixelReplaceArrays", "PixelReplacement"]
 
 
 @dataclass
@@ -22,7 +22,8 @@ class PixelReplaceArrays:
     `~stdatamodels.jwst.datamodels.JwstDataModel`.
     This avoids the overhead of constructing intermediate DataModel objects,
     which was slowing runtime for TSO data with thousands of integrations,
-    and provides a consistent interface for mingrad and fit_profile.
+    and provides a consistent interface for :meth:`PixelReplacement.mingrad`
+    and :meth:`PixelReplacement.fit_profile`.
 
     Attributes
     ----------
@@ -59,6 +60,15 @@ class PixelReplacement:
     method for pixel replacement, and executing each step. This class
     should provide modularization to allow for multiple options and possible
     future reference files.
+
+    Parameters
+    ----------
+    input_model : `~stdatamodels.jwst.datamodels.JwstDataModel`
+        Datamodel with bad pixels to replace. Updated in-place.
+
+    **pars : dict, optional
+        Optional parameters to modify how pixel replacement
+        will execute.
     """
 
     # Shortcuts for DQ Flags
@@ -72,18 +82,6 @@ class PixelReplacement:
     LOG_SLICE = ["column", "row"]
 
     def __init__(self, input_model, **pars):
-        """
-        Initialize the class with input data model.
-
-        Parameters
-        ----------
-        input_model : `~stdatamodels.jwst.datamodels.JwstDataModel`
-            Datamodel with bad pixels to replace. Updated in place.
-
-        **pars : dict, optional
-            Optional parameters to modify how pixel replacement
-            will execute.
-        """
         self.input = input_model
         self.pars = {}
         self.pars.update(pars)
@@ -131,7 +129,8 @@ def replace(self):
         """
         Unpack model and apply pixel replacement algorithm.
 
-        Process the input DataModel, unpack any model that holds
+        Process the input `~stdatamodels.jwst.datamodels.JwstDataModel`,
+        unpack any model that holds
         more than one 2D spectrum, then apply selected algorithm
         to each 2D spectrum in input.
         """
@@ -315,14 +314,14 @@ def fit_profile(self, arrays):
 
         Parameters
         ----------
-        arrays : PixelReplaceArrays
+        arrays : `PixelReplaceArrays`
             Pixel arrays and dispersion direction for the 2D spectrum to process.
             Arrays are modified in place.
 
         Returns
         -------
-        arrays : PixelReplaceArrays
-            The same PixelReplaceArrays with bad pixels now flagged with FLUX_ESTIMATED
+        arrays : `PixelReplaceArrays`
+            The input with bad pixels now flagged with FLUX_ESTIMATED
             and holding a flux value estimated from the spatial profile.
         """
         # np.nanmedian() entry full of NaN values would produce a numpy
@@ -536,12 +535,13 @@ def _interp_neighbors(arr, yindx, xindx):
         arr : ndarray
             2-D input array.
         yindx, xindx : ndarray
-            1D arrays, each length N, of row/column indices of the bad pixels.
+            1-D arrays, each length N, of row/column indices of the bad pixels.
 
         Returns
         -------
-        ndarray, shape (2, N)
-            Interpolations in the horizontal (0th index) and vertical (1st index) directions.
+        ndarray
+            Interpolations with shape of ``(2, N)`` in the horizontal (0th index)
+            and vertical (1st index) directions.
         """
         horiz = (arr[yindx, xindx - 1] + arr[yindx, xindx + 1]) / 2.0
         vert = (arr[yindx - 1, xindx] + arr[yindx + 1, xindx]) / 2.0
@@ -566,14 +566,14 @@ def mingrad(self, arrays):
 
         Parameters
         ----------
-        arrays : PixelReplaceArrays
+        arrays : `PixelReplaceArrays`
             Pixel arrays and dispersion direction for the 2D spectrum to process.
-            Arrays are modified in place.
+            Arrays are modified in-place.
 
         Returns
         -------
-        arrays : PixelReplaceArrays
-            The same PixelReplaceArrays with flagged bad pixels now flagged with FLUX_ESTIMATED
+        arrays : `PixelReplaceArrays`
+            The input with flagged bad pixels now flagged with FLUX_ESTIMATED
             and holding a flux value estimated from adjacent pixels.
         """
         # np.nanmedian() entry full of NaN values would produce a numpy
@@ -673,17 +673,19 @@ def custom_slice(self, dispaxis, index):
         Parameters
         ----------
         dispaxis : int
-            Using module-defined HORIZONTAL=1,
-            VERTICAL=2
+            Using module-defined:
+
+            * 1 = HORIZONTAL
+            * 2 = VERTICAL
 
         index : int or list
             Index or indices of cross-dispersion
             vectors to slice
 
         Returns
         -------
-        Tuple
-            Slice constructed using np.s_
+        tuple
+            Slice constructed using numpy
         """
         if dispaxis == self.HORIZONTAL:
             return np.s_[:, index]
@@ -694,24 +696,22 @@ def custom_slice(self, dispaxis, index):
 
     def profile_mse(self, scale, median, current):
         """
-        Calculate mean squared error of fitted profile.
+        Calculate mean-squared error of fitted profile.
 
         Parameters
         ----------
         scale : float
             Initial estimate of scale factor to bring
             normalized median profile up to current profile
-        median : array
-            Median profile constructed from neighboring
-            profile slices
-        current : array
-            Current profile with bad pixels to be
-            replaced
+        median : ndarray
+            Median profile constructed from neighboring profile slices
+        current : ndarray
+            Current profile with bad pixels to be replaced
 
         Returns
         -------
         float
-            Mean squared error for minimization purposes
+            Mean-squared error for minimization purposes
         """
         return np.nansum((current - (median * scale)) ** 2.0) / (
             len(median) - np.count_nonzero(np.isnan(current))

jwst/pixel_replace/pixel_replace_step.py

@@ -1,3 +1,5 @@
+"""Estimate missing pixel values in spectral data."""
+
 import logging
 
 from jwst import datamodels