DOC: Complete API for IPC

docs/jwst/ipc/api_ref.rst

@@ -0,0 +1,18 @@
+===
+API
+===
+
+Public Step API
+===============
+
+.. automodapi:: jwst.ipc.ipc_step
+   :no-inheritance-diagram:
+
+Complete Developer API
+======================
+
+.. automodapi:: jwst.ipc.ipc_corr
+   :no-inheritance-diagram:
+
+.. automodapi:: jwst.ipc.x_irs2
+   :no-inheritance-diagram:

docs/jwst/ipc/description.rst

@@ -1,15 +1,15 @@
 Description
 ===========
 
-:Class: `jwst.ipc.IPCStep`
+:Class: `jwst.ipc.ipc_step.IPCStep`
 :Alias: ipc
 
-The ``ipc`` step corrects a JWST exposure for interpixel capacitance by
+The ``ipc`` step corrects a JWST exposure for InterPixel Capacitance (IPC) by
 convolving with an IPC reference image.
 
-The current implementation uses an IPC reference file that is normally
-a small, rectangular image (e.g. 3 x 3 pixels), a deconvolution kernel.
-The kernel may, however, be a 4-D array (e.g. 3 x 3 x 2048 x 2048),
+The current implementation uses an :ref:`ipc_reffile` that is normally
+a small, rectangular image (e.g., 3 x 3 pixels), a deconvolution kernel.
+The kernel may, however, be a 4-D array (e.g., 3 x 3 x 2048 x 2048),
 to allow the IPC correction to vary across the detector.
 
 For each integration in the input science data, the data are corrected
@@ -20,7 +20,10 @@ contribute a value of zero to the convolution.  The ERR and DQ arrays
 will not be modified.
 
 Subarrays
-=========
-
+---------
 Subarrays are treated the same as full-frame data, with the exception
 that the reference pixels may be absent.
+
+Step Arguments
+--------------
+The IPC deconvolution step has no step-specific arguments.

docs/jwst/ipc/index.rst

@@ -8,7 +8,5 @@ IPC Correction
    :maxdepth: 2
 
    description.rst
-   arguments.rst
    reference_files.rst
-
-.. automodapi:: jwst.ipc
+   api_ref.rst

docs/jwst/references_general/ipc_reffile.inc

@@ -36,19 +36,28 @@ as described below:
 EXTNAME  XTENSION  NAXIS  Dimensions                     Data type
 =======  ========  =====  =============================  =========
 SCI      IMAGE       2    nkern x nkern                  float
-or
+=======  ========  =====  =============================  =========
+
+*or*
+
+=======  ========  =====  =============================  =========
+EXTNAME  XTENSION  NAXIS  Dimensions                     Data type
+=======  ========  =====  =============================  =========
 SCI      IMAGE       4    ncols x nrows x nkern x nkern  float
 =======  ========  =====  =============================  =========
 
-Two formats are currently supported for the IPC kernel: a small 2-D array
-or a 4-D array.  If the kernel is 2-D, its dimensions should be odd,
+Two formats are currently supported for the IPC kernel:
+
+* a small 2-D array
+* a 4-D array
+
+If the kernel is 2-D, its dimensions should be odd,
 for example 3 x 3 or 5 x 5 pixels.  The value at the center pixel will be
-larger than 1 (e.g. 1.02533) and the sum of all pixel values will be
+larger than 1 (e.g., 1.02533) and the sum of all pixel values will be
 equal to 1.
 
 A 4-D kernel may be used to allow the IPC correction to vary from pixel
 to pixel across the image.  In this case, the axes that are most rapidly
 varying (the last two in Python notation; the first two in IRAF/FITS notation)
 have dimensions equal to those of a full-frame image.  At each point in
-that image, there will be a small, 2-D kernel as described in the previous
-paragraph.
+that image, there will be a small, 2-D kernel as described above.

docs/jwst/references_general/ipc_selection.inc

@@ -15,4 +15,3 @@ NIRCam     INSTRUME, DETECTOR, DATE-OBS, TIME-OBS
 NIRISS     INSTRUME, DETECTOR, DATE-OBS, TIME-OBS
 NIRSpec    INSTRUME, DETECTOR, DATE-OBS, TIME-OBS
 ========== ======================================
-

jwst/ipc/ipc_corr.py

@@ -1,6 +1,4 @@
-#
-#  Module for IPC correction.
-#
+"""Functions for IPC correction."""
 
 import logging
 from collections import namedtuple
@@ -25,16 +23,16 @@ def do_correction(input_model, ipc_model):
 
     Parameters
     ----------
-    input_model : data model object
+    input_model : `~stdatamodels.jwst.datamodels.JwstDataModel`
         Science data to be corrected.
 
-    ipc_model : ipc model object
+    ipc_model : `~stdatamodels.jwst.datamodels.IPCModel`
         Deconvolution kernel, either a 2-D or 4-D image in the first
         extension.
 
     Returns
     -------
-    output_model : data model object
+    output_model : `~stdatamodels.jwst.datamodels.JwstDataModel`
         IPC-corrected science data.
     """
     # Save some data params for easy use later
@@ -60,16 +58,16 @@ def ipc_correction(output, ipc_model):
 
     Parameters
     ----------
-    output : data model object
+    output : `~stdatamodels.jwst.datamodels.JwstDataModel`
         The input science data.
 
-    ipc_model : IPCModel object
+    ipc_model : `~stdatamodels.jwst.datamodels.IPCModel`
         The IPC kernel.  The input is corrected for IPC by convolving
         with this 2-D or 4-D array.
 
     Returns
     -------
-    output : data model object
+    output : `~stdatamodels.jwst.datamodels.JwstDataModel`
         IPC-corrected science data.
     """
     log.debug(
@@ -125,13 +123,14 @@ def get_num_ref_pixels(input_model):
 
     Parameters
     ----------
-    input_model : data model object
+    input_model : `~stdatamodels.jwst.datamodels.JwstDataModel`
         The input science data.
 
     Returns
     -------
     nref : namedtuple
-        Tuple containing the number of reference pixels at each edge
+        Tuple containing the number of reference pixels at each edge:
+
         bottom_rows : int
             The number of reference rows at the bottom of the image.
         top_rows : int
@@ -169,17 +168,17 @@ def get_ipc_slice(input_model, ipc_model):
 
     Parameters
     ----------
-    input_model : data model object
+    input_model : `~stdatamodels.jwst.datamodels.JwstDataModel`
         The input science data.
 
-    ipc_model : data model object
+    ipc_model : `~stdatamodels.jwst.datamodels.IPCModel`
         The IPC kernel model.
 
     Returns
     -------
-    kernel : numpy.ndarray, either 2-D or 4-D
+    kernel : ndarray, either 2-D or 4-D
         The data array for the IPC kernel.  If the IPC kernel is 4-D and
-        the science data array is a subarray, `kernel` will be a slice of
+        the science data array is a subarray, ``kernel`` will be a slice of
         the reference image; otherwise, this will be the full image.
     """
     if len(ipc_model.data.shape) == 2:
@@ -207,17 +206,18 @@ def ipc_convolve(output_data, kernel, nref):
 
     Parameters
     ----------
-    output_data : numpy.ndarray, 2-D
-        A copy of the input science data for one group; this will be
+    output_data : ndarray
+        A copy of the 2-D input science data for one group; this will be
         modified in-place.
 
-    kernel : numpy.ndarray, 2-D or 4-D
-        The IPC kernel; the input is corrected for IPC by convolving with
-        this array.  If it is 4-D the last two dimensions will be a slice
-        that matches the last two dimensions of `output_data`.
+    kernel : ndarray
+        The IPC kernel (2-D or 4-D); the input is corrected for IPC by convolving with
+        this array.  If it is 4-D, the last two dimensions will be a slice
+        that matches the last two dimensions of ``output_data``.
 
     nref : namedtuple
         Tuple containing number of reference pixels at each edge:
+
         bottom_rows : int
             The number of reference rows at the bottom of the image.
         top_rows : int

jwst/ipc/ipc_step.py

@@ -1,3 +1,5 @@
+"""Perform the IPC (Inter-Pixel Capacitance) correction step."""
+
 import logging
 
 from stdatamodels.jwst import datamodels