mangadap.proc.spectralstack module¶
Stack some spectra!
Revision history¶
01 Apr 2016: Implementation begun by K. Westfall (KBW)10 Nov 2016: (KBW) Include dispersion cube in DRP file to construct spectral resolution of binned spectra.30 Nov 2016: (KBW) Use, e.g., [None,:] slicing instead of, e.g., numpy.array([v]*n) when necessary for array arithmetic01 Dec 2016: (KBW) Allow stacking the spectral resolution to be turned off viaSpectralStackPar
.06 Dec 2016: (KBW) Inmangadap.proc.spectralstack.SpectralStack._set_rebin_transfer_matrix()
, the number of bins is set by the number of unique indices; before based on the maximum unique index, meaning that “missing” bins were included. They’re now excluded, forcing classes likemangadap.proc.spatiallybinnedspectra.SpatiallyBinnedSpectra
to keep track of missing bins.30 Aug 2017: (KBW) Switch frommangadap.util.instrument.resample_vector()
tomangadap.util.instrument.resample1d()
in untested functionSpectralStack.register()
.30 Aug 2018: (KBW) Switch from resample1d tomangadap.util.sampling.Resample()
Copyright © 2019, SDSSIV/MaNGA Pipeline Group

class
mangadap.proc.spectralstack.
SpectralStack
[source]¶ Bases:
object
Class whose primary function is to stack a set of spectra while treating covariance between spectra.
See
covariance_mode_options()
for available methods of accounting for covariance.Class also approximates the resulting spectral resolution of the stacked data.

static
_check_covariance_shape
(covariance_mode, covar, nwave, nspec)[source]¶ Check that the input covariance object has the correct shape for the given mode.
Args:

static
_check_covariance_type
(covariance_mode, covar, ivar)[source]¶ Check that the covariance variable has the correct type for the given mode.
Parameters:  covariance_mode (str) – Covariance handling mode; see
covariance_mode_options()
.  (None, float, (covar) –
mangadap.util.covariance.Covariance
): The object to check the type against the covariance handling mode.
Returns: Flag that type is correct.
Return type: bool
 covariance_mode (str) – Covariance handling mode; see

static
_check_input_sres
(sres, nspec)[source]¶ Check the shape and type of the input spectral resolution.
If the input is a masked array, interpolate over the mask. Always returns a numpy.ndarray (unmasked).

_covar_in_mean
()[source]¶ Compute the covariance in the mean spectrum by propagating the division by the number of pixels through the covariance matrix.

_set_rebin_transfer_matrix
(binid, binwgt=None)[source]¶ Construct the transfer matrix that rebins the spectra. The output shape is \((N_{\rm bin} \times N_{\rm spec})\) with the expectation that the spectrum flux array has shape \((N_{\rm spec} \times N_{\rm wave})\). The binned spectra are calculated by matrix multiplication, \(\mathbf{B} = \mathbf{T} \times \mathbf{F}\) such that the covariance matrix can be calculated as \(\mathbf{C} = \mathbf{T} \times \mathbf{\Sigma} \times \mathbf{T}^{\rm T}\), where \(\mathbf{\Sigma}\) is the covariance matrix in the flux array, \(\mathbf{F}\).
If weighting, the sum of the weights is normalized to the number of points included in the bin.
Parameters:  binid (numpy.ndarray) – List if indices, one per spectrum in the flux array, for the binned spectrum. Indices of less than one are ignored.
 binwgt (numpy.ndarray) – (Optional) List of weights for the spectra. If not provided, the weights are uniform.

_stack_with_covariance
(flux, covariance_mode, covar, ivar=None, sres=None)[source]¶ Stack the spectra and incorporate covariance.
ivar must not be none if covariance_mode is channels or wavelengths
Size has to match self.rebin_T

_stack_without_covariance
(flux, ivar=None, sres=None)[source]¶ Stack the spectra, ignoring any covariance that may or may not exist.
Sets
flux
,fluxsqr
,npix
,ivar
,sres
.The stored data is always based on the SUM of the spectra in the stack.
Parameters:  flux (numpy.ma.MaskedArray) – Flux array.
 ivar (
numpy.ma.MaskedArray
, optional) – The inverse variance array.  sres (
numpy.ma.MaskedArray
, optional) – 1D or 2D spectral resolution as a function of wavelength for all or each input spectrum. Default is to ignore any spectral resolution data.

static
covariance_mode_options
(par_needed=False)[source]¶ Accounting for covariance: The two parameters covar_mode and covar_par set how covariance is accounted for in the stacking procedure. The valid options are:
none
: The noise in the stacked spectrum is a nominal propagation of the error assuming no covariance. No parameters needed.calibrate
: The spectral noise is calibrated following:\[n_{\rm calib} = n_{\rm nominal} (1 + \alpha \log\ N_{\rm bin})\]where \(N_{\rm bin}\) is the number of binned spaxels. The value of \(\alpha\) must be provided as a parameter.
channels
: The noise vector of each stacked spectrum is adjusted based on the mean ratio of the nominal and formally correct calculations of the noise measurements over a number of spectral channels. The channels are drawn from across the full spectral range. The number of channels to use is a defined parameter. The covariance matrix must be provided tostack()
.wavelengths
: Functionally equivalent tochannels
; however, the channels to use is set by a list of provided wavelengths. The covariance matrix must be provided tostack()
.approx_correlation
: Approximate the covariance matrix using a Gaussian description of the correlation between pixels. Seemangadap.drpfits.DRPFits.covariance_matrix()
. The value of \(\sigma\) provides for the Gaussian desciption of \(\rho_{ij}\) in the correlation matrix. The covariance matrix must be provided tostack()
.full
: The full covariance cube is calculated and the noise vectors are constructed using the formally correct calculation. No parameters needed. The covariance matrix must be provided tostack()
.Returns: List of the allowed modes. Return type: list

static
min_max_wave
(wave, voff)[source]¶ Determine the minimum and maximum of all shifted wavelength ranges.
Parameters:  wave (arraylike) – Original wavelengths. Should be 1D.
 voff (float, arraylike) – The velocity shift in km/s to apply to the wavelength vector (i.e., the velocity shift should be \(v_{\rm off} = cz\)). Each element is applied to the wavelength vector to determine the maximum wavelength range allowed for all spectra. Should be 1D.
Returns: Two floats with the minimum and maximum redshifted wavelengths.
Return type: float

static
operation_options
()[source]¶ Return the allowed stacking operations. Current operations are:
mean
: Construct the mean of the spectrasum
: Construct the spectrum sum.Returns: List of available operations. Return type: list

static
parse_covariance_parameters
(mode, par)[source]¶ Parse the parameters needed for the treatment of the covariance when stacking spectra.
Parameters:  mode (str) – Mode to use. Must be an allowed mode; see
covariance_mode_options()
.  par (str) – String representation of the parameters for the specified mode.
Returns: Parameters parsed from the input string for the designated covariance mode.
Return type: float or list
Raises: TypeError
– Raised if the input parameter could not be converted to a float as needed by the specified mode.ValueError
– Raised if the mode is not recognized.
 mode (str) – Mode to use. Must be an allowed mode; see

static
register
(wave, voff, flux, ivar=None, mask=None, sres=None, log=False, base=10.0, keep_range=False, flim=0.5)[source]¶ Register a set of spectra to the same wavelength range given a set of velocity offsets.
Warning
THIS FUNCTION IS UNTESTED!
Todo
 Allow for correction for deredshifting flux.
Parameters:  wave (numpy.ndarray) – Single wavelength vector for all input spectra. Must be 1D with shape \((N_{\rm wave},)\).
 voff (float, arraylike) – The velocity shift in km/s to apply to the wavelength vector (i.e., the velocity shift should be \(v_{\rm off} = cz\). deredshift). Should be 1D at most.
 flux (numpy.ndarray) – Flux array to register. Must be 2D with shape \((N_{\rm spec},N_{\rm wave})\). Can be a masked array.
 ivar (numpy.ndarray, optional) – Inverse variance in the spectrum fluxes. Shape must match flux. Can be a masked array.
 mask (numpy.ndarray, optional) – Boolean array with values in flux to mask. Default assumes nothing is masked. If flux and/or ivar are masked array, this is included in union with those masks.
 sres (numpy.ndarray, optional) – 1D or 2D spectral resolution as a function of wavelength for all or each input spectrum. Default is to ignore any spectral resolution data. If a masked array, the masked pixels are interpolated.
 log (bool, optional) – Flag that the wavelength vector is geometrically sampled in wavelength.
 base (float, optional) – If the wavelength vector is geometrically stepped, this is the base of the logarithmic step. Default is 10.0.
 keep_range (float, optional) – When registering the wavelengths of the shifted spectra, keep the identical spectral range as input.
 flim (float, optional) – Mask any pixels in the output flux arrays that are covered by less than this fraction by the input masked flux array.
Returns: Returns four arrays: (1) the new wavelength vector, common to all spectra; (2) the new masked flux array; (3) the new masked inverse variance array, which will be None if no inverse variances are provided to the function; and (4) the new spectral resolution vectors, which will also be None if no spectral resolution vectors are provided.
Return type: numpy.ndarray, numpy.ma.MaskedArray
Raises: ValueError
– Raised if the wavelength or velocity offset vectors are not onedimensional, if the flux array is not twodimensional, if the inverse variance or mask arrays do not have the same shape as the flux array, or if the number of wavelengths does not match the second axis of the flux array.

stack
(wave, flux, operation='mean', binid=None, binwgt=None, ivar=None, mask=None, sres=None, voff=None, log=False, base=10.0, covariance_mode=None, covar=None, keep_range=False, fill_sres=True)[source]¶ Stack a set of spectra. If binid is None, all the spectra in the array are stacked into a single output spectrum.
Register a set of spectra to the same wavelength range given a set of velocity offsets.
The internal attributes are always kept as the sum, not the mean, of the spectra.
Parameters:  wave (numpy.ndarray) – Single wavelength vector for all input spectra.
 flux (numpy.ndarray) – Spectrum flux values. Can be a masked array.
 operation (
str
, optional) – Stacking operation to perform. Seeoperation_options()
. Default ismean
.  binid (
numpy.ndarray
, optional) – Indices of the bin in which to place each spectrum. If not provided, all the spectra will be combined.  binwgt (
numpy.ndarray
, optional) – Weights for each of the spectra. If not provided, all weights are uniform.  ivar (
numpy.ndarray
, optional) – Inverse variance in the spectrum fluxes. Can be a masked array.  mask (
numpy.ndarray
, optional) – Binary mask values for the spectrum fluxes; 0 (False) is unmasked, anything else is masked. Default assumes no pixel mask.  sres (
numpy.ndarray
, optional) – 1D or 2D spectral resolution as a function of wavelength for all or each input spectrum. Default is to ignore any spectral resolution data. Can be a masked array.  voff (
numpy.ndarray
, optional) – Vector with velocity offsets to apply to each spectrum. Default is no velocity offsets  log (
bool
, optional) – Flag that the wavelength vector is geometrically stepped in wavelength.  base (
float
, optional) – If the wavelength vector is geometrically stepped, this is the base of the logarithmic step. Default is 10.0.  covariance_mode (
str
, optional) – Keyword for method to use for dealing with covariance; seecovariance_mode_options()
. Default is to ignore covariance.  covar (
float
,Covariance
, optional) – Covariance object to use, which must match the expectation from the covariance mode. Seecovariance_mode_options()
and_check_covariance_type()
.  keep_range (
float
, optional) – When registering the wavelengths of the shifted spectra, keep the identical spectral range as input.  fill_sres (
bool
, optional) – If the spectral resolution is provided, interpolate the stacked spectral resolution instead of returning a masked array.
Returns: Returns seven objects: the wavelength vector, the stacked flux, the standard deviation in the stacked flux, the number of spectra in each stacked pixel, the stacked inverse variance, the stacked spectral resolution, and the stacked covariance.
Return type: numpy.ndarray, numpy.ma.MaskedArray
Raises: ValueError
– Raised if the wavelength vector is not onedimensional, if the flux array is not twodimensional, if the inverse variance or mask arrays do not have the same shape as the flux array, or if the number of wavelengths does not match the second axis of the flux array. Also raised if the covariance mode is not recognized; seecovariance_mode_options()
.

stack_DRPFits
(drpf, binid, par=None)[source]¶ Wrapper function for
stack()
that uses a DRPFits file.Parameters: par (ParSet or dict) – (Optional) Set of parameters used to define how the stack the spectra. See stack()
. Does not need to be provided on initialization, but a parameter set is required for all the stacking routines.Returns: Returns six elements. See stack()
.Return type: numpy.ndarray, mangadap.util.covariance.Covariance

static

class
mangadap.proc.spectralstack.
SpectralStackPar
(operation=None, vel_register=None, vel_offsets=None, covar_mode=None, covar_par=None, stack_sres=None, prepixel_sres=None)[source]¶ Bases:
mangadap.par.parset.KeywordParSet
Class with parameters used to set how to stack a set of spectra. See
mangadap.par.parset.ParSet
for attributes.Todo
Allow for sigma rejection.
The defined parameters are:
Key Type Options Default Description operation
str mean
,sum
mean
Operation to perform for the stacked spectrum. See SpectralStack.operation_options()
for the available operation options.vel_register
bool False Flag to velocity register the spectra before adding them based on a provided prior measurement of the velocities. vel_offsets
ndarray, list List of velocity offsets to apply to the spectra to stack. covar_mode
str calibrate
,approx_correlation
,channels
,wavelengths
,none
,full
none
Describes how to incorporate covariance into the spectral stacking. See SpectralStack.covariance_mode_options()
for the available options.covar_par
int, float, ndarray, list The parameter(s) needed to perform a given method of handling the covariance. See SpectralStack.covariance_mode_options()
for the available options.stack_sres
bool True Stack the spectral resolution as well as the flux data. prepixel_sres
bool True Use the prepixelized spectral resolution. If true and the prepixelized versions are not available, an error will be raised! 
fromheader
(hdr)[source]¶ Copy the information from the header
hdr (astropy.io.fits.Header): Header object to write to.

toheader
(hdr)[source]¶ Copy the information to a header.
Parameters: hdr (astropy.io.fits.Header) – Header object to write to. Returns: Edited header object. Return type: astropy.io.fits.Header
