Clean up docstrings

jwst/outlier_detection/_fileio.py

@@ -4,29 +4,91 @@
 
 
 def save_median(median_model, make_output_path):
-    '''
-    Save median if requested by user
+    """Save a median model.
+
+    Output suffix is 'median'.
 
     Parameters
     ----------
     median_model : ~jwst.datamodels.ImageModel
         The median ImageModel or CubeModel to save
-    '''
+
+    make_output_path : function
+        A function to be used to create an output path from
+        an input path and an optional suffix.
+
+    """
     _save_intermediate_output(median_model, "median", make_output_path)
 
 
 def save_drizzled(drizzled_model, make_output_path):
+    """Save a drizzled model.
+
+    Input model is expected to have a filename that ends with
+    either 'outlier_i2d.fits' or 'outlier_s2d.fits'.
+
+    Parameters
+    ----------
+    drizzled_model : ~jwst.datamodels.ImageModel
+        The median ImageModel or CubeModel to save.
+
+    make_output_path : function
+        A function to be used to create an output path from
+        an input path and an optional suffix.
+
+    """
     expected_tail = "outlier_?2d.fits"
     suffix = drizzled_model.meta.filename[-len(expected_tail):-5]
     _save_intermediate_output(drizzled_model, suffix, make_output_path)
 
 
 def save_blot(input_model, blot, blot_err, make_output_path):
+    """Save a blotted model.
+
+    Output suffix is 'blot'.
+
+    Parameters
+    ----------
+    input_model : ~jwst.datamodels.ImageModel
+        An input model corresponding to the blotted data,
+        containing metadata to copy.
+
+    blot : array-like
+        The blotted science data.
+
+    blot_err : array-like or None
+        The blotted error data, if available.
+
+    make_output_path : function
+        A function to be used to create an output path from
+        an input path and an optional suffix.
+
+    """
     blot_model = _make_blot_model(input_model, blot, blot_err)
     _save_intermediate_output(blot_model, "blot", make_output_path)
 
 
 def _make_blot_model(input_model, blot, blot_err):
+    """Assemble a blot model.
+
+    Parameters
+    ----------
+    input_model : ~jwst.datamodels.ImageModel
+        An input model corresponding to the blotted data,
+        containing metadata to copy.
+
+    blot : array-like
+        The blotted science data.
+
+    blot_err : array-like or None
+        The blotted error data, if available.
+
+    Returns
+    -------
+    blot_model : ~jwst.datamodels.ImageModel
+        An image model containing the blotted data.
+
+    """
     blot_model = type(input_model)()
     blot_model.data = blot
     if blot_err is not None:
@@ -36,15 +98,29 @@ def _make_blot_model(input_model, blot, blot_err):
 
 
 def _save_intermediate_output(model, suffix, make_output_path):
-    """
-    Ensure all intermediate outputs from OutlierDetectionStep have consistent file naming conventions
-    
+    """Save an intermediate output from outlier detection.
+
+    Ensure all intermediate outputs from OutlierDetectionStep have
+    consistent file naming conventions.
+
+    Parameters
+    ----------
+    model : ~jwst.datamodels.ImageModel
+        The intermediate datamodel to save.
+
+    suffix : str
+        A suffix to add to the output file name.
+
+    make_output_path : function
+        A function to be used to create an output path from
+        an input path and an optional suffix.
+
     Notes
     -----
     self.make_output_path() is updated globally for the step in the main pipeline
     to include the asn_id in the output path, so no need to handle it here.
-    """
 
+    """
     # outlier_?2d is not a known suffix, and make_output_path cannot handle an
     # underscore in an unknown suffix, so do a manual string replacement
     input_path = model.meta.filename.replace("_outlier_", "_")

jwst/outlier_detection/spec.py

@@ -1,6 +1,5 @@
-"""
-Submodule for performing outlier detection on spectra.
-"""
+"""Perform outlier detection on spectra."""
+
 from jwst.datamodels import ModelContainer, ModelLibrary
 from jwst.stpipe.utilities import record_step_status
 
@@ -36,8 +35,7 @@ def detect_outliers(
     in_memory,
     make_output_path,
 ):
-    """
-    Flag outliers in spec data.
+    """Flag outliers in spec data.
 
     See `OutlierDetectionStep.spec` for documentation of these arguments.
     """

jwst/outlier_detection/utils.py

@@ -1,6 +1,4 @@
-"""
-The ever-present utils sub-module. A home for all...
-"""
+"""Utilities for outlier detection methods."""
 
 import copy
 from functools import partial
@@ -24,6 +22,21 @@
 
 
 def create_cube_median(cube_model, maskpt):
+    """Compute the median over a cube of data.
+
+    Parameters
+    ----------
+    cube_model : ~jwst.datamodels.CubeModel
+        The input cube model.
+    maskpt : float
+        The percent threshold for masking bad data.
+
+    Returns
+    -------
+    np.ndarray
+        The median over the first axis of the input cube.
+
+    """
     log.info("Computing median")
 
     weight_threshold = compute_weight_threshold(cube_model.wht, maskpt)
@@ -42,8 +55,10 @@ def median_without_resampling(input_models,
                               make_output_path=None,
                               buffer_size=None,
                               return_error=False):
-    """
-    Shared code between imaging and spec modes for resampling and median computation
+    """Compute a median image without resampling.
+
+    The median is performed across resampled exposures,
+    for both imaging and spectral modes.
 
     Parameters
     ----------
@@ -65,17 +80,29 @@ def median_without_resampling(input_models,
         if True, save the drizzled models and median model to fits.
 
     make_output_path : function
-        The functools.partial instance to pass to save_median. Must be 
+        The functools.partial instance to pass to save_median. Must be
         specified if save_intermediate_results is True. Default None.
 
     buffer_size : int
-        The size of chunk in bytes that will be read into memory when computing the median.
-        This parameter has no effect if the input library has its on_disk attribute
-        set to False.
+        The size of chunk in bytes that will be read into memory when
+        computing the median. This parameter has no effect if the input
+        library has its on_disk attribute set to False.
 
     return_error : bool, optional
         If set, an approximate median error is computed alongside the
         median science image.
+
+    Returns
+    -------
+    median_data : np.ndarray
+        The median data array.
+
+    median_wcs : gwcs.WCS
+        A WCS corresponding to the median data.
+
+    median_error : np.ndarray, optional
+        A median error estimate, returned only if `return_error` is True.
+
     """
     in_memory = not input_models._on_disk
     ngroups = len(input_models)
@@ -131,8 +158,13 @@ def median_with_resampling(input_models,
                            make_output_path=None,
                            buffer_size=None,
                            return_error=False):
-    """
-    Shared code between imaging and spec modes for resampling and median computation
+    """Compute a median image with resampling.
+
+    The median is performed across exposures, for both imaging
+    and spectral modes.
+
+    Shared code between imaging and spec modes for resampling and
+    median computation.
 
     Parameters
     ----------
@@ -149,21 +181,33 @@ def median_with_resampling(input_models,
         if True, save the drizzled models and median model to fits.
 
     make_output_path : function
-        The functools.partial instance to pass to save_median. Must be 
+        The functools.partial instance to pass to save_median. Must be
         specified if save_intermediate_results is True. Default None.
 
     buffer_size : int
-        The size of chunk in bytes that will be read into memory when computing the median.
-        This parameter has no effect if the input library has its on_disk attribute
-        set to False.
+        The size of chunk in bytes that will be read into memory when
+        computing the median. This parameter has no effect if the input
+        library has its on_disk attribute set to False.
 
     return_error : bool, optional
         If set, an approximate median error is computed alongside the
         median science image.
+
+    Returns
+    -------
+    median_data : np.ndarray
+        The median data array.
+
+    median_wcs : gwcs.WCS
+        A WCS corresponding to the median data.
+
+    median_error : np.ndarray, optional
+        A median error estimate, returned only if `return_error` is True.
+
     """
     if not resamp.single:
         raise ValueError("median_with_resampling should only be used for resample_many_to_many")
-    
+
     in_memory = not input_models._on_disk
     indices_by_group = list(input_models.group_indices.values())
     ngroups = len(indices_by_group)
@@ -219,10 +263,11 @@ def flag_crs_in_models(
     snr1,
     median_err=None
 ):
+    """Flag outliers in all input models without resampling."""
     for image in input_models:
         # dq flags will be updated in-place
         flag_model_crs(image, median_data, snr1, median_err=median_err)
-    
+
 
 def flag_resampled_model_crs(
     input_model,
@@ -237,6 +282,7 @@ def flag_resampled_model_crs(
     save_blot=False,
     make_output_path=None,
 ):
+    """Flag outliers in a resampled model."""
     if 'SPECTRAL' not in input_model.meta.wcs.output_frame.axes_type:
         input_pixflux_area = input_model.meta.photometry.pixelarea_steradians
         # Set array shape, needed to compute image pixel area
@@ -270,6 +316,7 @@ def _flag_resampled_model_crs(
     scale2,
     backg,
 ):
+    """Flag outliers via comparison to a blotted image."""
     # If the datamodel has a measured background that has not been subtracted
     # use it instead of the user provided backg.
     # Get background level of science data if it has not been subtracted, so it
@@ -308,6 +355,7 @@ def flag_crs_in_models_with_resampling(
     save_blot=False,
     make_output_path=None,
 ):
+    """Flag outliers in all input models, with resampling."""
     for image in input_models:
         flag_resampled_model_crs(image,
                                  median_data,
@@ -323,6 +371,7 @@ def flag_crs_in_models_with_resampling(
 
 
 def flag_model_crs(image, blot, snr, median_err=None):
+    """Flag outliers in a model."""
     if median_err is not None:
         error_to_use = median_err
     else: