synthesizer.emissions.line

A module containing functionality for working with emission lines.

Emission lines in Synthesizer are represented by the LineCollection class. This holds a collection of emission lines, each with a rest frame wavelength, a luminosity, and a continuum. The LineCollection class also has the ability to calculate the flux of the lines given a redshift and cosmology, including the observed wavelength and flux density. It also provides a number of helpful conversions and derived properties, such as the equivalent widths, photon energies, and line ratios.

Note that emission lines held by a LineCollection object exist at a specific wavelength and thus don’t account for any broadening effects at this time. To account for broadening effects, Seds including line contribution should be used (i.e. spectra extracted from the “nebular” type on a Grid).

Example usages:

# Create a LineCollection objects
lines = LineCollection(
    line_ids=["O III 5007 A", "H 1 1215.67A"],
    lam=[5007, 1215.67] * angstrom,
    lum=[1e40, 1e39] * erg / s,
    cont=[1e39, 1e38] * erg / s / Hz,
)

# Get the flux of the lines at redshift z=0.1
lines.get_flux(cosmo, z=0.1)

# Get the flux of the lines at redshift z=0.1 with IGM absorption
lines.get_flux(cosmo, z=0.1, igm=Inoue14())

# Get a ratio
lines.get_ratio("R23")

# Get a diagram
lines.get_diagram("OHNO")

Classes

class synthesizer.emissions.line.LineCollection(line_ids, lam, lum, cont, description=None)

A class holding a collection of emission lines.

The LineCollection class holds a collection of emission lines, each with a rest frame wavelength, a luminosity, and a continuum. The LineCollection class also has the ability to calculate the flux of the lines given a redshift and cosmology, including the observed wavelength and flux density. It also provides a number of helpful conversions and derived properties, such as the equivalent widths, photon energies, and line ratios.

Note that emission lines held by a LineCollection object exist at a specific wavelength and thus don’t account for any broadening effects at this time.

line_ids

A list of the line ids.

Type:

list

lam

An array of rest frame line wavelengths.

Type:

unyt_array

luminosity

An array of rest frame line luminosities.

Type:

unyt_array

continuum

An array of rest frame line continuum.

Type:

unyt_array

description

An optional description of the line collection.

Type:

str

obslam

An array of observed line wavelengths.

Type:

unyt_array

flux

An array of line fluxes.

Type:

unyt_array

continuum_flux

An array of line continuum fluxes.

Type:

unyt_array

vacuum_wavelength

An array of vacuum wavelengths.

Type:

unyt_array

available_ratios

A list of the available line ratios based on the lines in the collection.

Type:

list

available_diagrams

A list of the available line diagrams based on the lines in the collection.

Type:

list

nlines

The number of lines in the collection.

Type:

int

apply_attenuation(tau_v, dust_curve, mask=None)

Apply attenuation to this LineCollection.

Parameters:

• tau_v (float/array-like, float) – The V-band optical depth for every star particle.

• dust_curve (synthesizer.emission_models.attenuation.*) – An instance of one of the dust attenuation models. (defined in synthesizer/emission_models.attenuation.py)

• mask (array-like, bool) – A mask array with an entry for each line. Masked out spectra will be ignored when applying the attenuation. Only applicable for multidimensional lines.

Returns:

LineCollection

A new LineCollection object containing the attenuated lines.

concat(*other_lines)

Concatenate LineCollections together.

This will combine the array along the first axis. For example, if we have two LineCollections with LineCollection.shape = (10, 100) and (100, 100) the resulting LineCollection will have shape (110, 100).

This cannot combine LineCollections with different line_ids.

Parameters:

other_lines (LineCollection) – The other LineCollections to concatenate.

Returns:

LineCollection

The concatenated LineCollection.

property cont

Return the continuum of the lines.

This is an alias for the continuum property.

Returns:

continuum (unyt_array)

The continuum of the lines.

property continuum_llam

Return the continuum in units of Llam (erg/s/AA).

Returns:

continuum_llam (unyt_quantity)

The continuum in units of Llam (erg/s/AA).

property elements

Return the elements of the lines.

We relegate this to a property method to reduce the duplication of memory. This is rarely used in expensive use cases and is inexpensive enough that when it is calculating the elements on the fly is not prohibitive.

Returns:

elements (list)

A list of the elements of the lines.

property energy

Get the wavelengths in terms of photon energies in eV.

Returns

energy (unyt_array)

The energy coordinate.

property equivalent_width

Return the equivalent width.

Returns:

equivalent_width (unyt_quantity)

The equivalent width of the line.

extend(*other_lines)

Extend the LineCollection with additional lines.

This will add the lines to the end of the LineCollection. The combined LineCollections must not contain any duplicate lines.

Parameters:

other_lines (LineCollection) – The other LineCollections to extend with.

Returns:

LineCollection

The extended LineCollection.

get_blended_lines(wavelength_bins)

Blend lines based on a set of wavelength bins.

We use a set of wavelength bins to enable the user to control exactly which lines are blended together. This also enables an array to be used emulating an instrument’s resolution.

A simple resolution would lead to ambiguity in situations where A and B are blended, and B and C are blended, but A and C are not.

Parameters:

wavelength_bins (unyt_array) – The wavelength bin edges into which the lines will be blended. Any lines outside the range of the bins will be ignored.

Returns:

LineCollection

A new LineCollection object containing the blended lines.

get_diagram(diagram_id)

Return a pair of line ratios for a given diagram_id (E.g. BPT).

Parameters:

diagram_id (str, list) – Either a diagram_id where the pairs of ratio lines are defined in line_ratios or a list of lists defining the ratios.

Returns:

tuple (float)

a pair of line ratios

get_flux(cosmo, z, igm=None)

Calculate the line flux given a redshift and cosmology.

This will also populate the observed_wavelength attribute with the wavelength of the line when observed.

NOTE: if a redshift of 0 is passed the flux return will be calculated assuming a distance of 10 pc omitting IGM since at this distance IGM contribution makes no sense.

Parameters:

• cosmo (astropy.cosmology.) – Astropy cosmology object.

• z (float) – The redshift.

• igm (igm) – The IGM class. e.g. synthesizer.igm.Inoue14. Defaults to None.

Returns:

flux (unyt_quantity)

Flux of the line in units of erg/s/cm2 by default.

get_flux0()

Calculate the rest frame line flux.

Uses a standard distance of 10pc to calculate the flux.

This will also populate the observed_wavelength attribute with the wavelength of the line when observed (which in the rest frame is the same as the emitted wavelength).

Returns:

flux (unyt_quantity)

Flux of the line in units of erg/s/cm2 by default.

get_ratio(ratio_id)

Measure (and return) a line ratio.

Parameters:

ratio_id (str, list) – Either a ratio_id where the ratio lines are defined in line_ratios or a list of lines.

Returns:

float

a line ratio

property id

Return the line id.

This is an alias to be used when theres a single line id.

Returns:

line_ids (list)

A list of the line ids.

property lum

Return the luminosity of the lines.

This is an alias for the luminosity property.

Returns:

luminosity (unyt_array)

The luminosity of the lines.

property ndim

Get the dimensions of the spectra array.

Returns

Tuple

The shape of self.lnu

property nlam

Get the number of wavelength bins.

Returns

int

The number of wavelength bins.

property nu

Return the frequency of the line.

Returns:

nu (unyt_quantity)

The frequency of the line in Hz.

property obsnu

Return the observed frequency of the line.

Returns:

obsnu (unyt_quantity)

The observed frequency of the line in Hz.

plot_lines(subset=None, figsize=(8, 6), show=False, xlimits=(), ylimits=())

Plot the lines in the LineCollection.

Parameters:

• show (bool) – Whether to show the plot.

• xlimits (tuple) – The x-axis limits. Must be a length 2 tuple. Defaults to (), in which case the default limits are used.

• ylimits (tuple) – The y-axis limits. Must be a length 2 tuple. Defaults to (), in which case the default limits are used.

Returns:

fig (matplotlib.figure.Figure)

The figure object.

ax (matplotlib.axes.Axes)

The axis object.

scale(scaling, inplace=False, mask=None, **kwargs)

Scale the lines by a given factor.

Note: this will only scale the rest frame continuum and luminosity. To get the scaled flux get_flux must be called on the new Line object.

Parameters:

• scaling (float) – The factor by which to scale the line.

• inplace (bool) – If True the Line object will be scaled in place, otherwise a new Line object will be returned.

• mask (array-like, bool) – A mask array with an entry for each line. Masked out spectra will not be scaled. Only applicable for multidimensional lines.

Returns:

LineCollection

A new LineCollection object containing the scaled lines, unless inplace is True in which case the LineCollection object will be scaled in place.

property shape

Get the shape of the spectra array.

Returns

Tuple

The shape of self.lnu

sum(axis=None)

Sum the lines in the collection.

Parameters:

axis (int/tuple) – The axis/axes to sum over. By default this will sum over all but the final axis (the axis containing different lines).

property vacuum_wavelengths

Return the vacuum wavelengths of the lines.

We relegate this to a property method to reduce the duplication of memory. This is rarely used in expensive use cases and is inexpensive enough that when it is calculating the vacuum wavelengths on the fly is not prohibitive.

Returns:

vacuum_wavelengths (unyt_array)

The vacuum wavelengths of the lines.