mangadap.par.emissionlinedb module

Container class for a database of emission-line parameters, as well as support classes and functions.

Class usage examples

To define an emission line:

from mangadap.par.emissionlinedb import EmissionLinePar
p = EmissionLinePar(index=44, name='Ha', restwave=6564.632, action='f', line='l',
                    flux=1.0, vel=0.0, sig=10., mode='f')

More often, however, you will want to define an emission-line database using an SDSS parameter file. To do so, you can use one of the default set of available emission-line databases:

from mangadap.par.emissionlinedb import EmissionLineDB
print(EmissionLineDB.available_databases())
emldb = EmissionLineDB.from_key('ELPMPL9')

The above call uses the EmissionLineDB.from_key() method to define the database using its keyword and the database provided with the MaNGA DAP source distribution. You can also define the database directly for an SDSS-style parameter file:

from mangadap.par.emissionlinedb import EmissionLineDB
emldb = EmissionLineDB('/path/to/emission/line/database/myeml.par')

The above will read the file and set the database keyword to ‘MYEML’ (i.e., the capitalized root name of the *.par file). See Emission-Line Measurements for the format of the parameter file.

Revision history

17 Mar 2016: Original implementation by K. Westfall (KBW)

11 May 2016: (KBW) Switch to using pydl.pydlutils.yanny and pydl.goddard.astro.airtovac instead of internal functions

13 Jul 2016: (KBW) Include log_bounded, blueside, and redside in database.

06 Oct 2017: (KBW) Add function to return channel names

02 Dec 2019: (KBW) Significantly reworked to use the new base class.

---

Copyright © 2019, SDSS-IV/MaNGA Pipeline Group

---

class mangadap.par.emissionlinedb.EmissionLineDB(parfile)

Bases: mangadap.par.spectralfeaturedb.SpectralFeatureDB

Basic container class for the database of emission-line parameters.

Each row of the database is parsed using mangadap.proc.emissionlinedb.EmissionLinePar. For the format of the input file, see Gaussian Emission-Line Modeling.

The primary instantiation requires the SDSS parameter file with the emission-line data. To instantiate using a keyword (and optionally a directory that holds the parameter files), use the mangadap.par.spectralfeaturedb.SpectralFeatureDB.from_key() class method. See the base class for additional attributes.

Parameters

parfile (str) – The SDSS parameter file with the emission-line database.

key

Database signifying keyword

Type

str

file

File with the emission-line data

Type

str

size

Number of emission lines in the database.

Type

int

_parse_yanny()

Parse the yanny file (provided by file) for the emission-line database.

Returns

The list of mangadap.par.parset.ParSet instances for each line of the database.

Return type

list

channel_names(dicttype=True)

Return a dictionary with the channel names as the dictionary key and the channel number as the dictionary value. If dicttype is False, a list is returned with just the string keys.

default_data_dir = 'emission_lines'

class mangadap.par.emissionlinedb.EmissionLinePar(index=None, name=None, restwave=None, action=None, flux=None, mode=None, profile=None, ncomp=None, output_model=None, par=None, fix=None, lobnd=None, hibnd=None, log_bnd=None, blueside=None, redside=None)

Bases: mangadap.par.parset.KeywordParSet

Parameter object that defines a set of emission-line parameters used by various algorithms in the DAP.

See mangadap.par.parset.ParSet for attributes and raised exceptions.

Todo

• Specify these algorithms

• provide some basic printing functions for user-level interaction

• match the variable names to those in the parameter file typedef

The defined parameters are:

Key	Type	Options	Default	Description
index	int			An index used to refer to the line in the line and mode attributes.
name	str			A name for the line.
restwave	int, float			The rest wavelength of the line in angstroms in vacuum.
action	str	i, f, m, s	f	Describes how the line should be treated. See Emission-Line “Actions”. Default is f.
flux	int, float		1.0	Relative flux of the emission (positive) or absorption (negative) lines. This should most often be unity if line=l and indicates the ratio of line flux if line=dN. Default is 1.0.
mode	str		f	Fitting mode for the line. See Emission-Line “Actions”. Default is f.
profile	str		GaussianLineProfile	The class definition of the profile shape. Must be a class in mangadap.util.lineprofiles.
ncomp	int		1	The number of components (number of separate line profiles) to use when fitting the line. Default is 1.
output_model	bool		True	Flag to include the best-fitting model of the line in the emission-line model spectrum. Default is True.
par	ndarray, list			A list of the initial guess for the line profile parameters. The number of parameters must match the struct declaration at the top of the file. The initial parameters are automatically adjusted to provide any designated flux ratios, and the center is automatically adjusted to the provided redshift for the spectrum. For example, for a GaussianLineProfile, this is typically set to [1.0, 0.0, 100.0].
fix	ndarray, list			A list of flags for fixing the input guess parameters during the fit. Use 0 for a free parameter, 1 for a fixed parameter. The parameter value is only fixed after adjusted in the flux and or center based on the redshift and the implied tied parameters. For a free set of parameters using a GaussianLineProfile, this is set to [0, 0, 0].
lobnd	ndarray, list			A list of lower bounds for the parameters. For each parameter, use None to indicate no lower bound. For a GaussianLineProfile with positive flux and standard deviation, this is set to [0.0, None, 0.0].
hibnd	ndarray, list			A list of upper bounds for the parameters. For each parameter, use None to indicate no upper bound. For a GaussianLineProfile with maximum standard deviation of 500 km/s, this is set to [None, None, 500.0].
log_bnd	ndarray, list			A list of flags used when determining if a fit parameter is near the imposed boundary. If true, the fraction of the boundary range used is done in logarithmic, not linear, separation.
blueside	ndarray, list			A two-element vector with the starting and ending wavelength for a bandpass blueward of the emission line, which is used to set the continuum level near the emission line when calculating the equivalent width.
redside	ndarray, list			A two-element vector with the starting and ending wavelength for a bandpass redward of the emission line, which is used to set the continuum level near the emission line when calculating the equivalent width.

The action parameter allows the emission-line database to be used both in masking during the stellar-continuum modeling (see mangadap.util.pixelmask.SpectralPixelMask) and during the emission-line modeling itself.

The valid actions are:

• i: ignore the line, as if the line were commented out.

• f: fit the line and mask the line when fitting the stellar continuum.

• m: mask the line when fitting the stellar continuum but do not fit the line itself

• s: defines a sky line that should be masked. When masked, the wavelength of the line is not adjusted for the redshift of the object spectrum.

I.e., when using the emission-line database for the emission-line modeling, lines with the action set to f are fit, whereas all other lines are ignored.

The mode parameter sets how the emission line should be treated with respect of the rest of the lines being modeled.

The valid modes are:

• f: Fit the line independently of all others.

• wN: Used by mangadap.proc.elric.Elric only. Fit the line with untied parameters, but use a window that includes both this line and the line with index N.

• xN: Used by mangadap.proc.elric.Elric only. Fit the line with its flux tied to the line with index N.

• vN: Fit the line with the velocity tied to the line with index N.

• sN: Fit the line with the velocity dispersion tied to the line with index N.

• kN: Fit the line with the velocity and velocity dispersion tied to the line with index N.

• aN: Fit the line with the flux, velocity, and velocity dispersion tied to the line with index N.

As noted in the mode description, many of the modes are only available when using the mangadap.proc.elric.Elric module. For the w mode, this is simply because the preferred module, mangadap.proc.sasuke.Sasuke, fits the full spectrum instead of fitting the lines within small spectral windows. The other limitation are because mangadap.proc.sasuke.Sasuke is based on the use of template spectra to fit the emission lines (see mangadap.proc.emissionelinetemplates.EmissionLineTemplates): To tie line fluxes, the lines to be tied are included in the same template spectrum, meaning that their kinematics are also automatically tied. That means that, for mangadap.proc.sasuke.Sasuke, the x and a modes are identical.

In the Input Data Format example, the modes set the \({\rm H}\alpha\) line as the “reference” line. I.e., there should always be one line whose mode is f. This requirement is simply practical in setting up the tied parameter structure; there is no more weight given to the fit to the reference line than any other line. The blue [OII] and red [NII] lines have their velocities tied to the \({\rm H}\alpha\) line, all kinematics of the red [OII] line are tied to the blue [OII] line, and all parameters of the blue [NII] line are tied to the red [NII] line with a fixed flux ratio of NII-6550/NII-6585 == 0.34. By virtue of being tied to lines that have their velocites tied to the \({\rm H}\alpha\) line, the velocities of the red [OII] and blue [NII] lines are also tied to the \({\rm H}\alpha\) line. Again, this doesn’t mean that the fit to the \({\rm H}\alpha\) line is given any more weight than any other line, it just means that there is one model parameter that defines the velocity of all lines.

_check()

Check the parameter list:

• Amplitude has to be larger than zero.

• mode must be either 'f', 'wN', 'xN', 'vN', 'sN', 'kN', 'aN'

Todo

• Add check to __setitem__()?

• Add check of profile type

Raises

ValueError – Raised if one of the conditions above are not met.