mangadap.proc.spectralindices module¶
A class hierarchy that performs the spectral-index measurements.
- License:
- Copyright (c) 2015, SDSS-IV/MaNGA Pipeline Group
- Licensed under BSD 3-clause license - see LICENSE.rst
- Source location:
- $MANGADAP_DIR/python/mangadap/proc/spectralindices.py
- Class usage examples:
- Add examples!
Notes:
- If neither stellar-continuum nor emission-line models are provided:
- Indices are measure on the binned spectra
- No velocity-dispersion corrections are calculated
If a stellar-continuum model is provided without an emission-line model:
- Indices are measured on the binned spectra
- Velocity-dispersion corrections are computed for any binned spectrum with a stellar-continuum fit based on the optimal template
If an emission-line model is provided without a stellar-continuum model:
- Indices are measured on the relevant (binned or unbinned) spectra; spectra with emission-line fits have the model emission lines subtracted from them before these measurements.
- If the emission-line model includes data regarding the stellar-continuum fit (template spectra and template weights), corrections are calculated for spectra with emission-line models based on the continuum fits; otherwise, no corrections are calculated.
If both stellar-continuum and emission-line models are provided, and if the stellar-continuum and emission-line fits are performed on the same spectra:
- Indices are measured on the relevant (binned or unbinned) spectra; spectra with emission-line fits have the model emission lines subtracted from them before these measurements.
- Velocity-dispersion corrections are based on the stellar-continuum templates and weights
If both stellar-continuum and emission-line models are provided, and if the stellar-continuum and emission-line fits are performed on different spectra:
- The behavior is exactly as if the stellar-continuum model was not provided.
- Revision history:
- 20 Apr 2016: Implementation begun by K. Westfall (KBW)09 May 2016: (KBW) Add subtraction of emission-line models11 Jul 2016: (KBW) Allow to not apply dispersion corrections for index measurements28 Jul 2016: (KBW) Fixed error in initialization of guess redshift when stellar continuum is provided.23 Feb 2017: (KBW) Use DAPFitsUtil read and write functions.27 Feb 2017: (KBW) Use DefaultConfig02 Feb 2018: (KBW) Allow for stellar-continuum and emission-line models to be performed on different spectra (i.e., allow for the hybrid binning scheme). Adjust for change to
mangadap.proc.stellarcontinuummodel.StellarContinuumModel.fill_to_match()
.15 Mar 2018: (KBW) Correct the indices measured in angstroms for redshift. Keep the indices as measured by the best-fitting model.
-
class
mangadap.proc.spectralindices.
AbsorptionLineIndices
(wave, flux, bluebands, redbands, mainbands, err=None, log=True, units=None, weighted_center=True)[source]¶ Bases:
object
Measure a set of spectral indices in a single spectrum.
By default, the center of the two side-bands is the flux-weighted center; set weighted_center=False to get use the unweighted center of the band.
-
class
mangadap.proc.spectralindices.
BandheadIndices
(wave, flux, bluebands, redbands, err=None, log=True, order=None)[source]¶ Bases:
object
Measure a set of bandhead indices in a single spectrum.
-
class
mangadap.proc.spectralindices.
SpectralIndices
(database_key, binned_spectra, redshift=None, stellar_continuum=None, emission_line_model=None, database_list=None, artifact_list=None, absorption_index_list=None, bandhead_index_list=None, dapsrc=None, dapver=None, analysis_path=None, directory_path=None, output_file=None, hardcopy=True, tpl_symlink_dir=None, clobber=False, checksum=False, loggers=None, quiet=False)[source]¶ Bases:
object
Class that computes and interfaces with the spectral-index measurements.
- If neither stellar-continuum nor emission-line models are provided:
- Indices are measure on the binned spectra
- No velocity-dispersion corrections are calculated
If a stellar-continuum model is provided without an emission-line model:
- Indices are measured on the binned spectra
- Velocity-dispersion corrections are computed for any binned spectrum with a stellar-continuum fit based on the optimal template
If an emission-line model is provided without a stellar-continuum model:
- Indices are measured on the relevant (binned or unbinned) spectra; spectra with emission-line fits have the model emission lines subtracted from them before these measurements.
- If the emission-line model includes data regarding the stellar-continuum fit (template spectra and template weights), corrections are calculated for spectra with emission-line models based on the continuum fits; otherwise, no corrections are calculated.
If both stellar-continuum and emission-line models are provided, and if the stellar-continuum and emission-line fits are performed on the same spectra:
- Indices are measured on the relevant (binned or unbinned) spectra; spectra with emission-line fits have the model emission lines subtracted from them before these measurements.
- Velocity-dispersion corrections are based on the stellar-continuum templates and weights
If both stellar-continuum and emission-line models are provided, and if the stellar-continuum and emission-line fits are performed on different spectra:
- The behavior is exactly as if the stellar-continuum model was not provided.
Detail what should be provided in terms of the redshift
Parameters: - database_key (str) – Keyword used to select the specfic list of
indices to measure and how they should be measured; see
SpectralIndicesDef
. - binned_spectra – (
mangadap.proc.spatiallybinnedspectra.SpatiallyBinnedSpectra
): The binned spectra for the measurements. - redshift (float, numpy.ndarray) – (Optional) A single or spectrum-dependent redshift, \(z\), to use for shifting the index bands. Default is to measure the indices at their provided wavelengths (i.e., \(z=0\)).
- stellar_continuum – (
mangadap.proc.stellarcontinuummodel.StellarContinuumModel
): (Optional) The stellar-continuum model as applied to the binned spectra. - emission_line_model – (
mangadap.proc.emissionlinemodel.EmissionLineModel
): (Optional) The emission-line model as applied to either the binned spectra or the unbinned spaxels. - database_list (list) – (Optional) List of
SpectralIndicesDef
objects that define one or more methods to use for the spectral-index measurements. The default list is provided by the config files in the DAP source directory and compiled into this list usingavailable_spectral_index_databases()
. - artifact_list (list) – (Optional) List of
mangadap.par.spectralfeaturedb.SpectralFeatureDBDef
objects that define the unique key for the artifact database (seemangadap.par.artifactdb
). - absorption_index_list (list) – (Optional) List of
mangadap.par.spectralfeaturedb.SpectralFeatureDBDef
objects that define the unique key for the absorption-index database (seemangadap.par.absorptionindexdb
). - bandhead_index_list (list) – (Optional) List of
mangadap.par.spectralfeaturedb.SpectralFeatureDBDef
objects that define the unique key for the bandhead-index database (seemangadap.par.bandheadindexdb
). - dapsrc (str) – (Optional) Root path to the DAP source
directory. If not provided, the default is defined by
mangadap.config.defaults.dap_source_dir()
. - dapver (str) – (Optional) The DAP version to use for the
analysis, used to override the default defined by
mangadap.config.defaults.default_dap_version()
. - analysis_path (str) – (Optional) The top-level path for the
DAP output files, used to override the default defined by
mangadap.config.defaults.default_analysis_path()
. - directory_path (str) – The exact path to the directory with DAP
output that is common to number DAP “methods”. See
directory_path
. - output_file (str) – (Optional) Exact name for the output
file. The default is to use
mangadap.config.defaults.default_dap_file_name()
. - hardcopy (bool) – (Optional) Flag to write the HDUList attribute to disk. Default is True; if False, the HDUList is only kept in memory and would have to be reconstructed.
- tpl_symlink_dir (str) – (Optional) Create a symbolic link to the created template library file in the supplied directory. Default is to produce no symbolic link.
- clobber (bool) – (Optional) Overwrite any existing files. Default is to use any existing file instead of redoing the analysis and overwriting the existing output.
- checksum (bool) – (Optional) Use the checksum in the fits header to confirm that the data has not been corrupted. The checksum is always written to the fits header when the file is created; this argument does not toggle that functionality.
- loggers (list) – (Optional) List of `logging.Logger`_ objects
to log progress; ignored if quiet=True. Logging is done
using
mangadap.util.log.log_output()
. Default is no logging. - quiet (bool) – (Optional) Suppress all terminal and logging output. Default is False.
-
_assign_image_arrays
()[source]¶ Set
image_arrays
, which contains the list of extensions inhdu
that are on-sky image data.
-
_assign_redshifts
(redshift, measure_on_unbinned_spaxels, good_snr, default_redshift=None)[source]¶ Set the redshift to use for each spectrum for the spectral index measurements.
In terms of precedence, directly provided redshifts override those in any available StellarContinuumModel.
If self.stellar_continuum and redshift are None, the default redshift is used (or 0.0 if this is also None).
To get the stellar kinematics, the function calls
mangadap.proc.stellarcontinuummodel.StellarContinuumModel.matched_kinematics()
. It is expected that the stellar kinematics were fixed to these values during any emission-line modeling that may have altered the continuum fit itself (e.g.,mangadap.proc.Sasuke
).In this function, the provided redshift must be a single value or None; therefore, the means of any vectors should be provided instead of the full vector.
The function is borrows heavily from
mangadap.proc.emissionlinemodel.EmissionLineModel._assign_input_kinematics()
.Parameters: - redshift (float, numpy.ndarray) – Redshifts (\(z\)) to use for each spectrum. If None, the default
- default_redshift (float) – (Optional) Only used if there
are stellar kinematics available. Provides the default
redshift to use for spectra without stellar
measurements; see :arg:`redshift` in
mangadap.proc.stellarcontinuummodel.StellarContinuumModel.matched_kinematics()
. If None (default), the median of the unmasked stellar velocities will be used.
-
_define_databases
(database_key, database_list=None, artifact_list=None, absorption_index_list=None, bandhead_index_list=None, dapsrc=None)[source]¶ Select the database of indices
-
_index_database_dtype
(name_len)[source]¶ Construct the record array data type for the output fits extension.
-
_initialize_primary_header
(hdr=None, measurements_binid=None)[source]¶ Initialize the header of
hdu
.Returns: Edited header object. Return type: astropy.io.fits.Header
-
_resolution_matched_templates
(dapsrc=None, dapver=None, analysis_path=None, tpl_symlink_dir=None)[source]¶ Get a version of the template library that has had its resolution matched to that of the spectral-index database.
-
_set_paths
(directory_path, dapver, analysis_path, output_file)[source]¶ Set the
directory_path
andoutput_file
. If not provided, the defaults are set using, respectively,mangadap.config.defaults.default_dap_common_path()
andmangadap.config.defaults.default_dap_file_name()
.Parameters: - directory_path (str) – The exact path to the DAP
spectral-index file. See
directory_path
. - dapver (str) – DAP version.
- analysis_path (str) – The path to the top-level directory containing the DAP output files for a given DRP and DAP version.
- output_file (str) – The name of the file with spectral-index
moment measurements. See
measure()
.
- directory_path (str) – The exact path to the DAP
spectral-index file. See
-
static
adjust_spectral_resolution
(wave, flux, ivar, sres, resolution_fwhm)[source]¶ flux and ivar are expected to be masked arrays
-
static
apply_dispersion_corrections
(indx, indxcorr, err=None, unit=None)[source]¶ Apply a set of dispersion corrections. Errors in the dispersion corrections are assumed to be negligible.
Parameters: - indx (array-like) – Indices to correct.
- indxcorr (array-like) – Index corrections.
- err (array-like) – (Optional) Error in the indices.
- unit (str) – (Optional) Unit of the index; must be either magnitudes (mag) or angstroms (ang) or None. Default is None. Unitless corrections and angstrom corrections are treated identically.
Returns: The corrected indices and errors are returned. If no errors are returned, the second returned object is None.
Return type: numpy.ndarray
Raises: ValueError
– Raised if the unit is not ang or mag.
-
static
calculate_dispersion_corrections
(absdb, bhddb, wave, flux, continuum, continuum_dcnvlv, redshift=None, redshift_dcnvlv=None, bitmask=None)[source]¶ Calculate the dispersion corrections using the best-fitting template models.
Allow the “deconvolved” continuum spectra to be at a different redshift than the best-fitting continuum.
-
static
count_indices
(absdb, bhddb)[source]¶ Count the total number (absorption-line and bandhead) indices.
-
measure
(binned_spectra, redshift=None, stellar_continuum=None, emission_line_model=None, dapsrc=None, dapver=None, analysis_path=None, directory_path=None, output_file=None, hardcopy=True, tpl_symlink_dir=None, clobber=False, loggers=None, quiet=False)[source]¶ Measure the spectral indices using the binned spectra and the internal spectral index database, and construct the internal data structure.
If neither stellar-continuum nor emission-line models are provided:
- Indices are measure on the binned spectra
- No velocity-dispersion corrections are calculated
If a stellar-continuum model is provided without an emission-line model:
- Indices are measured on the binned spectra
- Velocity-dispersion corrections are computed for any binned spectrum with a stellar-continuum fit based on the optimal template
If an emission-line model is provided without a stellar-continuum model:
- Indices are measured on the relevant (binned or unbinned) spectra; spectra with emission-line fits have the model emission lines subtracted from them before these measurements.
- If the emission-line model includes data regarding the stellar-continuum fit (template spectra and template weights), corrections are calculated for spectra with emission-line models based on the continuum fits; otherwise, no corrections are calculated.
If both stellar-continuum and emission-line models are provided, and if the stellar-continuum and emission-line fits are performed on the same spectra:
- Indices are measured on the relevant (binned or unbinned) spectra; spectra with emission-line fits have the model emission lines subtracted from them before these measurements.
- Velocity-dispersion corrections are based on the stellar-continuum templates and weights
If both stellar-continuum and emission-line models are provided, and if the stellar-continuum and emission-line fits are performed on different spectra:
- The behavior is exactly as if the stellar-continuum model was not provided.
Parameters: - binned_spectra – (
mangadap.proc.spatiallybinnedspectra.SpatiallyBinnedSpectra
): The binned spectra for the measurements. - redshift (float, numpy.ndarray) –
(Optional) A single or spectrum-dependent redshift, \(z\), to use for shifting the index bands. Default is to measure the indices at their provided wavelengths (i.e.,
\(z=0\)). If providing spectrum-dependent values, the number of values must be the same as the number of stpectrum bins (i.e., binned_spectra.nbins) if either the emission-line model is not provided or it was not determined by deconstructing the bins; the number of values must be the same as the number of DRP spectra if the opposite is true (an emission-line model is provided that deconstructed the bins for its fit).
- stellar_continuum – (
mangadap.proc.stellarcontinuummodel.StellarContinuumModel
): (Optional) The stellar-continuum model as applied to the binned spectra. - emission_line_model – (
mangadap.proc.emissionlinemodel.EmissionLineModel
): (Optional) The emission-line model as applied to either the binned spectra or the unbinned spaxels. - dapsrc (str) – (Optional) Root path to the DAP source
directory. If not provided, the default is defined by
mangadap.config.defaults.dap_source_dir()
. - dapver (str) – (Optional) The DAP version to use for the
analysis, used to override the default defined by
mangadap.config.defaults.default_dap_version()
. - analysis_path (str) – (Optional) The top-level path for
the DAP output files, used to override the default
defined by
mangadap.config.defaults.default_analysis_path()
. - directory_path (str) – The exact path to the directory with
DAP output that is common to number DAP “methods”. See
directory_path
. - output_file (str) – (Optional) Exact name for the output
file. The default is to use
mangadap.config.defaults.default_dap_file_name()
. - hardcopy (bool) – (Optional) Flag to write the HDUList attribute to disk. Default is True; if False, the HDUList is only kept in memory and would have to be reconstructed.
- tpl_symlink_dir (str) – (Optional) Create a symbolic link to the created template library file in the supplied directory. Default is to produce no symbolic link.
- clobber (bool) – (Optional) Overwrite any existing files. Default is to use any existing file instead of redoing the analysis and overwriting the existing output.
- loggers (list) – (Optional) List of `logging.Logger`_
objects to log progress; ignored if quiet=True. Logging
is done using
mangadap.util.log.log_output()
. Default is no logging. - quiet (bool) – (Optional) Suppress all terminal and logging output. Default is False.
-
static
measure_indices
(absdb, bhddb, wave, flux, ivar=None, mask=None, redshift=None, bitmask=None)[source]¶ Measure the spectral indices in a set of spectra.
Parameters: - absdb – (
mangadap.par.aborptionlinedb.AbsorptionIndexDB
): Database with the absorption-line index definitions. Can be None. - bhddb – (
mangadap.par.bandheadindexdb.BandheadIndexDB
): Database with the bandhead index definitions. - wave (array-like) – 1D vector with the wavelength of each pixel. Assumed to be logarithmically binned in radius.
- flux (array-like) – 2D array with the flux, ordered as \(N_{\rm spec}\times N_{\rm wave}\). Can be a numpy.ma.MaskedArray; masked pixels will be ignored in the measurement.
- ivar (array-like) – (Optional) Inverse variance in the flux. Must match flux array shape. Used to calculate propagated errors in the index. Default is that errors are ignored.
- mask (array-like) – (Optional) Boolean array flagging to ignore (mask=True) or include (mask=False) each flux measurement in the index calculation.
- redshift (array-like) – (Optional) Redshift to use for each spectrum when determining the index. Must have the correct length compared to the flux array. Default is to assume the spectra are at rest wavelength.
- bitmask (
mangadap.util.bitmask.BitMask
) – (Optional) If an index is flagged for some reason (seeset_masks()
), this object is used to set the mask value; this should typically beSpectralIndicesBitMask
object. If not provided, the masked values are all set to True (False otherwise).
Returns: A record array with the following columns, each with one element per spectrum:
BINID
: Bin identifierBINID_INDEX
: Index of the bin identifierREDSHIFT
: Redshift used for measurementMASK
: Boolean or maskbit value for indexBCEN
: Blue passband centerBCONT
: Blue passband pseudo-continuumBCONTERR
: Error in the aboveRCEN
: Red passband centerRCONT
: Red passband pseudo-continuumRCONTERR
: Error in the above
INDX
: Index valueINDXERR
: Error in the aboveMODEL_INDX
: Index measured on the best-fitting- stellar-continuum model
INDX_DISPCORR
: Index dispersion correction
This function does not add the
BINID
,BINID_INDEX
, orINDX_DISPCORR
values. Each element in columns 3-12 are vectors with a length of \(N_{\rm index}\) — the total number of indices calcualte (seecount_indices()
).Return type: - absdb – (
-
static
output_dtype
(nindx, bitmask=None)[source]¶ Construct the record array data type for the output fits extension.
-
read
(ifile=None, strict=True, checksum=False)[source]¶ Read an existing file with a previously binned set of spectra.
-
static
set_masks
(measurements, blue_incomplete, blue_empty, red_incomplete, red_empty, divbyzero, main_incomplete=None, main_empty=None, bitmask=None)[source]¶
-
static
spectra_for_index_measurements
(binned_spectra, measure_on_unbinned_spaxels=False, pixelmask=None, select=None, resolution_fwhm=None, emission_line_model=None)[source]¶ Compile the set of spectra for the spectral-index measurements.
If the input fwhm is > 0, this function will match the spectral resolution of the data to the spectral-index system, based on the provided FWHM. It also subtracts the emission-line model if provided.
Todo
Allow resolution_fwhm to be wavelength dependent, provided via a vector.
Parameters: - binned_spectra – (
mangadap.proc.spatiallybinnedspectra.SpatiallyBinnedSpectra
): The binned spectra object. The returned spectra are either the binned spectra or the DRP spectra internal to this object. - measure_on_unbinned_spaxels (bool) – (Optional) Flag to return the unbinned spaxels as opposed to the binned spectra. Default is to use the binned spectra.
- pixelmask – (
mangadap.util.pixelmask.SpectralPixelMask
): (Optional) Defines the pixels that should automatically be masked during the measurements. By default, nothing is masked in addition to that specified by the data mask. - select (numpy.ndarray) – (Optional) Boolean vector selecting which spectra to return. The length must match the number of binned spectra or the total number of DRP spectra, depending on the provided :arg:`measure_on_unbinned_spaxels`. Default is to return all spectra.
- resolution_fwhm (float) – (Optional) Wavelength-independent FWHM of the resolution element at which to measure the indices. If > 0, the spectra are resolution matched from the input resolution to the provided resolution; otherwise, the resolution is not altered.
- emission_line_model – (
mangadap.proc.emissionlinemodel.EmissionLineModel
): (Optional) Object providing the emission-line model. The emission-line model must match the selection of the spectra (binned or unbinned) to fit, as given by the fitting method (deconstruct_bins).
Returns: Three arrays are returned: (1) the common wavelength vector, (2) the masked flux array, and (3) the masked inverse variance array.
Return type: numpy.ndarray, numpy.ma.MaskedArray
Raises: ValueError
– Raised if the emission-line model and spectra selection (binned vs. unbinned) do not match.- binned_spectra – (
-
class
mangadap.proc.spectralindices.
SpectralIndicesBitMask
(dapsrc=None)[source]¶ Bases:
mangadap.util.bitmask.BitMask
Derived class that specifies the mask bits for the spectral-index measurements. See
mangadap.util.bitmask.BitMask
for attributes.A list of the bits and meanings are provided by the base class function
mangadap.util.bitmask.BitMask.info()
; i.e.,:from mangadap.proc.spectralindices import SpectralIndicesBitMask bm = SpectralIndicesBitMask() bm.info()
-
class
mangadap.proc.spectralindices.
SpectralIndicesDef
(key, minimum_snr, fwhm, compute_corrections, artifacts, absindex, bandhead)[source]¶ Bases:
mangadap.par.parset.ParSet
A class that holds the parameters necessary to perform the spectral-index measurements.
Parameters: - key (str) – Keyword used to distinguish between different spectral-index databases.
- minimum_snr (bool) – Minimum S/N of spectrum to fit
- fwhm (int, float) – Resolution FWHM in angstroms at which to make the measurements.
- compute_corrections (bool) – Flag to compute dispersion corrections to indices. Dispersion corrections are always calculated!
- artifacts (str) – String identifying the artifact database to use
- absindex (str) – String identifying the absorption-index database to use
- bandhead (str) – String identifying the bandhead-index database to use
-
mangadap.proc.spectralindices.
available_spectral_index_databases
(dapsrc=None)[source]¶ Return the list of available spectral index databases
Available database combinations:
Todo
Fill in
Parameters: dapsrc (str) – (Optional) Root path to the DAP source directory. If not provided, the default is defined by
mangadap.config.defaults.dap_source_dir()
.Returns: A list of
SpectralIndicesDef()
objects, each defining a spectral-index database to measure.Return type: list
Raises: NotADirectoryError
– Raised if the provided or default dapsrc is not a directory.OSError/IOError
– Raised if no spectral-index configuration files could be found.KeyError
– Raised if the spectral-index database keywords are not all unique.
Todo
- Somehow add a python call that reads the databases and constructs the table for presentation in sphinx so that the text above doesn’t have to be edited with changes in the available databases.
-
mangadap.proc.spectralindices.
validate_spectral_indices_config
(cnfg)[source]¶ Validate
mangadap.util.parser.DefaultConfig
object with spectral-index measurement parameters.Parameters: cnfg (
mangadap.util.parser.DefaultConfig
) – Object with parameters to validate.Raises: KeyError
– Raised if any required keywords do not exist.ValueError
– Raised if keys have unacceptable values.FileNotFoundError
– Raised if a file is specified but could not be found.