Background

class specreduce.background.Background(image: ~numpy.ndarray | ~astropy.nddata.nddata.NDData | ~astropy.units.quantity.Quantity, traces: list = <factory>, width: float = 5, statistic: str = 'average', disp_axis: int = 1, crossdisp_axis: int = 0, mask_treatment: ~typing.Literal['apply', 'ignore', 'propagate', 'zero_fill', 'nan_fill', 'apply_mask_only', 'apply_nan_only'] = 'apply')

Bases: _ImageParser

Determine the background from an image for subtraction.

Example:

trace = FlatTrace(image, trace_pos)
bg = Background.two_sided(image, trace, bkg_sep, width=bkg_width)
subtracted_image = image - bg

Parameters:

image

Image with 2-D spectral image data

tracesList, specreduce.tracing.Trace, int, float

Individual or list of trace object(s) (or integers/floats to define FlatTraces) to extract the background. If None, a FlatTrace at the center of the image (according to disp_axis) will be used.

width

Width of extraction aperture in pixels.

statistic

Statistic to use when computing the background. average will account for partial pixel weights, median will include all partial pixels.

disp_axis

Dispersion axis.

crossdisp_axis

Cross-dispersion axis.

mask_treatment

Specifies how to handle masked or non-finite values in the input image. The accepted values are:

• apply: The image remains unchanged, and any existing mask is combined with a mask derived from non-finite values.

• ignore: The image remains unchanged, and any existing mask is dropped.

• propagate: The image remains unchanged, and any masked or non-finite pixel causes the mask to extend across the entire cross-dispersion axis.

• zero_fill: Pixels that are either masked or non-finite are replaced with 0.0, and the mask is dropped.

• nan_fill: Pixels that are either masked or non-finite are replaced with nan, and the mask is dropped.

• apply_mask_only: The image and mask are left unmodified.

• apply_nan_only: The image is left unmodified, the old mask is dropped, and a new mask is created based on non-finite values.

Attributes Summary

bkg_array
crossdisp_axis
disp_axis
image
mask_treatment
statistic
traces
width

Methods Summary

bkg_image([image])	Expose the background tiled to the dimension of image.
bkg_spectrum([image, bkg_statistic])	Expose the 1D spectrum of the background.
one_sided(image, trace_object, separation, ...)	Determine the background from an image for subtraction above or below an input trace.
sub_image([image])	Subtract the computed background from image.
sub_spectrum([image])	Expose the 1D spectrum of the background-subtracted image.
two_sided(image, trace_object, separation, ...)	Determine the background from an image for subtraction centered around an input trace.

Attributes Documentation

bkg_array

Deprecated since version 1.3: The bkg_array attribute is deprecated and may be removed in a future version.

crossdisp_axis: int = 0

disp_axis: int = 1

image: ndarray | NDData | Quantity = <dataclasses._MISSING_TYPE object>

mask_treatment: Literal['apply', 'ignore', 'propagate', 'zero_fill', 'nan_fill', 'apply_mask_only', 'apply_nan_only'] = 'apply'

statistic: str = 'average'

traces: list = <dataclasses._MISSING_TYPE object>

width: float = 5

Methods Documentation

bkg_image(image=None)

Expose the background tiled to the dimension of image.

Parameters:

imageNDData-like or array-like, optional

Image with 2-D spectral image data. Assumes cross-dispersion (spatial) direction is axis 0 and dispersion (wavelength) direction is axis 1. If None, will extract the background from image used to initialize the class. [default: None]

Returns:

specSpectrum1D

Spectrum object with same shape as image.

bkg_spectrum(image=None, bkg_statistic=None)

Expose the 1D spectrum of the background.

Parameters:

imageNDData-like or array-like, optional

Image with 2-D spectral image data. Assumes cross-dispersion (spatial) direction is axis 0 and dispersion (wavelength) direction is axis 1. If None, will extract the background from image used to initialize the class. [default: None]

Returns:

specSpectrum1D

The background 1-D spectrum, with flux expressed in the same units as the input image (or DN if none were provided).

classmethod one_sided(image, trace_object, separation, **kwargs)

Determine the background from an image for subtraction above or below an input trace.

Example:

trace = FitTrace(image, guess=trace_pos)
bg = Background.one_sided(image, trace, bkg_sep, width=bkg_width)

Parameters:

imageNDData-like or array-like

Image with 2-D spectral image data. Assumes cross-dispersion (spatial) direction is axis 0 and dispersion (wavelength) direction is axis 1.

trace_object: `~specreduce.tracing.Trace`

estimated trace of the spectrum to center the background traces

separation: float

separation from trace_object for the background, positive will be above the trace, negative below.

widthfloat

width of each background aperture in pixels

statistic: string

statistic to use when computing the background. ‘average’ will account for partial pixel weights, ‘median’ will include all partial pixels.

disp_axisint

dispersion axis

crossdisp_axisint

cross-dispersion axis

mask_treatmentstring

The method for handling masked or non-finite data. Choice of filter, omit, or zero_fill. If filter is chosen, masked/non-finite data will be filtered during the fit to each bin/column (along disp. axis) to find the peak. If omit is chosen, columns along disp_axis with any masked/non-finite data values will be fully masked (i.e, 2D mask is collapsed to 1D and applied). If zero_fill is chosen, masked/non-finite data will be replaced with 0.0 in the input image, and the mask will then be dropped. For all three options, the input mask (optional on input NDData object) will be combined with a mask generated from any non-finite values in the image data.

sub_image(image=None)

Subtract the computed background from image.

Parameters:

imagenddata-compatible image or None

image with 2-D spectral image data. If None, will extract the background from image used to initialize the class.

Returns:

specSpectrum1D

Spectrum object with same shape as image.

sub_spectrum(image=None)

Expose the 1D spectrum of the background-subtracted image.

Parameters:

imagenddata-compatible image or None

image with 2-D spectral image data. If None, will extract the background from image used to initialize the class.

Returns:

specSpectrum1D

The background 1-D spectrum, with flux expressed in the same units as the input image (or u.DN if none were provided) and the spectral axis expressed in pixel units.

classmethod two_sided(image, trace_object, separation, **kwargs)

Determine the background from an image for subtraction centered around an input trace.

Example:

trace = FitTrace(image, guess=trace_pos)
bg = Background.two_sided(image, trace, bkg_sep, width=bkg_width)

Parameters:

imageNDData-like or array-like

Image with 2-D spectral image data. Assumes cross-dispersion (spatial) direction is axis 0 and dispersion (wavelength) direction is axis 1.

trace_object: `~specreduce.tracing.Trace`

estimated trace of the spectrum to center the background traces

separation: float

separation from trace_object for the background regions

widthfloat

width of each background aperture in pixels

statistic: string

statistic to use when computing the background. ‘average’ will account for partial pixel weights, ‘median’ will include all partial pixels.

disp_axisint

dispersion axis

crossdisp_axisint

cross-dispersion axis

mask_treatmentstring

The method for handling masked or non-finite data. Choice of filter, omit`, or ``zero_fill. If filter is chosen, masked/non-finite data will be filtered during the fit to each bin/column (along disp. axis) to find the peak. If omit is chosen, columns along disp_axis with any masked/non-finite data values will be fully masked (i.e, 2D mask is collapsed to 1D and applied). If zero_fill is chosen, masked/non-finite data will be replaced with 0.0 in the input image, and the mask will then be dropped. For all three options, the input mask (optional on input NDData object) will be combined with a mask generated from any non-finite values in the image data.