mangadap.proc.spectralindices module

A class hierarchy that performs the spectral-index measurements.

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.

---

Copyright © 2019, SDSS-IV/MaNGA Pipeline Group

---

class mangadap.proc.spectralindices.AbsorptionLineIndices(wave, flux, bluebands, redbands, mainbands, err=None, log=True, units=None)

Bases: object

Measure a set of absorption-line indices and metrics in a single spectrum.

The calculations performed provide spectral index measurements as defined/used by Worthey et al. (1994) and Trager et al. (1998) (\({\mathcal I}_{\rm WT}\), index), as well as defined/used by Burstein et al. (1984) and Faber et al. (1985) (\({\mathcal I}_{\rm BF}\), index_bf).

Specifically, let

\[S(y) \equiv \int_{\lambda_1}^{\lambda_2} y\ d\lambda \approx \sum_i y_i\ {\rm d}p_i\ {\rm d}\lambda_i,\]

where \({\rm d}p_i\) is the fraction of pixel \(i\) (with width \({\rm d}\lambda_i\)) in the passband defined by \(\lambda_1 < \lambda < \lambda_2\); the discrete sum is performed by mangadap.proc.bandpassfilter.passband_integral(). Also, let \(f\) be the spectrum flux density and define a linear continuum using two sidebands (“blue” and “red”):

\[C(\lambda) = (\langle f\rangle_{\rm red} - \langle f\rangle_{\rm blue})\ \frac{\lambda - \lambda_{\rm blue}}{\lambda_{\rm red}-\lambda_{\rm blue}} + \langle f\rangle_{\rm blue},\]

where \(\lambda_{\rm blue}\) and \(\lambda_{\rm red}\) are the wavelengths at the center of the two sidebands — e.g., \(\lambda_{\rm red} = (\lambda_{1,{\rm red}} + \lambda_{2,{\rm red}})/2\) — and

\[\langle y\rangle = S(y)/S(1).\]

When no pixels are masked in the spectrum, \(S(1) = (\lambda_2 - \lambda_1) \equiv \Delta\lambda\).

Following the Worthey et al. (1994) definition, we can then calculate the absorption-line spectral indices as follows:

\[\begin{split}{\mathcal I}_{\rm WT} = \left\{ \begin{array}{ll} S(1 - f/C), & \mbox{for angstrom units} \\[3pt] -2.5\log\left[\langle f/C\rangle\right], & \mbox{for magnitude units} \end{array}\right..\end{split}\]

The difficulty with the Worthey et al. definitions is that it makes it difficult to construct an aggregate index measurement based on individual index measurements from multiple spectra; however, this is straight-forward under definitions closer to those provided by Burstein et al. (1984) and Faber et al. (1985).

Instead define:

\[\begin{split}{\mathcal I}_{\rm BF} = \left\{ \begin{array}{ll} S(1) - S(f)/C_0, & \mbox{for angstrom units} \\[3pt] -2.5\log\left[\langle f\rangle/C_0\right], & \mbox{for magnitude units} \end{array}\right.,\end{split}\]

where \(C_0\) is the value of the linear continuum at the center of the main passband. Given that the continuum is a linear function, \(S(C) = C_0 \Delta\lambda\); i.e., the integral of the continuum over the passband is mathematically identical to the continuum sampled at the center of the bandpass times the bandpass width.

Now, we can calculate a weighted sum of indices using the value of \(C_0\) for each index as the weight and assume that no pixels are masked such that we can replace \(S(1)\) with \(\Delta\lambda\) to find:

\[\begin{split}\begin{eqnarray} \frac{\sum_i C_{0,i} {\mathcal I}_{\rm BF}}{\sum_i C_{0,i}} & = & \frac{\sum_i C_{0,i} (\Delta\lambda - S(f)_i / C_{0,i})}{\sum_i C_{0,i}} \\ & = & \Delta\lambda - \frac{\sum_i S(f)_i}{\sum_i C_{0,i}} \end{eqnarray}.\end{split}\]

That is, this weighted sum of the individual indices is mathematically identical (to within the limits of how error affects the construction of the linear continuum) to the index measured for the sum (or mean) of the individual spectra. Similarly for the indices in magnitude units:

\[\begin{split}\begin{eqnarray} -2.5\log\left[\frac{\sum_i C_{0,i} 10^{-0.4 {\mathcal I}_{\rm BF}}}{\sum_i C_{0,i}}\right] & = & -2.5\log\left[\frac{\sum_i C_{0,i} (S(f)_i / C_{0,i})} {\Delta\lambda \sum_i C_{0,i}}\right] \\ & = & -2.5\log\left[\frac{\sum_i S(f)_i}{\Delta\lambda \sum_i C_{0,i}}\right] \end{eqnarray}.\end{split}\]

Given the ease with which one can combine indices in the latter definition, we provide these measurements, as well.

Note

The calculations performed by this class are agnostic as to the redshift of the spectrum provided. It is expected that you will have either de-redshifted the spectrum or redshifted the passband definitions appropriately to measure the index in a redshifted spectrum. However, note that, for the latter case, the calculated indices with angstrom units should be divided by \(1+z\) (where \(z\) is the redshift) to calculate the rest-frame spectral index; no factor is needed for the indices in magnitude units.

Parameters

• wave (numpy.ndarray) – Wavelength vector.

• flux (array-like) – Flux vector. Units must be appropriate to the definition of the provided index passbands. Can be a numpy.ma.MaskedArray; masked pixels will be ignored in the measurement.

• bluebands (numpy.ndarray) – Array with the definition of the blue sidebands. Shape must be \((N_{\rm index},2)\), where the second axis provides the starting and ending wavelength of each band.

• redbands (numpy.ndarray) – Array with the definition of the red sidebands. Shape must be \((N_{\rm index},2)\), where the second axis provides the starting and ending wavelength of each band.

• mainbands (numpy.ndarray) – Array with the definition of the primary passbands. Shape must be \((N_{\rm index},2)\), where the second axis provides the starting and ending wavelength of each band.

• err (numpy.ndarray, optional) – Error in the flux, used for a nominal propagation of the index error.

• log (numpy.ndarray, optional) – Flag that the provided flux vector is sampled logarithmically in wavelength.

• units (numpy.ndarray, optional) – Array with the units for each index to compute. Elements of the array must be either 'ang' or 'mag'. If units is None, 'ang' is assumed for all indices.

nindx

Number of indices

Type

int

units

String array with the units of each index ('ang' or 'mag').

Type

numpy.ndarray

blue_center

Center of the blue sideband.

Type

numpy.ndarray

blue_continuum

Flux in the blue sideband.

Type

numpy.ndarray

blue_continuum_err

Propagated error in the blue sideband flux.

Type

numpy.ndarray

blue_incomplete

Boolean array flagging if the blue sideband contained any masked pixels.

Type

numpy.ndarray

blue_empty

Boolean array flagging if the blue sideband was completely empty.

Type

numpy.ndarray

red_center

Center of the red sideband.

Type

numpy.ndarray

red_continuum

Flux in the red sideband.

Type

numpy.ndarray

red_continuum_err

Propagated error in the red sideband flux.

Type

numpy.ndarray

red_incomplete

Boolean array flagging if the red sideband contained any masked pixels.

Type

numpy.ndarray

red_empty

Boolean array flagging if the red sideband was completely empty.

Type

numpy.ndarray

continuum_m

Slope of the linear continuum defined by the two sidebands.

Type

numpy.ndarray

continuum_b

Intercept of the linear continuum defined by the two sidebands.

Type

numpy.ndarray

main_continuum

The continuum interpolated to the center of the main passband based on the linear continuum constructed using the blue and red sidebands.

Type

numpy.ndarray

main_continuum_err

The propagated error in the continuum interpolated to the center of the main passband.

Type

numpy.ndarray

main_flux

The integral of the flux over the main passband.

Type

numpy.ndarray

main_flux_err

Propagated error in the integral of the flux over the main passband.

Type

numpy.ndarray

main_incomplete

Boolean array flagging if the main passband contained any masked pixels.

Type

numpy.ndarray

main_empty

Boolean array flagging if the main passband was completely empty.

Type

numpy.ndarray

index

Computed index following the Worthey et al. definition.

Type

numpy.ndarray

index_err

Error in the WT index from nominal error propagation. Does not include error in the linear continuum.

Type

numpy.ndarray

index_bf

Computed index following the Burstein et al. definition.

Type

numpy.ndarray

index_bf_err

Error in the BF index from nominal error propagation. Does not include error in the linear continuum.

Type

numpy.ndarray

divbyzero

Boolean array flagging if the index computation encountered a division by 0 error; only flagged for indices with magnitude units.

Type

numpy.ndarray

class mangadap.proc.spectralindices.BandheadIndices(wave, flux, bluebands, redbands, err=None, log=True, order=None)

Bases: object

Measure a set of bandhead, or “color”, indices in a single spectrum.

These indices simply measure the ratio between two sidebands. Following the nomenclature for the AbsorptionLineIndices, a color index is:

\[{\mathcal I} = \frac{\langle f\rangle_0}{\langle f\rangle_1},\]

where \(\langle y\rangle = S(y)/S(1)\) and the two sidebands are denoted with indices 0 and 1; order is used to select if the index is calculated as the red-to-blue flux ratio or the blue-to-red flux ratio.

Indices from multiple spectra can be combined to provide the expected index for the summed (or mean) spectrum by constructing the weighted-mean index, using the continuum in the denominator as the weights:

\[\frac{\sum_i \langle f_i\rangle_1 {\mathcal I}_i}{\sum_i \langle f_i\rangle_1} = \frac{\sum_i \langle f_i\rangle_0} {\sum_i \langle f_i\rangle_1} = \frac{\langle\sum_i f_i\rangle_0} {\langle\sum_i f_i\rangle_1}\]

Note

The calculations performed by this class are agnostic as to the redshift of the spectrum provided. It is expected that you will have either de-redshifted the spectrum or redshifted the passband definitions appropriately to measure the index in a redshifted spectrum. Because the indices are flux ratios, indices calculated for a redshifted spectrum (with appropriately defined passbands) are identical to those calculated shifted to the rest frame.

Also, the integrand is always the provided flux vector, meaning that its units should be appropriate to all of the indices to be calculated. For example, the D4000 index uses continua measured by the integral \(\int F_\nu {\rm d}\lambda\), meaning the spectrum provided to this class should be in per-frequency units.

Parameters

• wave (numpy.ndarray) – Wavelength vector.

• flux (array-like) – Flux vector. Units must be appropriate to the definition of the provided index passbands. Can be a numpy.ma.MaskedArray; masked pixels will be ignored in the measurement.

• bluebands (numpy.ndarray) – Array with the definition of the blue sidebands. Shape must be \((N_{\rm index},2)\), where the second axis provides the starting and ending wavelength of each band.

• redbands (numpy.ndarray) – Array with the definition of the red sidebands. Shape must be \((N_{\rm index},2)\), where the second axis provides the starting and ending wavelength of each band.

• err (numpy.ndarray, optional) – Error in the flux, used for a nominal propagation of the index error.

• log (numpy.ndarray, optional) – Flag that the provided flux vector is sampled logarithmically in wavelength.

• order (numpy.ndarray, optional) – String array signifying which band is in the numerator and which in the denominator. The string must be 'r_b' — signifying the index is calculated as the red continuum divided by the blue continuum — or 'b_r'. If None, 'r_b' is assumed for all measurements.

class mangadap.proc.spectralindices.SpectralIndices(database_key, binned_spectra, redshift=None, stellar_continuum=None, emission_line_model=None, database_list=None, artifact_path=None, absorption_index_path=None, bandhead_index_path=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)

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.

Todo

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 using available_spectral_index_databases().

• artifact_path (str, optional) – Path to the directory with artifact parameter files. If None, defined by mangadap.par.artifactdb.ArtifactDB.default_data_dir.

• absorption_index_path (str, optional) – Path to the directory with absorption-line index parameter files. If None, defined by mangadap.par.absorptionindexdb.AbsorptionIndexDB.default_data_dir.

• bandhead_index_path (str, optional) – Path to the directory with bandhead index parameter files. If None, defined by mangadap.par.bandheadindexdb.BandheadIndexDB.default_data_dir.

• 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.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.dap_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.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()

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)

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

• measure_on_unbinned_spaxels (bool) – Flag that method expects to measure moments on unbinned spaxels.

• good_snr (numpy.ndarray) – Boolean array setting which spectra have sufficient S/N for the measurements.

• default_redshift (float, optional) – Only used if there are stellar kinematics available. Provides the default redshift to use for spectra without stellar measurements; see redshift in mangadap.proc.stellarcontinuummodel.StellarContinuumModel.matched_kinematics(). If None (default), the median of the unmasked stellar velocities will be used.

_compile_database()

Compile the database with the specifications of each index.

_define_databases(database_key, database_list=None, artifact_path=None, absorption_index_path=None, bandhead_index_path=None)

Select the database of indices

_flag_good_spectra(measure_on_unbinned_spaxels)

_get_missing_bins(unique_bins=None)

_index_database_dtype(name_len)

Construct the record array data type for the output fits extension.

_initialize_primary_header(hdr=None, measurements_binid=None)

Construct the primary header for the reference file.

Parameters

• hdr (astropy.io.fits.Header, optional) – Input base header for added keywords. If None, uses the cube header (if there is one) and then cleans the header using mangadap.util.fitsutil.DAPFitsUtil.clean_dap_primary_header().

• measurements_binid (numpy.ndarray, optional) – Bin IDs for spectral index measurements. Only use is to check if this is None, and the boolean result is saved to the header to indicate if the spectral indices are disconnected from the stellar-continuum measurements.

Returns

Initialized header object.

Return type

astropy.io.fits.Header

_resolution_matched_templates(dapver=None, analysis_path=None, tpl_symlink_dir=None)

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)

Set the directory_path and output_file. If not provided, the defaults are set using, respectively, mangadap.config.defaults.dap_common_path() and mangadap.config.defaults.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)

flux and ivar are expected to be masked arrays

static apply_dispersion_corrections(indx, indxcorr, err=None, unit=None)

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

Returns two objects with the corrected indices and errors. If no errors are returned, the second returned object is None.

Return type

tuple

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)

Calculate the spectral-index velocity-dispersion corrections.

The indices are measured twice, once on the best-fitting model (continuum; produces \({\mathcal I}_{\rm mod}\)), and once on the “deconvolved” best-fitting model (continuum_dcnvlv); i.e., the best-fitting model but with 0 velocity dispersion, \({\mathcal I}_{\sigma=0}\). The corrections, \(\delta {\rm mathcal I}\) are then constructed as:

\[\begin{split}\delta{\mathcal I} = \left\{ \begin{array}{ll} {\mathcal I}_{\sigma=0}\ /\ {\mathcal I}_{\rm mod}, & \mbox{for unitless indices} \\[3pt] {\mathcal I}_{\sigma=0}\ /\ {\mathcal I}_{\rm mod}, & \mbox{for angstrom units} \\[3pt] {\mathcal I}_{\sigma=0} - {\mathcal I}_{\rm mod}, & \mbox{for magnitude units} \end{array}\right.,\end{split}\]

where “bandhead” (color) indices are treated as unitless. The construction of the two continuum spectra can be such that they have different redshifts (see redshift and redshift_dcnvlv). The corrected index values are then:

\[\begin{split}{\mathcal I}^c = \left\{ \begin{array}{ll} {\mathcal I}\ \delta{\mathcal I}, & \mbox{for unitless indices} \\[3pt] {\mathcal I}\ \delta{\mathcal I}, & \mbox{for angstrom units} \\[3pt] {\mathcal I} + \delta{\mathcal I}, & \mbox{for magnitude units} \\[3pt] \end{array}\right..\end{split}\]

For absorption-line indices, the index corrections are calculated for both the Worthey/Trager definition and the Burstein/Faber definition.

Similar corrections are calculated for the continuum in the main passband, as well as the two sidebands:

\[\delta C = C_{\sigma=0} / C_{\rm mod},\]

where \(C\) is used here as a generic continuum measurement (cf. AbsorptionLineIndices documentation nomenclature).

Parameters

• absdb (AbsorptionIndexDB) – Database with the absorption-line index definitions.

• bhddb (BandheadIndexDB) – Database with the bandhead index definitions.

• wave (numpy.ndarray) – 1D vector with the wavelength of each pixel. Assumed to be logarithmically binned in radius.

• flux (numpy.ndarray) – 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. This is only used to get the masked pixels to ignore during the index computation in the continuum model.s

• continuum (numpy.ndarray) – Best-fitting continuum-only models to the spectra.

• continuum_dcnvlv (numpy.ndarray) – Best-fitting continuum-only models to the spectra, but with a velocity dispersion of 0 km/s.

• 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

Returns 16 (!) numpy.ndarray objects: The model blue pseudo-continua and corrections, the model red pseudo-continua and corrections, the model main passband continua and corrections, the model weights and corrections, the model Worthey/Trager indices and corrections, the model Burstein/Faber indices and corrections, and boolean arrays selecting the good unitless indices, angstrom-unit indices, and magnitude-unit indices, and absorption-line indices.

Return type

tuple

static check_and_prep_input(wave, flux, ivar=None, mask=None, redshift=None, bitmask=None)

static count_indices(absdb, bhddb)

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

file_name()

Return the name of the output file.

file_path()

Return the full path to the output file.

measure(binned_spectra, redshift=None, stellar_continuum=None, emission_line_model=None, dapver=None, analysis_path=None, directory_path=None, output_file=None, hardcopy=True, tpl_symlink_dir=None, clobber=False, loggers=None, quiet=False)

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.

• dapver (str) – (Optional) The DAP version to use for the analysis, used to override the default defined by mangadap.config.defaults.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.dap_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.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)

Measure the spectral indices in a set of spectra.

The returned record array has the following elements:

Column Name	Description
BINID	Binned spectrum ID
BINID_INDEX	Binned spectrum 0-indexed ID
REDSHIFT	Spectrum redshift
MASK	Bitmask value for each index measurement
BCEN	Unweighted center of the blue sideband
BCONT	Continuum level of the blue sideband
BCONT_ERR	Error in the blue-sideband continuum
BCONT_MOD	Continuum level of the model spectrum in the blue sideband
BCONT_CORR	Zero-dispersion correction to the blue-sideband continuum
RCEN	Unweighted center of the red sideband
RCONT	Continuum level of the red sideband
RCONT_ERR	Error in the red-sideband continuum
RCONT_MOD	Continuum level of the model spectrum in the red sideband
RCONT_CORR	Zero-dispersion correction to the red-sideband continuum
MCONT	Continuum level in the main passband
MCONT_ERR	Error in the main-passband continuum
MCONT_MOD	Continuum level of the model spectrum in the main passband
MCONT_CORR	Zero-dispersion correction to the main-passband continuum
AWGT	Appropriate weight to use when additively combining measurements.
AWGT_ERR	Error in weight.
AWGT_MOD	Model weight to use when additively combining measurements.
AWGT_CORR	Zero-velocity dispersion correction to weight.
INDX	Index measured using the Worthey/Trager definition
INDX_ERR	Error in the above
INDX_MOD	Value of the Worthey/Trager defined index in the model spectrum
INDX_CORR	Correction to the index measured using the Worthey/Trager definition
INDX_BF	Index measured using the Burstein/Faber definition
INDX_BF_ERR	Error in the above
INDX_BF_MOD	Value of the Burstein/Faber defined index in the model spectrum
INDX_BF_CORR	Correction to the index measured using the Burstein/Faber definition

See the documentation of AbsorptionLineIndices and BandheadIndices for the definitions of these quantities. For the purpose of their storage here, INDX refers to \({\mathcal I}_{\rm WT}\) for the absorption-line indices. There is only one definition for the bandhead/color indices, and they are included in both INDX and INDX_BF (see save_results()).

The weights to use when combining indices are simply copies of the data in other columns, collected for convenience (and to ease the construction of the main DAP output file). For all absorption-line indices, AWGT is identically MCONT; for bandhead indices, AWGT is BCONT and RCONT for indices with order 'r_b' and 'b_r' order, respectively.

This function does not add the BINID, BINID_INDEX, *_MOD or *_CORR values. All except the first 3 columns vectors with a length of \(N_{\rm index}\) — the total number of indices calculated (see count_indices()).

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 index measurements.

Return type

numpy.recarray

static output_dtype(nindx, bitmask=None)

Construct the record array data type for the output fits extension.

read(ifile=None, strict=True, checksum=False)

Read an existing file with a previously binned set of spectra.

static save_results(results, measurements, good, err=False, bitmask=None)

Save the index measuremements to the measurement database.

static set_masks(measurements, blue_incomplete, blue_empty, red_incomplete, red_empty, divbyzero, main_incomplete=None, main_empty=None, bitmask=None)

static spectra_for_index_measurements(binned_spectra, measure_on_unbinned_spaxels=False, pixelmask=None, select=None, resolution_fwhm=None, emission_line_model=None)

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 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)

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

write(clobber=False)

Write the hdu object to the file.

class mangadap.proc.spectralindices.SpectralIndicesBitMask

Bases: mangadap.util.dapbitmask.DAPBitMask

Derived class that specifies the mask bits for the spectral-index measurements. The maskbits defined are:

Key	Bit	Description
DIDNOTUSE	0	Pixel was ignored because it was flagged as DONOTUSE or FORESTAR by the DRP, or as LOW_SPECCOV, LOW_SNR, or NONE_IN_STACK in the binning step.
FORESTAR	1	Pixel was ignored because it was flagged as FORESTAR by the DRP.
LOW_SNR	2	Pixel was ignored because the S/N estimate of the spectrum was below the set threshold; see header keyword SIMINSN.
ARTIFACT	3	Pixel was ignored during the spectral-index measurements because it was designated as containing an artifact.
SPECRES_LOW	4	The spectral resolution was not matched to the target value because the target value was higher than the existing spectral resolution.
NO_MEASUREMENT	5	Nothing measured because of low S/N, missing spectrum, or incomplete bandpass definition.
MAIN_EMPTY	6	Index not measured because the main passband had no observed fluxes.
BLUE_EMPTY	7	Index not measured because the blue passband had no observed fluxes.
RED_EMPTY	8	Index not measured because the red passband had no observed fluxes.
MAIN_INCOMP	9	There were masked fluxes in the main passband.
BLUE_INCOMP	10	There were masked fluxes in the blue passband.
RED_INCOMP	11	There were masked fluxes in the red passband.
DIVBYZERO	12	Could not compute index or its error because of a zero devision. Either the pseudocontinuum in a bandhead computation or the continuum in an absorption-line computation was zero.
NO_DISPERSION_CORRECTION	13	No dispersion correction was applied to the index because either the template library did not cover this wavelength range or not zero-dispersion model fit was available.
UNDEFINED_BANDS	14	No index calculated because the bandpasses were not, or improperly, defined.

cfg_root = 'spectral_indices_bits'

class mangadap.proc.spectralindices.SpectralIndicesDef(key=None, minimum_snr=None, fwhm=None, compute_corrections=None, artifacts=None, absindex=None, bandhead=None)

Bases: mangadap.par.parset.KeywordParSet

A class that holds the parameters necessary to perform the spectral-index measurements.

The defined parameters are:

Key	Type	Options	Default	Description
key	str			Keyword used to distinguish between different spectral-index databases.
minimum_snr	int, float			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()

Return the list of available spectral index databases

Available database combinations:

Todo

Fill in

Returns

A list of SpectralIndicesDef() objects, each defining a spectral-index database to measure.

Return type

list

Raises

• 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)

Validate DefaultConfig object with spectral-index measurement parameters.

Parameters

cnfg (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.