lightcurvelynx.models.lightcurve_template_model

Model that generate the SED or bandflux of a source based on given observer frame light curves of fluxes in each band.

If we are generating the bandfluxes directly, the models interpolate the given light curves at the requested times and filters. If we are generating an SED for a given set of wavelengths, the model computes a box-shaped SED basis function for each filter that will produce the same bandflux after being passed through the passband filter.

Note: If you are interested in generating SED-level data, use the SEDTemplateModel in src/lightcurvelynx/models/sed_template_model.py instead.

Attributes

logger

Classes

LightcurveBandData	A class to hold data for a single model light curve defined at the band level (a set of
BaseLightcurveBandTemplateModel	A base class for light curve template models. This class is not meant to be used directly,
LightcurveTemplateModel	A model that generates either the SED or bandflux of a source based on
MultiLightcurveTemplateModel	A MultiLightcurveTemplateModel either randomly or programmatically selects a light

Module Contents

logger

class LightcurveBandData(lightcurves, lc_data_t0, *, periodic=False, magnitudes_in=False, baseline=None)

A class to hold data for a single model light curve defined at the band level (a set of fluxes over time for each filter).

Data can be passed in as fluxes (in nJy) or AB magnitudes (if magnitudes_in=True), but is always stored internally as fluxes.

lightcurves

A dictionary mapping filter names to a 2D array of the bandfluxes in that filter, where the first column is time (in days from the reference time of the light curve), the second column is the bandflux (in nJy), and an optional third column is fluxerror.

Type:

dict

lc_data_t0

The reference epoch of the input light curve. This is the time stamp of the input array that will correspond to t0 in the model. For periodic light curves, this either must be set to the first time of the light curve or set as 0.0 to automatically derive the lc_data_t0 from the light curve.

Type:

float

period

The period of the light curve in days. If the light curve is not periodic, then this value is set to None.

Type:

float or None

min_times

A dictionary mapping filter names to the minimum time of the light curve in that filter (shifted to be relative to the reference epoch of the light curve).

Type:

dict

max_times

A dictionary mapping filter names to the maximum time of the light curve in that filter (shifted to be relative to the reference epoch of the light curve).

Type:

dict

baseline

A dictionary of baseline bandfluxes for each filter (in nJy). This is only used for non-periodic light curves when they are not active.

Type:

dict

has_time_bounds

Whether the model has time bounds where it is valid. This is True for non-periodic light curves without a baseline, and False otherwise.

Type:

bool

Parameters:

• lightcurves (dict or numpy.ndarray) –

  The light curves can be passed as either:

  1. a dictionary mapping filter names to a (T, 2) array of the bandfluxes in that filter where the first column is time and the second column is the light curve values, or

  2. a numpy array of shape (T, 3) array where the first column is time (in days), the second column is the light curve values, and the third column is the filter. The light curve values can be either fluxes (in nJy) or AB magnitudes (if magnitudes_in=True).

• lc_data_t0 (float) – The reference epoch of the input light curve. The model will be shifted to the model’s lc_data_t0 when computing fluxes. For periodic light curves, this either must be set to the first time of the light curve or as 0.0 to automatically derive the lc_data_t0 from the light curve.

• periodic (bool) – Whether the light curve is periodic. If True, the model will assume that the light curve repeats every period. Default: False

• magnitudes_in (bool) – Whether the input light curves are in AB magnitudes (True) or fluxes (False).

• baseline (dict or None) – A dictionary of baseline bandfluxes or AB magnitudes for each filter. This is only used for non-periodic light curves when they are not active. Default: None

lc_data_t0

period = None

min_times

max_times

has_time_bounds

__len__()

Get the number of light curves.

property filters

Get the list of filters in the lightcurves.

classmethod from_lclib_table(lightcurves_table, *, forced_lc_t0=None, filters=None)

Break up a light curves table in LCLIB format into a LightcurveBandData instance. This function expects the table to have a “time” column, an optional “type” column, and a column for each filter. The “type” column should use “S” for source observation and “T” for template (background) observation.

Parameters:

• lightcurves_table (astropy.table.Table) – A table with a “time” column, optional “type” column, and a column for each filter. If the type column is present it should use “S” for source observation and “T” for template (background) observation.

• forced_lc_t0 (float) – By default we use the LCLIB convention of storing the light curves so the first time corresponds to the reference epoch (lc_data_t0) of the light curve. This can be overridden by providing a value for forced_lc_t0. Default: None

• filters (list of str or None) – A list of filters to use for the light curves. If None, all filters will be used. Used to select a subset of filters. Default: None

evaluate_bandfluxes(times, filter)

Get the bandflux values for a given filter at the specified times. These can be multiplied by a basis SED function to produce estimated SED values for the given filter at the specified times or can be used directly as bandfluxes.

Parameters:

• times (numpy.ndarray) – A length T array of times (in days) at which to compute the SED values. These should be shift to be relative to the light curve’s lc_data_t0.

• filter (str) – The name of the filter for which to compute the SED values.

Returns:

values – A length T array of bandpass fluxes for the specified filter at the given times.

Return type:

numpy.ndarray

plot_lightcurves(times=None, ax=None, figure=None)

Plot the underlying light curves. This is a debugging function to help the user understand the SEDs produced by this model.

Parameters:

• times (numpy.ndarray or None, optional) – An array of timestamps at which to plot the light curves. If None, the function uses the timestamps from each light curve.

• ax (matplotlib.pyplot.Axes or None, optional) – Axes, None by default.

• figure (matplotlib.pyplot.Figure or None) – Figure, None by default.

class BaseLightcurveBandTemplateModel(*, passbands=None, filters=None, **kwargs)

Bases: lightcurvelynx.models.physical_model.BandfluxModel, abc.ABC

A base class for light curve template models. This class is not meant to be used directly, but rather as a base for other light curve template models that may have additional functionality. It provides the basic structure (primarily SED basis functions) and validation for light curve-based SED models.

The set of passbands used to configure the model MUST be the same as used to generate the SED (the wavelengths must match).

Parameterized values include:

• dec - The object’s declination in degrees.

• ra - The object’s right ascension in degrees.

• t0 - The t0 of the zero phase (if applicable), date.

sed_basis

An SEDBasisModel mapping representing the fake SED basis functions for each filter. Only generated if passbands are provided.

Type:

SEDBasisModel, optional

Parameters:

• passbands (Passband or PassbandGroup, optional) – The passband or passband group to use for defining the light curve. If provided, they will be used to create box-shaped SED basis functions for each filter.

• filters (list, optional) – A list of filter names that the model supports. If None then all available filters will be used.

compute_sed_given_lc(lc, times, wavelengths, graph_state)

Compute the flux density for a given light curve at specified times and wavelengths.

Parameters:

• lc (LightcurveBandData) – The light curve data to use for computing the flux density.

• times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.

• wavelengths (numpy.ndarray, optional) – A length N array of observer frame wavelengths (in angstroms).

• graph_state (GraphState) – An object mapping graph parameters to their values.

Returns:

flux_density – A length T x N matrix of observer frame SED values (in nJy).

Return type:

numpy.ndarray

plot_sed_basis(ax=None, figure=None)

Plot the basis functions for the SED. This is a debugging function to help the user understand the SEDs produced by this model.

Parameters:

• ax (matplotlib.pyplot.Axes or None, optional) – Axes, None by default.

• figure (matplotlib.pyplot.Figure or None) – Figure, None by default.

class LightcurveTemplateModel(lightcurves, passbands, lc_data_t0, *, periodic=False, baseline=None, **kwargs)

Bases: BaseLightcurveBandTemplateModel

A model that generates either the SED or bandflux of a source based on given light curves in each band. When generating the bandflux, it interpolates the light curves directly. When generating the SED, the model uses a box-shaped SED for each filter such that the resulting flux density is equal to the light curve’s value after passing through the passband filter.

LightcurveTemplateModel supports both periodic and non-periodic light curves. If the light curve is not periodic then each light curve’s given values will be interpolated during the time range of the light curve. Values outside the time range (before and after) will be set to the baseline value for that filter (0.0 by default).

Periodic models require that each filter’s light curve is sampled at the same times and that the value at the end of the light curve is equal to the value at the start of the light curve. The light curve epoch (lc_data_t0) is automatically set to the first time so that the t0 parameter corresponds to the shift in phase.

The set of passbands used to configure the model MUST be the same as used to generate the SED (the wavelengths must match).

Parameterized values include:

• dec - The object’s declination in degrees.

• ra - The object’s right ascension in degrees.

• t0 - The t0 of the zero phase (if applicable), date.

Note

If you are interested in generating SED-level data, use the SEDTemplateModel in src/lightcurvelynx/models/sed_template_model.py instead.

lightcurves

The data for the light curves, such as the times and bandfluxes in each filter.

Type:

LightcurveBandData

sed_values

A dictionary mapping filters to the SED basis values for that passband. These SED values are scaled by the light curve and added for the final SED.

Type:

dict

filters

The list of filters in the light curves.

Type:

list

Parameters:

• lightcurves (dict or numpy.ndarray) –

  The light curves can be passed as either:

  1. a LightcurveBandData instance,

  2. a dictionary mapping filter names to a (T, 2) array of the bandlfuxes in that filter where the first column is time and the second column is the flux density (in nJy), or

  3. a numpy array of shape (T, 3) array where the first column is time (in days), the second column is the bandflux (in nJy), and the third column is the filter.

• passbands (Passband or PassbandGroup or None) – The passband or passband group to use for defining the light curve. If provided (not None), these will be used to create box-shaped SED basis functions for each filter.

• lc_data_t0 (float) – The reference epoch of the input light curve. This is the time stamp of the input array that will correspond to t0 in the model. For periodic light curves, this either must be set to the first time of the light curve or set as 0.0 to automatically derive the lc_data_t0 from the light curve.

• periodic (bool) – Whether the light curve is periodic. If True, the model will assume that the light curve repeats every period. Default: False

• baseline (dict or None) – A dictionary of baseline bandfluxes for each filter. This is only used for non-periodic light curves when they are not active. Default: None

filters

minphase(filter=None, **kwargs)

Get the minimum supported phase of the model (for this filter) in days.

Parameters:

• filter (str) – The name of the filter (required). An error is raised if no value is provided.

• **kwargs (dict) – Additional keyword arguments, not used in this method.

Returns:

minphase – The minimum phase of the model (in days) or None if the model does not have a defined minimum phase.

Return type:

float or None

maxphase(filter=None, **kwargs)

Get the maximum supported phase of the model (for this filter) in days.

Parameters:

• filter (str) – The name of the filter (required). An error is raised if no value is provided.

• graph_state (GraphState, optional) – An object mapping graph parameters to their values. If provided, the function will use the graph state to compute the maximum wavelength.

• **kwargs (dict) – Additional keyword arguments, not used in this method.

Returns:

maximum – The maximum phase of the model (in days) or None if the model does not have a defined maximum phase.

Return type:

float or None

compute_sed(times, wavelengths, graph_state)

Draw effect-free observer frame flux densities.

Parameters:

• times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.

• wavelengths (numpy.ndarray, optional) – A length N array of observer frame wavelengths (in angstroms).

• graph_state (GraphState) – An object mapping graph parameters to their values.

Returns:

flux_density – A length T x N matrix of observer frame SED values (in nJy). These are generated from non-overlapping box-shaped SED basis functions for each filter and scaled by the light curve values.

Return type:

numpy.ndarray

compute_bandflux(times, filter, state, **kwargs)

Evaluate the model at the passband level for a single, given graph state.

Parameters:

• times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.

• filter (str) – The name of the filter.

• state (GraphState) – An object mapping graph parameters to their values with num_samples=1.

• **kwargs (dict) – Additional keyword arguments, not used in this method.

Returns:

bandfluxes – A length T matrix of observer frame passband fluxes (in nJy).

Return type:

numpy.ndarray

plot_lightcurves(times=None, ax=None, figure=None)

Plot the underlying light curves. This is a debugging function to help the user understand the SEDs produced by this model.

Parameters:

• times (numpy.ndarray or None, optional) – An array of timestamps at which to plot the light curves. If None, the function uses the timestamps from each light curve.

• ax (matplotlib.pyplot.Axes or None, optional) – Axes, None by default.

• figure (matplotlib.pyplot.Figure or None) – Figure, None by default.

class MultiLightcurveTemplateModel(lightcurves, passbands=None, *, weights=None, indices=None, **kwargs)

Bases: BaseLightcurveBandTemplateModel

A MultiLightcurveTemplateModel either randomly or programmatically selects a light curve at each evaluation and computes the flux from that source. If the ‘indices’ parameter is provided, the model uses those indices to select the light curve (in order). Otherwise, the model randomly samples from the available light curves (with replacement).

The models can generate either the SED or bandflux of a source based of given light curves in each band. When generating the bandflux, the model interpolates the light curves directly. When generating the SED, the model uses a box-shaped SED for each filter such that the resulting flux density is equal to the light curve’s value after passing through the passband filter.

MultiLightcurveTemplateModel supports both periodic and non-periodic light curves. If the light curve is not periodic then each light curve’s given values will be interpolated during the time range of the light curve. Values outside the time range (before and after) will be set to the baseline value for that filter (0.0 by default).

Periodic models require that each filter’s light curve is sampled at the same times and that the value at the end of the light curve is equal to the value at the start of the light curve. The light curve epoch is automatically set to the first time so that the t0 parameter corresponds to the shift in phase.

The set of passbands used to configure the model MUST be the same as used to generate the SED (the wavelengths must match).

Parameterized values include:

• dec - The object’s declination in degrees.

• ra - The object’s right ascension in degrees.

• t0 - The t0 of the zero phase (if applicable), date.

lightcurves

The data for each set of light curves.

Type:

list of LightcurveBandData

sed_values

A dictionary mapping filters to the SED basis values for that passband. These SED values are scaled by the light curve and added for the final SED.

Type:

dict

all_filters

A set of all filters used by the light curves. This is the union of all filters used by each light curve in the lightcurves list.

Type:

set

Parameters:

• lightcurves (list of LightcurveBandData) – The data for each set of light curves. One light curve will be randomly selected at each evaluation.

• passbands (Passband or PassbandGroup or None, optional) – The passband or passband group to use for defining the light curve. If provided (not None), these will be used to create box-shaped SED basis functions for each filter. Default: None

• weights (numpy.ndarray, optional) – A length N array indicating the relative weight from which to select a light curve at random. Cannot be used if the ‘indices’ parameter is provided. If None, all light curves will be weighted equally. Default: None

• indices (parameter, list, or numpy.ndarray, optional) – An array-like parameter that provides the indices of the light curves to select. If provided, the model will use these indices to select the light curves instead of sampling randomly. Default: None

filters = []

lightcurves

__len__()

Get the number of light curves.

classmethod from_lclib_file(lightcurves_file, passbands, *, forced_lc_t0=None, filters=None, **kwargs)

Create a MultiLightcurveTemplateModel from a light curves file in LCLIB format.

Parameters:

• lightcurves_file (str) – The path to the light curves file in LCLIB format.

• passbands (Passband or PassbandGroup) – The passband or passband group to use for defining the light curve.

• forced_lc_t0 (float or ndarray, optional) – By default we use the LCLIB convention of storing the light curves so the first time corresponds to the reference epoch (lc_data_t0) of the light curve. This can be overridden by providing a value for forced_lc_t0. Default: None

• filters (list of str, optional) – A list of filters to use for the light curves. If None, all filters will be used. Used to select a subset of filters that match the survey to simulate. Default: None

• **kwargs – Additional keyword arguments to pass to the LightcurveBandData constructor, including the parameters for the model such as dec, ra, and t0 and metadata such as node_label.

Returns:

An instance of MultiLightcurveTemplateModel with the loaded light curves.

Return type:

MultiLightcurveTemplateModel

minphase(filter=None, graph_state=None, **kwargs)

Get the minimum supported phase of the model (for this filter) in days.

Parameters:

• filter (str) – The name of the filter (required). An error is raised if no value is provided.

• graph_state (GraphState, optional) – An object mapping graph parameters to their values. If provided, the function will use the graph state to compute the minimum wavelength.

• **kwargs (dict) – Additional keyword arguments, not used in this method.

Returns:

minphase – The minimum phase of the model (in days) or None if the model does not have a defined minimum phase.

Return type:

float or None

maxphase(filter=None, graph_state=None, **kwargs)

Get the maximum supported phase of the model (for this filter) in days.

Parameters:

• filter (str) – The name of the filter (required). An error is raised if no value is provided.

• graph_state (GraphState, optional) – An object mapping graph parameters to their values. If provided, the function will use the graph state to compute the maximum wavelength.

• **kwargs (dict) – Additional keyword arguments, not used in this method.

Returns:

maximum – The maximum phase of the model (in days) or None if the model does not have a defined maximum phase.

Return type:

float or None

compute_sed(times, wavelengths, graph_state)

Draw effect-free observer frame flux densities.

Parameters:

• times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.

• wavelengths (numpy.ndarray, optional) – A length N array of observer frame wavelengths (in angstroms).

• graph_state (GraphState) – An object mapping graph parameters to their values.

Returns:

flux_density – A length T x N matrix of observer frame SED values (in nJy). These are generated from non-overlapping box-shaped SED basis functions for each filter and scaled by the light curve values.

Return type:

numpy.ndarray

compute_bandflux(times, filter, state, **kwargs)

Evaluate the model at the passband level for a single, given graph state.

Parameters:

• times (numpy.ndarray) – A length T array of observer frame timestamps in MJD.

• filter (str) – The name of the filter.

• state (GraphState) – An object mapping graph parameters to their values with num_samples=1.

• **kwargs (dict) – Additional keyword arguments, not used in this method.

Returns:

bandfluxes – A length T matrix of observer frame passband fluxes (in nJy).

Return type:

numpy.ndarray