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 models
11 Jul 2016: (KBW) Allow to not apply dispersion corrections for index measurements
28 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 DefaultConfig
02 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:
_assign_image_arrays()[source]

Set image_arrays, which contains the list of extensions in hdu 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:
_compile_database()[source]

Compile the database with the specifications of each index.

_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

_flag_good_spectra(measure_on_unbinned_spaxels)[source]
_get_missing_bins(unique_bins=None)[source]
_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 and output_file. If not provided, the defaults are set using, respectively, mangadap.config.defaults.default_dap_common_path() and mangadap.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().
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 check_and_prep_input(wave, flux, ivar=None, mask=None, redshift=None, bitmask=None)[source]
static count_indices(absdb, bhddb)[source]

Count the total number (absorption-line and bandhead) indices.

file_name()[source]

Return the name of the output file.

file_path()[source]

Return the full path to the output file.

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 (see set_masks()), this object is used to set the mask value; this should typically be SpectralIndicesBitMask 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:

  1. BINID: Bin identifier
  2. BINID_INDEX: Index of the bin identifier
  3. REDSHIFT: Redshift used for measurement
  4. MASK: Boolean or maskbit value for index
  5. BCEN: Blue passband center
  6. BCONT: Blue passband pseudo-continuum
  7. BCONTERR: Error in the above
  8. RCEN: Red passband center
  9. RCONT: Red passband pseudo-continuum
  10. RCONTERR: Error in the above
  1. INDX: Index value
  2. INDXERR: Error in the above
  3. MODEL_INDX: Index measured on the best-fitting
    stellar-continuum model
  4. INDX_DISPCORR: Index dispersion correction

This function does not add the BINID, BINID_INDEX, or INDX_DISPCORR values. Each element in columns 3-12 are vectors with a length of \(N_{\rm index}\) — the total number of indices calcualte (see count_indices()).
Return type:

numpy.recarray
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 save_results(results, measurements, good, err=False, bitmask=None)[source]
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.
static unit_selection(absdb, bhddb)[source]

Return boolean arrays selection which indices are unitless, in angstrom units, or in magnitude units.

write(clobber=False)[source]

Write the hdu object to the file.

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.