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.

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

Bases: object

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

The absorption-line index calculations are performed as defined/used by Worthey (1994) and Trager et al. (1998) (\({\mathcal I}_{\rm WT}\)), as well as defined/used by Burstein et al. (1984) and Faber et al. (1985) (\({\mathcal I}_{\rm 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 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 (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).

Let:

\[\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 (not necessarily “flat”) 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, the DAP calculates both \({\mathcal I}_{\rm WT}\) and \({\mathcal I}_{\rm BF}\).

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)[source]

Bases: object

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

Bandhead, or color, indices simply measure the ratio of fluxes in two sidebands. Following the nomenclature defined for the Absorption-line Indices, 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 subscripts 0 and 1. The “order” of the index selects if the index is calculated as the red-to-blue flux ratio or the blue-to-red flux ratio (e.g., D4000 is defined as a red-to-blue index, whereas TiOCvD is defined as a blue-to-red index).

Given the simple definition of color indices, a combined index for the sum (or mean) of multiple spectra can be calculated by constructing the weighted-mean index, where the continuum in the denominator is used as the weight:

\[\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, 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, output_path=None, output_file=None, hardcopy=True, tpl_hardcopy=False, overwrite=None, 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.

Todo

Detail what should be provided in terms of the redshift.

Parameters:

database (SpectralIndicesDef) – Object defining the parameters and databases for the measurements.
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.
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.
overwrite (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 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 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()[source]: Compile the database with the specifications of each index.

_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]

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()[source]: Get a version of the template library that has had its resolution matched to that of the spectral-index database.

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:

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)[source]

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)[source]

static count_indices(absdb, bhddb)[source]: Count the total number (absorption-line and bandhead) indices.

static default_paths(cube, method_key, rdxqa_method, binning_method, stelcont_method=None, elmodel_method=None, output_path=None, output_file=None)[source]

Set the default directory and file name for the output file.

Parameters:

cube (mangadap.datacube.datacube.DataCube) – Datacube to analyze.
method_key (str) – Keyword designating the method used for the reduction assessments.
rdxqa_method (str) – The method key for the basic assessments of the datacube.
binning_method (str) – The method key for the spatial binning.
stelcont_method (str, optional) – The method key for the stellar-continuum fitting method. If None, not included in output file name.
elmodel_method (str, optional) – The method key for the emission-line modeling method. If None, not included in the output file name.
output_path (str, Path, optional) – The path for the output file. If None, the current working directory is used.
output_file (str, optional) – The name of the output “reference” file. The full path of the output file will be directory_path/output_file. If None, the default is to combine cube.output_root and the method keys. The order of the keys is the order of operations (rdxqa, binning, stellar continuum, emission-line model).

Returns:

Returns a Path with the output directory and a str with the output file name.

Return type:

tuple

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, output_path=None, output_file=None, hardcopy=True, tpl_hardcopy=False, overwrite=None, 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.
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.
overwrite (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.

The returned object is SpectralIndicesDataTable; see the documentation of this object for the list of returned quantities.

See the documentation of AbsorptionLineIndices and BandheadIndices for the definitions of the index measurements. 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:

The object with the index-measurement data.

Return type:

SpectralIndicesDataTable

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]: 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)[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 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(overwrite=False)[source]: Write the hdu object to the file.

class mangadap.proc.spectralindices.SpectralIndicesBitMask[source]

Bases: 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.SpectralIndicesDataTable(nindx=1, bitmask=None, shape=None)[source]

Bases: DataTable

Primary data table with the results of the spectral-index measurements.

Table includes:

Key	Type	Description
BINID	`int64`	Spectrum/Bin ID number
BINID_INDEX	`int64`	Index of the spectrum in the list of provided spectra.
REDSHIFT	`float64`	Redshift used for shifting the passbands
MASK	`bool_`	Bad-value boolean or bit mask value for the moments
BCEN	`float64`	Center of the blue sideband
BCONT	`float64`	Pseudo-continuum in the blue sideband
BCONT_ERR	`float64`	Error in the blue-sideband pseudo-continuum
BCONT_MOD	`float64`	Pseudo-continuum in the blue sideband of the best-fitting model spectrum
BCONT_CORR	`float64`	Multiplicative correction to apply to the pseudo-continuum in the blue sideband to match the measurement for a spectrum with no Doppler broadening
RCEN	`float64`	Center of the red sideband
RCONT	`float64`	Pseudo-continuum in the red sideband
RCONT_ERR	`float64`	Error in the red-sideband pseudo-continuum
RCONT_MOD	`float64`	Pseudo-continuum in the red sideband of the best-fitting model spectrum
RCONT_CORR	`float64`	Multiplicative correction to apply to the pseudo-continuum in the red sideband to match the measurement for a spectrum with no Doppler broadening
MCONT	`float64`	Interpolated continuum at the center of the main index passband (absorption-line indices only)
MCONT_ERR	`float64`	Error in the continuum of the main passband
MCONT_MOD	`float64`	Continuum in the main passband of the best-fitting model spectrum
MCONT_CORR	`float64`	Multiplicative correction to apply to the continuum in the main passband to match the measurement for a spectrum with no Doppler broadening
AWGT	`float64`	Weight needed to construct an index measured for the sum (or mean) of a set of spectra. This identical to data pulled from either BCONT, RCONT, or MCONT, as appropriate to the calculation.
AWGT_ERR	`float64`	Error in the aggregation weight
AWGT_MOD	`float64`	Weight as measured using the best-fitting model spectrum
AWGT_CORR	`float64`	Multiplicative correction to apply to the weight needed to match the measurement for a spectrum with no Doppler broadening
INDX	`float64`	Index measurement for the observed spectrum. Absorption lines are measured using the definition in Worthey et al. (1994)
INDX_ERR	`float64`	Error in the spectral index
INDX_MOD	`float64`	Spectral index as measured using the best-fitting model spectrum
INDX_CORR	`float64`	Index correction needed to match the measurement for a spectrum with no Doppler broadening
INDX_BF	`float64`	Index measurement for the observed spectrum. Absorption lines are measured using the definition used by Burstein et al. (1984) and Faber et al. (1985); see also Faber et al. (1977)
INDX_BF_ERR	`float64`	Error in the spectral index
INDX_BF_MOD	`float64`	Spectral index as measured using the best-fitting model spectrum
INDX_BF_CORR	`float64`	Index correction needed to match the measurement for a spectrum with no Doppler broadening

Parameters:

nindx (int) – Number of spectral indices to measure.
bitmask (BitMask, optional) – Object used to flag mask bits. If None, flags are simply boolean.
shape (int, tuple, optional) – The shape of the initial array. If None, the data array will not be instantiated; use init() to initialize the data array after instantiation.

class mangadap.proc.spectralindices.SpectralIndicesDef(key='INDXEN', minimum_snr=0.0, pixelmask=None, fwhm=-1, compute_corrections=True, absindex='EXTINDX', bandhead='BHBASIC', overwrite=False)[source]

Bases: KeywordParSet

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

The defined parameters are:

Key	Type	Default	Description
`key`	str	`INDXEN`	Keyword used to distinguish between different spectral-index databases.
`minimum_snr`	int, float	0.0	Minimum S/N of spectrum to fit
`pixelmask`	SpectralPixelMask		Object used to mask spectral pixels
`fwhm`	int, float	-1	Resolution FWHM in angstroms at which to make the measurements. If -1, the measurements are taken at the native resolution of the observed spectra. If >0, the resolution should be larger than the observed resolution, and the observed data are convolved with a wavelength dependent Gaussian to match it to the provided FWHM.
`compute_corrections`	bool	True	Flag to compute velocity dispersion corrections to the measured indices, if possible. This requires the stellar kinematics results from the stellar continuum fitting.
`absindex`	str	`EXTINDX`	Either a string identifying the absorption-line database to use, or the direct path to the parameter file defining the database
`bandhead`	str	`BHBASIC`	Either a string identifying the bandhead/color database to use, or the direct path to the parameter file defining the database
`overwrite`	bool	False	If the output file already exists, redo all the calculations and overwrite it.

_validate()[source]: Validate the object and instantiate the passband database to use for the emission-line moments.

classmethod from_dict(d)[source]: Instantiate from a dictionary.

class mangadap.proc.spectralindices.SpectralIndicesDefinitionTable(name_len=1, shape=None)[source]

Bases: DataTable

Table with the definitions of the spectral indices.

Table includes:

Key	Type	Description
TYPE	`str_`	Type of spectral index, either absorption or bandhead.
ID	`int64`	ID number for the spectral index
NAME	`str_`	Unique name for the spectral index
PASSBAND	`float64`	Lower and upper rest wavelength of the main index passband (absorption-line indices only)
BLUEBAND	`float64`	Lower and upper rest wavelength of the blue sideband used to define the linear continuum
REDBAND	`float64`	Lower and upper rest wavelength of the red sideband used to define the linear continuum
UNIT	`str_`	Index units
COMPONENT	`bool_`	Flag if the index is a component of a multi-component index (ignored)
INTEGRAND	`str_`	The flux integrand for the index.
ORDER	`str_`	The numerator-denominator order of the index (bandhead/color indices only)

Parameters:

name_len (int) – The maximum length of any of the spectral index names.
shape (int, tuple, optional) – The shape of the initial array. If None, the data array will not be instantiated; use init() to initialize the data array after instantiation.