Spectrum1D

class specutils.Spectrum1D(flux=None, spectral_axis=None, wcs=None, velocity_convention=None, rest_value=None, redshift=None, radial_velocity=None, bin_specification=None, **kwargs)

Bases: specutils.spectra.spectrum_mixin.OneDSpectrumMixin, astropy.nddata.NDDataRef

Spectrum container for 1D spectral data.

Parameters

fluxastropy.units.Quantity or astropy.nddata.NDData`-like

The flux data for this spectrum.

spectral_axisastropy.units.Quantity or specutils.SpectralAxis

Dispersion information with the same shape as the last (or only) dimension of flux, or one greater than the last dimension of flux if specifying bin edges.

wcsastropy.wcs.WCS or gwcs.wcs.WCS

WCS information object.

velocity_convention{“doppler_relativistic”, “doppler_optical”, “doppler_radio”}

Convention used for velocity conversions.

rest_valueQuantity

Any quantity supported by the standard spectral equivalencies (wavelength, energy, frequency, wave number). Describes the rest value of the spectral axis for use with velocity conversions.

redshift

See redshift for more information.

radial_velocity

See radial_velocity for more information.

uncertaintyNDUncertainty

Contains uncertainty information along with propagation rules for spectrum arithmetic. Can take a unit, but if none is given, will use the unit defined in the flux.

metadict

Arbitrary container for any user-specific information to be carried around with the spectrum container object.

Attributes Summary

bin_edges
data	ndarray-like : The stored dataset.
energy	The energy of the spectral axis as a Quantity in units of eV.
flux	Converts the stored data and unit information into a quantity.
frequency	The frequency as a Quantity in units of GHz
mask	any type : Mask for the dataset, if any.
meta	dict-like : Additional meta information about the dataset.
photon_flux	The flux density of photons as a Quantity, in units of photons per cm^2 per second per spectral_axis unit
radial_velocity	The radial velocity(s) of the objects represented by this spectrum.
read(\*args, \*\*kwargs)
redshift	The redshift(s) of the objects represented by this spectrum.
rest_value
shape
spectral_axis	Returns the SpectralCoord object.
spectral_axis_unit	Deprecated since version v1.1.
spectral_wcs	Returns the spectral axes of the WCS
uncertainty	any type : Uncertainty in the dataset, if any.
unit	Unit : Unit for the dataset, if any.
velocity	Converts the spectral axis array to the given velocity space unit given the rest value.
velocity_convention	Returns the velocity convention
wavelength	The wavelength as a Quantity in units of Angstroms
wcs	any type : A world coordinate system (WCS) for the dataset, if any.
write(\*args, \*\*kwargs)

Methods Summary

add(operand[, operand2])	Performs addition by evaluating self + operand.
divide(operand[, operand2])	Performs division by evaluating self / operand.
multiply(operand[, operand2])	Performs multiplication by evaluating self * operand.
new_flux_unit(self, unit[, equivalencies, …])	Converts the flux data to the specified unit.
subtract(operand[, operand2])	Performs subtraction by evaluating self - operand.
with_spectral_unit(self, unit[, …])	Returns a new spectrum with a different spectral axis unit.
with_velocity_convention(self, …)

Attributes Documentation

bin_edges

data

ndarray-like : The stored dataset.

energy

The energy of the spectral axis as a Quantity in units of eV.

flux

Converts the stored data and unit information into a quantity.

Returns

Quantity

Spectral data as a quantity.

frequency

The frequency as a Quantity in units of GHz

mask

any type : Mask for the dataset, if any.

Masks should follow the numpy convention that valid data points are marked by False and invalid ones with True.

meta

dict-like : Additional meta information about the dataset.

photon_flux

The flux density of photons as a Quantity, in units of photons per cm^2 per second per spectral_axis unit

radial_velocity

The radial velocity(s) of the objects represented by this spectrum. May be scalar (if this spectrum’s flux is 1D) or vector. Note that the concept of “RV of a spectrum” can be ambiguous, so the interpretation is set to some extent by either the user, or operations (like template fitting) that set this attribute when they are run on a spectrum.

read(\*args, \*\*kwargs) = <astropy.nddata.mixins.ndio.NDDataRead object>

redshift

The redshift(s) of the objects represented by this spectrum. May be scalar (if this spectrum’s flux is 1D) or vector. Note that the concept of “redshift of a spectrum” can be ambiguous, so the interpretation is set to some extent by either the user, or operations (like template fitting) that set this attribute when they are run on a spectrum.

rest_value

shape

spectral_axis

Returns the SpectralCoord object.

spectral_axis_unit

Deprecated since version v1.1: The spectral_axis_unit function is deprecated and may be removed in a future version. Use spectral_axis.unit instead.

Returns the units of the spectral axis.

spectral_wcs

Returns the spectral axes of the WCS

uncertainty

any type : Uncertainty in the dataset, if any.

Should have an attribute uncertainty_type that defines what kind of uncertainty is stored, such as 'std' for standard deviation or 'var' for variance. A metaclass defining such an interface is NDUncertainty but isn’t mandatory.

unit

Unit : Unit for the dataset, if any.

velocity

Converts the spectral axis array to the given velocity space unit given the rest value.

These aren’t input parameters but required Spectrum attributes

Parameters

unitstr or ~`astropy.units.Unit`

The unit to convert the dispersion array to.

rest~`astropy.units.Quantity`

Any quantity supported by the standard spectral equivalencies (wavelength, energy, frequency, wave number).

type{“doppler_relativistic”, “doppler_optical”, “doppler_radio”}

The type of doppler spectral equivalency.

redshift or radial_velocity

If present, this shift is applied to the final output velocity to get into the rest frame of the object.

Returns

~`astropy.units.Quantity`

The converted dispersion array in the new dispersion space.

velocity_convention

Returns the velocity convention

wavelength

The wavelength as a Quantity in units of Angstroms

wcs

any type : A world coordinate system (WCS) for the dataset, if any.

write(\*args, \*\*kwargs) = <astropy.nddata.mixins.ndio.NDDataWrite object>

Methods Documentation

classmethod add(operand, operand2=None, \*\*kwargs)

Performs addition by evaluating self + operand.

Parameters

operand, operand2NDData-like instance or convertible to one.

If operand2 is None or not given it will perform the operation self + operand. If operand2 is given it will perform operand + operand2. If the method was called on a class rather than on the instance operand2 must be given.

propagate_uncertaintiesbool or None, optional

If None the result will have no uncertainty. If False the result will have a copied version of the first operand that has an uncertainty. If True the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties are NDUncertainty-like. Default is True.

Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated. None was added as valid parameter value.

handle_maskcallable, 'first_found' or None, optional

If None the result will have no mask. If 'first_found' the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the results mask and if necessary provide a copy. Default is numpy.logical_or.

New in version 1.2.

handle_metacallable, 'first_found' or None, optional

If None the result will have no meta. If 'first_found' the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the results meta and if necessary provide a copy. Default is None.

New in version 1.2.

compare_wcscallable, 'first_found' or None, optional

If None the result will have no wcs and no comparison between the wcs of the operands is made. If 'first_found' the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare the wcs. The resulting wcs will be like if False was given otherwise it raises a ValueError if the comparison was not successful. Default is 'first_found'.

New in version 1.2.

uncertainty_correlationnumber or ndarray, optional

The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.

New in version 1.2.

kwargs :

Any other parameter that should be passed to the callables used.

Returns

resultNDData-like

The resulting dataset

Notes

If a callable is used for mask, wcs or meta the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined as kwargs and must start with "wcs_" (for wcs callable) or "meta_" (for meta callable). This startstring is removed before the callable is called.

"first_found" can also be abbreviated with "ff".

classmethod divide(operand, operand2=None, \*\*kwargs)

Performs division by evaluating self / operand.

Parameters

operand, operand2NDData-like instance or convertible to one.

If operand2 is None or not given it will perform the operation self / operand. If operand2 is given it will perform operand / operand2. If the method was called on a class rather than on the instance operand2 must be given.

propagate_uncertaintiesbool or None, optional

If None the result will have no uncertainty. If False the result will have a copied version of the first operand that has an uncertainty. If True the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties are NDUncertainty-like. Default is True.

Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated. None was added as valid parameter value.

handle_maskcallable, 'first_found' or None, optional

If None the result will have no mask. If 'first_found' the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the results mask and if necessary provide a copy. Default is numpy.logical_or.

New in version 1.2.

handle_metacallable, 'first_found' or None, optional

If None the result will have no meta. If 'first_found' the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the results meta and if necessary provide a copy. Default is None.

New in version 1.2.

compare_wcscallable, 'first_found' or None, optional

If None the result will have no wcs and no comparison between the wcs of the operands is made. If 'first_found' the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare the wcs. The resulting wcs will be like if False was given otherwise it raises a ValueError if the comparison was not successful. Default is 'first_found'.

New in version 1.2.

uncertainty_correlationnumber or ndarray, optional

The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.

New in version 1.2.

kwargs :

Any other parameter that should be passed to the callables used.

Returns

resultNDData-like

The resulting dataset

Notes

If a callable is used for mask, wcs or meta the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined as kwargs and must start with "wcs_" (for wcs callable) or "meta_" (for meta callable). This startstring is removed before the callable is called.

"first_found" can also be abbreviated with "ff".

classmethod multiply(operand, operand2=None, \*\*kwargs)

Performs multiplication by evaluating self * operand.

Parameters

operand, operand2NDData-like instance or convertible to one.

If operand2 is None or not given it will perform the operation self * operand. If operand2 is given it will perform operand * operand2. If the method was called on a class rather than on the instance operand2 must be given.

propagate_uncertaintiesbool or None, optional

If None the result will have no uncertainty. If False the result will have a copied version of the first operand that has an uncertainty. If True the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties are NDUncertainty-like. Default is True.

Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated. None was added as valid parameter value.

handle_maskcallable, 'first_found' or None, optional

If None the result will have no mask. If 'first_found' the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the results mask and if necessary provide a copy. Default is numpy.logical_or.

New in version 1.2.

handle_metacallable, 'first_found' or None, optional

If None the result will have no meta. If 'first_found' the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the results meta and if necessary provide a copy. Default is None.

New in version 1.2.

compare_wcscallable, 'first_found' or None, optional

If None the result will have no wcs and no comparison between the wcs of the operands is made. If 'first_found' the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare the wcs. The resulting wcs will be like if False was given otherwise it raises a ValueError if the comparison was not successful. Default is 'first_found'.

New in version 1.2.

uncertainty_correlationnumber or ndarray, optional

The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.

New in version 1.2.

kwargs :

Any other parameter that should be passed to the callables used.

Returns

resultNDData-like

The resulting dataset

Notes

If a callable is used for mask, wcs or meta the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined as kwargs and must start with "wcs_" (for wcs callable) or "meta_" (for meta callable). This startstring is removed before the callable is called.

"first_found" can also be abbreviated with "ff".

new_flux_unit(self, unit, equivalencies=None, suppress_conversion=False)

Converts the flux data to the specified unit. This is an in-place change to the object.

Parameters

unitstr or Unit

The unit to convert the flux array to.

equivalencieslist of equivalencies

Custom equivalencies to apply to conversions. Set to spectral_density by default.

suppress_conversionbool

Set to true if updating the unit without converting data values.

Returns

Spectrum1D

A new spectrum with the converted flux array

classmethod subtract(operand, operand2=None, \*\*kwargs)

Performs subtraction by evaluating self - operand.

Parameters

operand, operand2NDData-like instance or convertible to one.

If operand2 is None or not given it will perform the operation self - operand. If operand2 is given it will perform operand - operand2. If the method was called on a class rather than on the instance operand2 must be given.

propagate_uncertaintiesbool or None, optional

If None the result will have no uncertainty. If False the result will have a copied version of the first operand that has an uncertainty. If True the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties are NDUncertainty-like. Default is True.

Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated. None was added as valid parameter value.

handle_maskcallable, 'first_found' or None, optional

If None the result will have no mask. If 'first_found' the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the results mask and if necessary provide a copy. Default is numpy.logical_or.

New in version 1.2.

handle_metacallable, 'first_found' or None, optional

If None the result will have no meta. If 'first_found' the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the results meta and if necessary provide a copy. Default is None.

New in version 1.2.

compare_wcscallable, 'first_found' or None, optional

If None the result will have no wcs and no comparison between the wcs of the operands is made. If 'first_found' the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare the wcs. The resulting wcs will be like if False was given otherwise it raises a ValueError if the comparison was not successful. Default is 'first_found'.

New in version 1.2.

uncertainty_correlationnumber or ndarray, optional

The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.

New in version 1.2.

kwargs :

Any other parameter that should be passed to the callables used.

Returns

resultNDData-like

The resulting dataset

Notes

If a callable is used for mask, wcs or meta the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined as kwargs and must start with "wcs_" (for wcs callable) or "meta_" (for meta callable). This startstring is removed before the callable is called.

"first_found" can also be abbreviated with "ff".

with_spectral_unit(self, unit, velocity_convention=None, rest_value=None)

Returns a new spectrum with a different spectral axis unit.

Parameters

unitUnit

Any valid spectral unit: velocity, (wave)length, or frequency. Only vacuum units are supported.

velocity_convention‘relativistic’, ‘radio’, or ‘optical’

The velocity convention to use for the output velocity axis. Required if the output type is velocity. This can be either one of the above strings, or an astropy.units equivalency.

rest_valueQuantity

A rest wavelength or frequency with appropriate units. Required if output type is velocity. The spectrum’s WCS should include this already if the input type is velocity, but the WCS’s rest wavelength/frequency can be overridden with this parameter.

with_velocity_convention(self, velocity_convention)