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 arithmetic

01 Dec 2016: (KBW) Allow stacking the spectral resolution to be turned off via SpectralStackPar.

06 Dec 2016: (KBW) In mangadap.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 like mangadap.proc.spatiallybinnedspectra.SpatiallyBinnedSpectra to keep track of missing bins.

30 Aug 2017: (KBW) Switch from mangadap.util.instrument.resample_vector() to mangadap.util.instrument.resample1d() in untested function SpectralStack.register().

30 Aug 2018: (KBW) Switch from resample1d to mangadap.util.sampling.Resample()

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

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.

static _get_input_mask(flux, ivar=None, mask=None, dtype=<class 'bool'>)[source]¶

_get_stack_mean()[source]¶: Return the mean of the stacked spectra using the internal data.

_recalibrate_ivar_figure(ratio, ofile=None)[source]¶

_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 build_covariance_data_DRPFits(drpf, covariance_mode, covariance_par)[source]¶

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 to stack().

wavelengths: Functionally equivalent to channels; however, the channels to use is set by a list of provided wavelengths. The covariance matrix must be provided to stack().

approx_correlation: Approximate the covariance matrix using a Gaussian description of the correlation between pixels. See mangadap.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 to stack().

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 to stack().

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 (array-like) – Original wavelengths. Should be 1D. voff (float, array-like) – 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 spectra

sum: 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.

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, array-like) – The velocity shift in km/s to apply to the wavelength vector (i.e., the velocity shift should be \(v_{\rm off} = -cz\). de-redshift). 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 one-dimensional, if the flux array is not two-dimensional, 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. See `operation_options()`. Default is `mean`. 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; see `covariance_mode_options()`. Default is to ignore covariance. covar (`float`, `Covariance`, optional) – Covariance object to use, which must match the expectation from the covariance mode. See `covariance_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 one-dimensional, if the flux array is not two-dimensional, 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; see `covariance_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`

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 pre-pixelized 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