Skip to content

Commit

Permalink
Clean up docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@melanieclarke
melanieclarke committed Oct 3, 2024
1 parent 084dd1a commit d4e89a9
Show file tree
Hide file tree
Showing 3 changed files with 152 additions and 29 deletions.
90 changes: 83 additions & 7 deletions jwst/outlier_detection/_fileio.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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_", "_")
Expand Down
8 changes: 3 additions & 5 deletions jwst/outlier_detection/spec.py
View file
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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.
"""
Expand Down
83 changes: 66 additions & 17 deletions jwst/outlier_detection/utils.py
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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)
Expand All @@ -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 input exposures, for both
imaging and spectral modes.
Parameters
----------
Expand All @@ -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)
Expand Down Expand Up @@ -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
----------
Expand All @@ -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)
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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:
Expand Down

0 comments on commit d4e89a9

Please sign in to comment.