From d3328a8be6253acd00ec0bf6cc084bc5b63b7e61 Mon Sep 17 00:00:00 2001 From: Pey Lian Lim <2090236+pllim@users.noreply.github.com> Date: Tue, 7 Apr 2026 18:55:54 -0400 Subject: [PATCH] DOC: Complete API for IPC --- docs/jwst/ipc/api_ref.rst | 18 +++ docs/jwst/ipc/arguments.rst | 4 - docs/jwst/ipc/description.rst | 17 ++- docs/jwst/ipc/index.rst | 4 +- docs/jwst/references_general/ipc_reffile.inc | 21 ++- .../jwst/references_general/ipc_selection.inc | 1 - jwst/ipc/ipc_corr.py | 42 +++--- jwst/ipc/ipc_step.py | 2 + jwst/ipc/x_irs2.py | 128 ++++++++---------- 9 files changed, 120 insertions(+), 117 deletions(-) create mode 100644 docs/jwst/ipc/api_ref.rst delete mode 100644 docs/jwst/ipc/arguments.rst diff --git a/docs/jwst/ipc/api_ref.rst b/docs/jwst/ipc/api_ref.rst new file mode 100644 index 00000000000..8fa8741a768 --- /dev/null +++ b/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: diff --git a/docs/jwst/ipc/arguments.rst b/docs/jwst/ipc/arguments.rst deleted file mode 100644 index f174b2ecbea..00000000000 --- a/docs/jwst/ipc/arguments.rst +++ /dev/null @@ -1,4 +0,0 @@ -Step Arguments -============== - -The IPC deconvolution step has no step-specific arguments. diff --git a/docs/jwst/ipc/description.rst b/docs/jwst/ipc/description.rst index 427553dee0c..67a5f4aa241 100644 --- a/docs/jwst/ipc/description.rst +++ b/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. diff --git a/docs/jwst/ipc/index.rst b/docs/jwst/ipc/index.rst index 187492f78d1..91af322a260 100644 --- a/docs/jwst/ipc/index.rst +++ b/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 diff --git a/docs/jwst/references_general/ipc_reffile.inc b/docs/jwst/references_general/ipc_reffile.inc index ad1402e0476..3df46b15177 100644 --- a/docs/jwst/references_general/ipc_reffile.inc +++ b/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. \ No newline at end of file diff --git a/docs/jwst/references_general/ipc_selection.inc b/docs/jwst/references_general/ipc_selection.inc index b6c9255bd71..3573f2003c4 100644 --- a/docs/jwst/references_general/ipc_selection.inc +++ b/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 ========== ====================================== - diff --git a/jwst/ipc/ipc_corr.py b/jwst/ipc/ipc_corr.py index 513f0a12ba4..8c249b66404 100644 --- a/jwst/ipc/ipc_corr.py +++ b/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 diff --git a/jwst/ipc/ipc_step.py b/jwst/ipc/ipc_step.py index c85306d45a3..e912fec033d 100644 --- a/jwst/ipc/ipc_step.py +++ b/jwst/ipc/ipc_step.py @@ -1,3 +1,5 @@ +"""Perform the IPC (Inter-Pixel Capacitance) correction step.""" + import logging from stdatamodels.jwst import datamodels diff --git a/jwst/ipc/x_irs2.py b/jwst/ipc/x_irs2.py index 4a5e3f1fca1..5190d3004bd 100644 --- a/jwst/ipc/x_irs2.py +++ b/jwst/ipc/x_irs2.py @@ -4,32 +4,6 @@ from jwst.lib import pipe_utils -""" This is the interface: - mask = make_mask(input_model) - Create a mask for extracting normal pixels; used by `from_irs2` and - `to_irs2`. - Parameters `n` and `r` can be gotten from metadata if `input_model` - is a `jwst.datamodels` object. If `input_model` is instead a - numpy.ndarray, `n` and `r` can be specified as keyword arguments. - If they are not specified, function `_get_irs2_parameters` will - assign values that at the time of writing are correct. If there - is any doubt about using the default values, they should be - specified explicitly. - shape = normal_shape(input_model, n=n, r=r) - Return the shape of the data array when excluding interleaved - reference pixels. - `n` and `r` can be specified as keyword arguments. - normal_data = from_irs2(irs2_data, mask, detector) - Extract the normal pixels from data in IRS2 format. - to_irs2(irs2_data, normal_data, mask, detector) - Insert an array of normal pixels back into data in IRS2 format. - - Note that `input_model` may be either a jwst.datamodels object or a - numpy.ndarray (though in the latter case the parameters will be - assigned default values, unless specified explicitly). -""" - - ReadoutParam = namedtuple("ReadoutParam", ["refout", "n", "r"]) __all__ = ["normal_shape", "make_mask", "from_irs2", "to_irs2"] @@ -41,36 +15,37 @@ def _get_irs2_parameters(input_model, n=None, r=None): Parameters ---------- - input_model : JWST data model - This is most likely a RampModel object; it's used for getting the + input_model : `~stdatamodels.jwst.datamodels.JwstDataModel` + This is most likely a `~stdatamodels.jwst.datamodels.RampModel`; it's used for getting the width of the reference output and the values of NRS_NORM and NRS_REF. n : int or None - If not None, this value will be used for the `nrs_normal` - parameter. If `n` is None, the value will be obtained from the - metadata for `input_model`, or, if this fails (e.g. if - `input_model` is actually an ndarray), a default value of 16 will + If not None, this value will be used for the ``nrs_normal`` + parameter. If ``n`` is None, the value will be obtained from the + metadata for ``input_model``, or, if this fails (e.g., if + ``input_model`` is actually an ndarray), a default value of 16 will be used. None is the default. r : int or None - If not None, this value will be used for the `nrs_reference` - parameter. See also the description for `n`. None is the default. + If not None, this value will be used for the ``nrs_reference`` + parameter. See also the description for ``n``. None is the default. Returns ------- param : namedtuple - Tuple containing reference pixel parameters - param.refout : int + Tuple containing reference pixel parameters: + + refout : int The length (in the last image axis) of the reference output section. The reference output is assumed to be on the left side of the IRS2-format image. - param.n : int + n : int The number of "normal" (as opposed to reference) pixels read out before jumping to the reference pixel region. - param.r : int + r : int The number of reference pixels read out before jumping back to the normal pixel region. """ @@ -96,28 +71,29 @@ def _get_irs2_parameters(input_model, n=None, r=None): def normal_shape(input_model, n=None, r=None, detector=None): """ - Determine the shape of the 'normal' pixel data. + Determine the shape of the 'normal' pixel data when excluding interleaved reference pixels. Parameters ---------- - input_model : JWST data model, or an ndarray + input_model : `~stdatamodels.jwst.datamodels.JwstDataModel` or ndarray Either the input science data model or the data array from the input data model. n : int or None - If not None, this value will be used for the `nrs_normal` - parameter. If `n` is None, the value will be obtained from the - metadata for `input_model`, or, if this fails (e.g. if - `input_model` is actually an ndarray), a default value will + If not None, this value will be used for the ``nrs_normal`` + parameter. If ``n`` is None, the value will be obtained from the + metadata for ``input_model``, or, if this fails (e.g., if + ``input_model`` is actually an ndarray), a default value will be used. None is the default. r : int or None - If not None, this value will be used for the `nrs_reference` - parameter. See also the description for `n`. None is the default. + If not None, this value will be used for the ``nrs_reference`` + parameter. See also the description for ``n``. None is the default. detector : str or None - When `input_model` is a JWST data model, the detector name can be - gotten from the metadata. If `input_model` is an ndarray, the + When ``input_model`` is a `~stdatamodels.jwst.datamodels.JwstDataModel`, + the detector name can be + gotten from the metadata. If ``input_model`` is an ndarray, the detector name should be explicitly specified. For NIRSpec data, the value should be either "NRS1" or "NRS2". @@ -160,27 +136,29 @@ def make_mask(input_model, n=None, r=None): """ Create a mask to extract 'normal' pixels. + This is used by :func:`from_irs2` and :func:`to_irs2`. + Parameters ---------- - input_model : JWST data model, or an ndarray + input_model : `~stdatamodels.jwst.datamodels.JwstDataModel` or ndarray Either the input science data model or the data array from the input data model. This is used for getting the IRS2 parameters and the length of the longer image axis. - n : int or None (default is None) - If not None, this value will be used for the `nrs_normal` - parameter. If `n` is None, the value will be obtained from the - metadata for `input_model`; if this fails (e.g. if `input_model` - is actually an ndarray), a default value of 16 will be used. + n : int or None + If not None, this value will be used for the ``nrs_normal`` + parameter. If ``n`` is None, the value will be obtained from the + metadata for ``input_model``; if this fails (e.g., if ``input_model`` + is actually an ndarray), a default value of 16 will be used. None is the default. - r : int or None (default is None) - If not None, this value will be used for the `nrs_reference` - parameter. See also the description for `n`. None is the default. + r : int or None + If not None, this value will be used for the ``nrs_reference`` + parameter. See also the description for ``n``. None is the default. Returns ------- - irs2_mask : 1-D bool numpy.ndarray - Boolean index mask with length equal to the last axis of + irs2_mask : ndarray + Boolean index mask (1-D) with length equal to the last axis of the science data shape. """ param = _get_irs2_parameters(input_model, n=n, r=r) @@ -234,27 +212,27 @@ def from_irs2(irs2_data, irs2_mask, detector=None): Parameters ---------- - irs2_data : numpy.ndarray + irs2_data : ndarray Data in IRS2 format. This can be a slice in the Y direction, but it should include the entire X (last) axis. - irs2_mask : 1-D numpy.ndarray, bool + irs2_mask : ndarray Boolean mask to extract the "normal" pixels. This is a 1-D array with length equal to the size of the next-to-last axis (for data - in DMS orientation) of `irs2_data`. + in DMS orientation) of ``irs2_data``. detector : str or None - For IRS2 data in DMS orientation, `detector` should be either + For IRS2 data in DMS orientation, ``detector`` should be either "NRS1" or "NRS2"; NIRSpec is currently the only instrument supported in this module. The mask will be applied to the rows, and for "NRS2" the mask will first be reversed. - For IRS2 data in detector orientation, `detector` should be None + For IRS2 data in detector orientation, ``detector`` should be None (the default), and the mask will be applied to the columns. Returns ------- ndarray - The normal pixel data (i.e. without embedded reference pixels). + The normal pixel data (i.e., without embedded reference pixels). """ if detector is None: # Select columns. @@ -278,25 +256,25 @@ def to_irs2(irs2_data, norm_data, irs2_mask, detector=None): Parameters ---------- - irs2_data : numpy.ndarray + irs2_data : ndarray Data in IRS2 format. This will be modified in-place. - norm_data : numpy.ndarray - The normal data, for example previously extracted from `irs2_data` + norm_data : ndarray + The normal data, for example previously extracted from ``irs2_data`` but then modified in some way. This will be copied back into - `irs2_data` in the correct locations, as specified by `irs2_mask`. + ``irs2_data`` in the correct locations, as specified by ``irs2_mask``. - irs2_mask : 1-D numpy.ndarray, bool - Boolean mask identifying the locations of the "normal" pixels - within `irs2_data`. The length is equal to the size of the - next-to-last axis (for data in DMS orientation) of `irs2_data`. + irs2_mask : ndarray + Boolean mask (1-D) identifying the locations of the "normal" pixels + within ``irs2_data``. The length is equal to the size of the + next-to-last axis (for data in DMS orientation) of ``irs2_data``. detector : str or None - For IRS2 data in DMS orientation, `detector` should be either + For IRS2 data in DMS orientation, ``detector`` should be either "NRS1" or "NRS2"; NIRSpec is currently the only instrument supported in this module. The mask will be applied to the rows, and for "NRS2" the mask will first be reversed. - For IRS2 data in detector orientation, `detector` should be None + For IRS2 data in detector orientation, ``detector`` should be None (the default), and the mask will be applied to the columns. """ if detector is None: