mangadap.proc.emissionlinemodel module¶
A class hierarchy that fits the emission lines.
Copyright © 2019, SDSS-IV/MaNGA Pipeline Group
- class mangadap.proc.emissionlinemodel.EmissionLineModel(method_key, binned_spectra, stellar_continuum=None, emission_line_moments=None, redshift=None, dispersion=None, minimum_error=None, method_list=None, artifact_path=None, ism_line_path=None, emission_line_db_path=None, dapver=None, analysis_path=None, directory_path=None, output_file=None, hardcopy=True, clobber=False, checksum=False, loggers=None, quiet=False)[source]¶
Bases:
object
Class that holds the emission-line model fits.
- Parameters
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.
- loggers¶
List of logging.Logger objects to log progress; ignored if quiet=True. Logging is done using
mangadap.util.log.log_output()
.- Type
list
- quiet¶
Suppress all terminal and logging output.
- Type
bool
- _assign_image_arrays()[source]¶
Set
image_arrays
, which contains the list of extensions inhdu
that are on-sky image data.
- _assign_input_kinematics(emission_line_moments, redshift, dispersion, default_dispersion=100.0)[source]¶
Set the initial redshift and velocity dispersion for each spectrum.
In terms of precedence, directly provided redshifts and dispersions override those in the EmissionLineMoments model, which overrides those in the StellarContinuumModel object. The default_dispersion does not take precedence over any provided disperison.
If emission_line_moments, redshift, and
stellar_continuum
are all None, the redshift is set to 0.0. If dispersion is also None, the dispersion is set to default_dispersion.To get the stellar kinematics, the function calls
mangadap.proc.stellarcontinuummodel.StellarContinuumModel.matched_kinematics()
. In this function, the provided redshift and dispersion must be a single value or None; therefore, the means of any vectors provided as redshift or disperison are passsed to this function instead of the full vector.- Parameters
emission_line_moments (
mangadap.proc.emissionlinemoments.EmissionLineMoments
) – Object with the results of the emission-line-moment measurementsredshift (
float
, numpy.ndarray) – Redshifts (\(z\)) to use for each spectrum.dispersion (
float
, numpy.ndarray) – Velocity dispersion (km/s) to use for each spectrum.default_dispersion (
float
, numpy.ndarray, optional) – Default velocity dispersion to use (km/s), if relevant.
- _construct_2d_hdu(good_snr, model_flux, model_base, model_mask, model_eml_par, model_fit_par=None, model_binid=None)[source]¶
Construct
hdu
that is held in memory for manipulation of the object. Seeconstruct_3d_hdu()
if you want to convert the object into a DRP-like datacube.
- _fill_method_par(analysis_path=None)[source]¶
Fill in any remaining modeling parameters.
Todo
Construct the replacement template library here instead of in Sasuke?
- _finalize_cube_mask(mask)[source]¶
Finalize the mask after the 2D mask has been reconstructed into a 3D cube.
This mostly handles the masks for regions outside the datacube field of view.
Note that the input mask is both edited in-place and returned.
Todo
This needs to be abstracted for non-DRP datacubes.
Describe MAPMASK usage
- Parameters
mask (numpy.ndarray) – 3D array with the current bitmask data.
- Returns
Edited bitmask data.
- Return type
- _get_line_fit_metrics(model_flux, model_base, model_mask, model_eml_par, model_binid=None, window=15, debug=False)[source]¶
Compute fit-quality metrics near each fitted line.
Primarily a wrapper of
EmissionLineFit.line_metrics()
.- Parameters
model_flux (numpy.ndarray) – The best-fitting emission-line model spectra.
model_base (numpy.ndarray) – The “baseline” of the emission-line model defined as the difference between the best-fitting stellar-continuum model and the best-fitting continuum from the emission-line modeling procedure.
model_mask (numpy.ndarray) – A boolean or integer (bitmask) array with the mask for the model data.
model_eml_par (
EmissionLineFitDataTable
) – A record array with the best-fitting results and parameters for each emission line. The format is expected to be given byEmissionLineFit._per_emission_line_dtype()
. This object is edited in place and returned.model_binid (numpy.ndarray, optional) – A 2D array with the bin ID assigned to each spaxel with a fitted emission-line model. The number of non-negative bin IDs must match the number of fitted models. If None, this is generated from the BINID column in the model_eml_par object.
window (
int
, optional) – The window size in pixels around each line to use for calculation of the figures of merit.
- Returns
Return the input
model_eml_par
after filling the LINE_PIXC, AMP, ANR, LINE_NSTAT, LINE_CHI2, LINE_RMS, and LINE_FRMS columns.- Return type
- _initialize_primary_header(hdr=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 datacube header from
binned_spectra
(if there is one) and then cleans the header usingmangadap.util.fitsutil.DAPFitsUtil.clean_dap_primary_header()
.- Returns
Initialized header object.
- Return type
- _set_paths(directory_path, dapver, analysis_path, output_file)[source]¶
Set the
directory_path
andoutput_file
. If not provided, the defaults are set using, respectively,mangadap.config.defaults.dap_method_path()
andmangadap.config.defaults.dap_file_name()
.- Parameters
directory_path (str) – The exact path to the DAP emission-line moments 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 emission-line moment measurements. See
measure()
.
- construct_3d_hdu()[source]¶
Reformat the model spectra into a cube matching the shape of the DRP fits file.
- construct_continuum_models(replacement_templates=None, redshift_only=False, deredshift=False, dispersion_corrections=None)[source]¶
- copy_to_array(ext='FLUX', waverange=None, include_missing=False)[source]¶
Wrapper for
mangadap.util.fitsutil.DAPFitsUtil.copy_to_array()
specific forEmissionLineModel
.Return a copy of the selected data array. The array size is always \(N_{\rm models} \times N_{\rm wavelength}\); i.e., the data is always flattened to two dimensions and the unique spectra are selected.
- Parameters
ext (str) – (Optional) Name of the extension from which to draw the data. Must be allowed for the current
mode
; seedata_arrays
. Default is'FLUX'
.waverange (array-like) – (Optional) Two-element array with the first and last wavelength to include in the computation. Default is to use the full wavelength range.
include_missing (bool) – (Optional) Create an array with a size that accommodates the missing models.
- Returns
A 2D array with a copy of the data from the selected extension.
- Return type
- copy_to_masked_array(ext='FLUX', flag=None, waverange=None, include_missing=False)[source]¶
Wrapper for
mangadap.util.fitsutil.DAPFitsUtil.copy_to_masked_array()
specific forEmissionLineModel
.Return a copy of the selected data array as a masked array. This is functionally identical to
copy_to_array()
, except the output format is a numpy.ma.MaskedArray. The pixels that are considered to be masked can be specified using flag.- Parameters
ext (str) – (Optional) Name of the extension from which to draw the data. Must be allowed for the current
mode
; seedata_arrays
. Default is ‘FLUX’.flag (str or list) – (Optional) (List of) Flag names that are considered when deciding if a pixel should be masked. The names must be a valid bit name as defined by
bitmask
. If not provided, ANY non-zero mask bit is omitted.waverange (array-like) – (Optional) Two-element array with the first and last wavelength to include in the computation. Default is to use the full wavelength range.
include_missing (bool) – (Optional) Create an array with a size that accommodates the missing models.
- Returns
A 2D array with a copy of the data from the selected extension.
- Return type
- static define_method(method_key, method_list=None)[source]¶
Select the modeling method
- Parameters
method_key (str) – Description
method_list (list) –
- fill_continuum_to_match(binid, replacement_templates=None, redshift_only=False, deredshift=False, corrected_dispersion=False, missing=None)[source]¶
Get the emission-line continuum model, if possible, that matches the input bin ID matrix. The output is a 2D matrix ordered by the bin ID; any skipped index numbers in the maximum of the union of the unique numbers in the binid and missing input are masked.
Use replacement_templates only if the number of templates is identical to the number used during the fitting procedure. Use redshift_only to produce the best-fitting model without and velocity dispersion. Use corrected_dispersion to produce the model using the corrected velocity dispersion.
- fill_to_match(binid, include_base=False, missing=None)[source]¶
Get the emission-line model that matches the input bin ID matrix. The output is a 2D matrix ordered by the bin ID; any skipped index numbers in the maximum of the union of the unique numbers in the binid and missing input are masked.
Use include_base to include the baseline in the output emission-line models.
- fit(binned_spectra, stellar_continuum=None, emission_line_moments=None, redshift=None, dispersion=None, minimum_error=None, dapver=None, analysis_path=None, directory_path=None, output_file=None, hardcopy=True, clobber=False, loggers=None, quiet=False)[source]¶
Fit the emission lines.
- fit_figures_of_merit()[source]¶
Use the fitting class to set the figures-of-merit of the full fit.
This is primarily used to set the output data for the MAPS file.
- Returns
Returns (1) a list of names to assign each column (length is NFOM), (2) the units of the data in this column (length is NFOM), and (3) a 2D array with the figures of merit for each spectrum (shape is NSPEC x NFOM). If the fitting class used does not have a fit_figures_of_merit function, the name is set to ‘null’, the unit is an empty string, and the data is a (NMOD,1) array of zeros.
- Return type
tuple
- matched_kinematics(binid, line_name, redshift=None, dispersion=100.0, constant=False, cz=False, corrected=False, min_dispersion=None, nearest=False, missing=None)[source]¶
Return the redshift and velocity dispersion for all the spectra based on the emission-line model fit to a single line.
For spectra the were not fit, use the median (unmasked) kinematic measurement if no default value is provided as an argument.
- Parameters
binid (numpy.ndarray) – 2D array with the bin ID associate with each spaxel in the datacube.
line (str) – Line to use for the kinematics. Must match one of the lines created by
channel_names()
. Function will raise an exception if the line_name is None or if the channel names cannot be constructed.redshift (float) – (Optional) The default redshift to use for spectra without an emission-line fit. Default is to use the median of the unmasked measurements.
dispersion (float) – (Optional) The default velocity dispersion to use for spectra without an emission-line fit. Default is 100 km/s.
constant (bool) – (Optional) Force the function to return a constant redshift and dispersion for each spectrum, regardless of any fitted kinematics.
cz (bool) – (Optional) Return the redshift as cz in km/s, as opposed to unitless z.
corrected (bool) – (Optional) By default, the returned velocity dispersions are the measured values, which will include the instrumental resolution. Setting corrected to True will return the corrected dispersions.
min_dispersion (float) – (Optional) Impose a minimum dispersion.
nearest (bool) – (Optional) Instead of the median of the results for the spectra that were not fit, use the value from the nearest bin.
missing (list) – (Optional) Any bin ID numbers missing from the input binid image needed for constructing the output matched data.
- Returns
Returns arrays with a redshift (or cz) and dispersion for each spectrum.
- Return type
- Raises
TypeError – Raised if the input redshift or dispersion values are not single numbers.
- class mangadap.proc.emissionlinemodel.EmissionLineModelBitMask[source]¶
Bases:
mangadap.util.dapbitmask.DAPBitMask
Derived class that specifies the mask bits for the emission-line modeling. 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 ELFMINSN.
ARTIFACT
3
Pixel was ignored during the emission-line model fit because it was designated as containing an artifact.
OUTSIDE_RANGE
4
Pixel was ignored during the emission-line model fit because it was outside of any emission-line fitting window.
NOCONTINUUM
5
Pixel did not have any model of the stellar-continuum subtracted.
INSUFFICIENT_DATA
6
There were insufficient data over the relevant wavelength range to fit the line profile(s).
FIT_FAILED
7
Emission-line fit failed according to status returned by scipy.optimize.least_squares.
NEAR_BOUND
8
Emission-line parameter(s) are within at or near the imposed boundaries in parameter space to within the error of the parameter.
UNDEFINED_COVAR
9
Emission-line fit resulted in a covariance matrix with negative values along the diagonal, meaning that the formal error is undefined. (Need to test, but this should mean that the fit is bad.)
EXCLUDED_FROM_MODEL
10
Emission-line fit excluded from the emission-line flux model because the input emission-line database requested it be one of the lines in the fitting window be excluded or one of the following bits were set: INSUFFICIENT_DATA, FIT_FAILED, NEAR_BOUND, UNDEFINED_COVAR.
UNDEFINED_SIGMA
11
Emission-line velocity dispersion is undefined because it was found to be smaller than the instrumental dispersion.
NON_POSITIVE_CONTINUUM
12
Equivalent width measurements were not computed because the continuum in either the blue or red sidebands was not positive.
NO_FIT
13
Emission-line or spectrum was not fit.
TPL_PIXELS
14
These pixels were removed to ensure that the number of template spectral pixels was >= the number of fitted object pixels during the stellar-continuum fit.
TRUNCATED
15
This region was truncated to avoid convolution errors at the edges of the spectral range during the stellar-continuum fit.
PPXF_REJECT
16
Pixel was rejected during the pPXF fit via the clean parameter.
MIN_SIGMA
17
The fitted velocity dispersion is at the minimum allowed by pPXF (1/100th of a pixel)
BAD_SIGMA
18
Corrected velocity dispersion is below 0 km/s or above 400 km/s
MAXITER
19
The fit optimizer reached the maximum number of iterations during the fit, which may imply failure to converge.
INVALID_ERROR
20
Pixel ignored because the flux error was invalid.
EML_REGION
21
Pixel was ignored during the stellar-continuum fit because it contains an emission-line.
- cfg_root = 'emission_line_model_bits'¶
- class mangadap.proc.emissionlinemodel.EmissionLineModelDef(key=None, minimum_snr=None, deconstruct_bins=None, mom_vel_name=None, mom_disp_name=None, waverange=None, artifacts=None, ism_mask=None, emission_lines=None, continuum_tpl_key=None, fitpar=None, fitclass=None, fitfunc=None)[source]¶
Bases:
mangadap.par.parset.KeywordParSet
A class that holds the parameters necessary to perform the emission-line profile fits.
The defined parameters are:
Key
Type
Options
Default
Description
key
str
Keyword used to distinguish between different emission-line moment databases.
minimum_snr
int, float
Minimum S/N of spectrum to fit
deconstruct_bins
str
Method to use for deconstructing binned spectra into individual spaxels for emission-line fitting. See
deconstruct_bins_options()
.mom_vel_name
str
Name of the emission-line moments band used to set the initial velocity guess for each spaxel.
mom_disp_name
str
Name of the emission-line moments band used to set the initial velocity dispersion guess for each spaxel.
waverange
list
Limited wavelength range to use during the fit
artifacts
str
String identifying the artifact database to use
ism_mask
str
String identifying an emission-line database used only for masking lines during the fit.
emission_lines
str
String identifying the emission-line database to use
continuum_tpl_key
str
String identifying the continuum templates to use
fitpar
ParSet, dict
Fitting function parameters
fitclass
Undefined
Class used to perform the fit.
fitfunc
Undefined
Function or method that performs the fit; must be callable.
- mangadap.proc.emissionlinemodel.available_emission_line_modeling_methods()[source]¶
Return the list of available emission-line modeling methods.
Available methods are:
Todo
Fill in
- Returns
A list of
EmissionLineModelDef
objects, each defining an emission-line modeling method.- Return type
list
- Raises
IOError – Raised if no emission-line moment configuration files could be found.
KeyError – Raised if the emission-line modeling method keywords are not all unique.
NotImplementedError – Raised if the method requests the deconstruction of the bins into spaxls for using the Elric fitter.
Todo
Possible to 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.emissionlinemodel.validate_emission_line_modeling_method_config(cnfg)[source]¶
Validate the
mangadap.util.parser.DefaultConfig
with the emission-line modeling method parameters.- Parameters
cnfg (
mangadap.util.parser.DefaultConfig
) – Object meant to contain defining parameters of the emission-line modeling method needed byEmissionLineModelDef
- Raises
KeyError – Raised if any required keywords do not exist.
ValueError – Raised if keys have unacceptable values.