Background#

class specreduce.background.Background(image: ndarray | NDData | Quantity, traces: list = <factory>, width: float = 5, statistic: str = 'average', disp_axis: int = 1, crossdisp_axis: int = 0, mask_treatment: Literal['apply', 'ignore', 'propagate', 'zero_fill', 'nan_fill', 'apply_mask_only', 'apply_nan_only']='apply', sigma: None | float = 5.0)[source]#

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

traces

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.

sigma

Number of standard deviations for sigma clipping outlier rejection. Clipping is applied column-by-column along the cross-dispersion axis within the background aperture. If None, no sigma clipping is performed.

Attributes Summary

`bkg_array`
`crossdisp_axis`
`disp_axis`
`image`
`mask_treatment`
`sigma`
`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'#

sigma: None | float = 5.0#

statistic: str = 'average'#

traces: list = <dataclasses._MISSING_TYPE object>#

width: float = 5#

Methods Documentation

bkg_image(image=None) → Spectrum[source]#

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:

specSpectrum: Spectrum object with same shape as image, including uncertainty.

bkg_spectrum(image=None, bkg_statistic=None) → Spectrum[source]#

Expose the 1D spectrum of the background.

Parameters:

image: Image with 2D 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.
bkg_statistic: Deprecated. Use statistic parameter in the Background constructor instead.

Returns:

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

classmethod one_sided(image, trace_object, separation, **kwargs)[source]#

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:

image: Image with 2-D spectral image data. Assumes cross-dispersion (spatial) direction is axis 0 and dispersion (wavelength) direction is axis 1.
trace_object: Estimated trace of the spectrum to center the background trace.
separation: Separation from trace_object for the background. Positive will be above the trace, negative below.
**kwargs: Additional keyword arguments passed to the Background constructor. See Background for available options including width, statistic, disp_axis, crossdisp_axis, mask_treatment, and sigma.

Returns:

Background: A Background object with a one-sided background region.

sub_image(image=None) → Spectrum[source]#

Subtract the computed background from image.

Parameters:

image: NDData-like or array-like 2D spectral image data. If None, will extract the background from image used to initialize the class.

Returns:

Spectrum: Spectrum object with same shape as image, including propagated uncertainty.

sub_spectrum(image=None) → Spectrum[source]#

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

Parameters:

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

Returns:

specSpectrum: The background-subtracted 1D spectrum, with flux and uncertainty 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)[source]#

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:

image: Image with 2-D spectral image data. Assumes cross-dispersion (spatial) direction is axis 0 and dispersion (wavelength) direction is axis 1.
trace_object: Estimated trace of the spectrum to center the background traces.
separation: Separation from trace_object for the background regions.
**kwargs: Additional keyword arguments passed to the Background constructor. See Background for available options including width, statistic, disp_axis, crossdisp_axis, mask_treatment, and sigma.

Returns:

Background: A Background object with two-sided background regions.