Lightning

class lightning.Lightning

The main interface for fitting a galaxy SED model.

Holds information about the filters, observed flux, type of model. Model components are set by keyword choices.

The only strictly required parameters are filter_labels and one of redshift or lum_dist. For inference/fitting, both flux_obs and flux_unc must also be set.

Parameters:

filter_labelslist, str

List of filter labels.

redshiftfloat

Redshift of the model. If set, lum_dist is ignored. (Default: None)

lum_distfloat

Luminosity distance to the model. If redshift is not set, this parameter must be. If a luminosity distance is provided instead of a redshift, the redshift is set to 0 (as we assume the galaxy is very nearby). (Default: None)

flux_obsnp.ndarray, (Nfilters,) or (Nfilters, 2), float32, optional

The observed flux densities in mJy, or, optionally, the observed flux densities and associated uncertainties as a 2D array. (Default: None)

flux_uncnp.ndarray, (Nfilters,), float32, optional

The uncertainties associated with flux_obs, in mJy. (Default: None)

wave_gridtuple (3,), or np.ndarray, (Nwave,), float32, optional

Either a tuple of (lo, hi, Nwave) specifying a log-spaced rest-frame wavelength grid, or an array giving the wavelengths directly. (Default: (0.1, 1000, 1200))

stellar_type{‘PEGASE’, ‘PEGASE-A24’, ‘BPASS’, ‘BPASS-A24’, ‘BPASS-ULX-G24’}

String specifying the simple stellar population models to use. ‘PEGASE’ gives the stellar population models used in IDL Lightning (Doore+2023). (Default: ‘PEGASE’)

line_labelsnp.ndarray, (Nlines,), string, optional

Line labels in the format used by pyCloudy. See lightning/models/linelist_full.txt for the complete list of available lines in the grid and their format. (Default: None)

line_fluxnp.ndarray, (Nlines,) or (Nlines, 2), float32, optional

Observed integrated fluxes of the lines in erg cm-2 s-1 (unless the line_index keyword is set, in which case they should be normalized by the appropriate line). (Default: None)

line_flux_uncnp.ndarray,(Nlines,), float32, optional

Uncertainties on the integrated line fluxes in erg cm-2 s-1 (unless line_index is set, see above) (Default: None)

line_indexstring

Label for the line to index the line fluxes by. You would normally want this to be 'H__1_486132A' or 'H__1_656280A' for Hbeta and Halpha, respectively, but the highest SNR line could be a good choice. If this is set to None then the model line fluxes are not normalized for fitting. (Default: None)

nebula_lognHfloat

log of the Hydrogen density in cm-3 for the Cloudy grids. (Default: 2.0)

nebula_dustbool

If True, then dust grains are included in the Cloudy grids. (Default: False)

SFH_type{‘Piecewise-Constant’, ‘Delayed-Exponential’, ‘Single-Exponential’, ‘Burst’}

String specifying the SFH type to use. (Default: ‘Piecewise-Constant’)

agesnp.ndarray, (Nages,), float32

Array giving the stellar ages (or stellar age bins) of the stellar population models. Default depends on the model and redshift.

atten_type{‘Modified-Calzetti’, ‘Calzetti’}

String specifying the dust attenuation model to use. (Default: ‘Modified-Calzetti’)

dust_emissionbool

If True, a Draine & Li (2007) dust emission model is included, in energy balance with the attenuated power. (Default: False)

agn_emissionbool

If True, a Stalevski et al. (2016) UV-IR AGN emission model is included. (Default: False)

agn_polar_dustbool

If True, AGN polar dust extinction and re-emission are implemented following the recipe from X-Cigale. Note that even if this keyword is set to False, the polar dust optical depth remains a parameter of the model - it just doesn’t do anything, and should held at 0 in any fitting. (Default: False)

xray_mode{‘flux’, ‘counts’, ‘None’, None}

String specifying the mode for X-ray model fitting - fluxes are fit like any other point in the SED, while counts are folded through the instrumental response. Expect counts mode to be more flexible but harder to set up. If you are fitting X-ray data from multiple instruments simultaneously, you must set this to ‘flux’ (and should convert your instrumental countrates to fluxes assuming the same spectrum for every instrument). (Default: None)

xray_stellar_emission{‘Stellar-Plaw’, ‘None’, None}

String specifying the X-ray stellar model. Currently the only available model is ‘Stellar-Plaw’, which uses the Gilbertson+(2022) LX-stellar age scaling relation to calculate the luminosity. (Default: None)

xray_agn_emission{‘AGN-Plaw’, ‘QSOSED’, ‘None’, None}

String specifying the X-ray AGN model. The ‘AGN-Plaw’ model is a power law sclaed by the Lusso & Risaliti (2017) empirical L2500-L2keV relationship; the QSOSED model is a theoretical accretion disk + comptonization model that sets the normalization of the whole X-ray-to-IR AGN model as a function of M and mdot. (Default: None)

xray_absorption{‘tbabs’, ‘phabs’, ‘None’, None}

String specifying the X-ray absorption model to use. Two instances are used, one in the rest frame describing the intrinsic absorption, and one in the observed frame with a constant Galactic NH. (Default: None)

xray_wave_gridtuple (3,), or np.ndarray, (Nwave,), float32, optional

Either a tuple of (lo, hi, Nwave) specifying a log-spaced rest-frame wavelength grid, or an array giving the wavelengths directly. At high redshift this should be constructed carefully to ensure that your bands are covered. (Default: (1e-6, 1e-1, 200))

xray_arfdict or astropy.table.Table or numpy structured array

A structure defining the anciliary response function (ARF) of your X-ray observations. The structure must have three keys, ‘ENERG_LO’, ‘ENERG_HI’, and ‘SPECRESP’, which given the energy bins and binned spectral response respectively. Only used if xray_mode=’counts’`. (Default: None)

xray_exposurefloat or np.ndarray (Nfilters)

A scalar or array giving the exposure time of the X-ray observations. If an array, it should have the same length as filter_labels, with all non-X-ray bands having their exposure time set to 0. Note that you almost certainly don’t need to give exposure time as an array, since the energy dependence of the effective area is explicitly given by the ARF. Only used if xray_mode='counts'. (Default: None)

galactic_NHfloat

A scalar giving the Galactic column density along the line of sight to the source in 1e20 cm-2. (Default: 0.0)

print_setup_timebool

If True, the setup time will be printed. (Default: False)

model_uncnp.ndarray, (Nfilters,), float, or float

Fractional (i.e. [0,1)) model uncertainty to include in the fits. If a scalar is provided, the same model uncertainty is applied to each filter. Alternately, model uncertainties can be provided as an array, one per filter. The smarter way to do this in the future may be to set model uncertainties per component, rather than per filter. (Default: None)

model_unc_linesnp.ndarray, (Nlines,), float, or float

Fractional (i.e. [0,1)) model uncertainty to include in the line fits. (Default: None)

cosmologyastropy.cosmology.FlatLambdaCDM

The cosmology to assume. Lightning defaults to a flat cosmology with h=0.7 and Om0=0.3.

uplim_handling{‘exact’, ‘approx’}

A string specifying how upper limits are to be handled. In the case of ‘exact’ we treat them as derived in e.g. Appendix A of Sawicki et al. (2012). In the case of ‘approx’, upper limits are treated as measurements of 0 with a 1 sigma uncertainty equal to the 1 sigma flux limit. This option is provided for consistency with the handling of limits in IDL lightning. Our convention for inputting upper limits remains that they should be specified as a measurement of 0 with a 1 sigma uncertainty equal to the 1 sigma flux limit. (Default: ‘exact’)

Attributes:

flux_obs

Observed flux-densities in mJy.

flux_unc

Uncertainties associated with flux_obs.

Lnu_obsNone or numpy.ndarray, (Nfilters,), float32

Observed-frame luminosity densities, converted from the given fluxes.

Lnu_uncNone or numpy.ndarray, (Nfilters,), float32

Uncertainties associated with Lnu_obs.

filter_labelslist, str

List of filter labels.

filtersdict, len=Nfilters, float32

A dict of numpy float32 arrays. The keys are filter_labels and the values correspond to the normalized transmission evaluated on wave_grid.

wave_obsnumpy.ndarray, (Nfilters,), float32

Mean wavelength of the the supplied filters.

redshiftfloat

Redshift of the model. Assumed to be 0 if lum_dist was set.

DLfloat

Luminosity distance to the model, in Mpc

wave_grid_restnumpy.ndarray, (Nwave,), float32

Unified rest-frame wavelength grid for the models.

wave_grid_obs

nu_grid_rest

nu_grid_obs

path_to_filtersstr

The path (relative or absolute, should just make it absolute) to the top filter directory.

model_unc

Methods

chain_plot(samples, **kwargs)	Make chain plot.
corner_plot(samples, **kwargs)	Make corner plot.
fit(p0, **kwargs)	Fit the model to the data.
from_json(fname)	Construct a Lightning object with the configuration specified by a json file.
get_mcmc_chains(sampler[, thin, discard, ...])	Reduce the emcee sampler object into chains.
get_model_components_lnu_hires(params[, ...])	Construct the individual components of the high-resolution spectral model.
get_model_likelihood(params[, negative])	Calculate the log-likelihood of the model under the given parameters.
get_model_lines(params[, stepwise])	Construct the absorbed and intrinsic model lines.
get_model_lnu(params[, stepwise])	Construct the low-resolution SED model.
get_model_lnu_hires(params[, stepwise])	Construct the high-resolution spectral model.
get_model_log_prob(params[, priors, ...])	Calculate the log-probability of the model under the given parameters.
get_xray_model_counts(params)	Construct the low-resolution X-ray instrumental SED.
get_xray_model_lnu(params)	Construct the low-resolution X-ray SED model.
get_xray_model_lnu_hires(params)	Construct the high-resolution X-ray spectral model.
print_params([verbose])	Print all the parameters of the current model.
save_json(fname)	Save the information needed to reconstruct this Lightning object to a json file.
save_pickle(fname)	Save this whole Lightning object to a pickle.
sed_plot_bestfit(samples, logprob_samples, ...)	Make plot of the best-fitting SED.
sed_plot_delchi(samples, logprob_samples, ...)	Make residual plot.
sfh_plot(samples, **kwargs)	Make SFH plot.

__init__(filter_labels, redshift=None, lum_dist=None, flux_obs=None, flux_obs_unc=None, wave_grid=(0.1, 1000, 1200), stellar_type='PEGASE', line_labels=None, line_flux=None, line_flux_unc=None, line_index=None, nebula_lognH=2.0, nebula_dust=False, SFH_type='Piecewise-Constant', ages=None, atten_type='Modified-Calzetti', dust_emission=False, agn_emission=False, agn_polar_dust=False, xray_mode=None, xray_stellar_emission=None, xray_agn_emission=None, xray_absorption=None, xray_wave_grid=(1e-06, 0.1, 200), xray_arf=None, xray_exposure=None, galactic_NH=0.0, print_setup_time=False, model_unc=None, model_unc_lines=None, cosmology=None, uplim_handling='approx')

chain_plot(samples, **kwargs)

Make chain plot.

See lightning.plots.chain_plot

corner_plot(samples, **kwargs)

Make corner plot.

See lightning.plots.corner_plot

fit(p0, **kwargs)

Fit the model to the data.

Parameters:

p0np.ndarray, (Nwalkers, Nparam) or (Nparam,), float32

Initial parameters. In the case of the affine invariant MCMC sampler, this should be a 2D array initializing the entire ensemble.

method{‘emcee’, ‘optimize’}

Fitting method.

Returns:

emcee ensemble sampler object or scipy.opt.minimize result, depending on

method.

property flux_obs

Observed flux-densities in mJy.

Flux densities are converted to observed-frame luminosity densities.

property flux_unc

Uncertainties associated with flux_obs.

Flux densities are converted to observed-frame luminosity densities.

static from_json(fname)

Construct a Lightning object with the configuration specified by a json file.

This was a nice idea when the model was simple enough that it could just be Lightning(**config) but now it’s kind of a nightmare. Should move to binary only. Or come up with a better scheme for ascii serialization, so that I don’t have to update this function every time I change anything about the model.

get_mcmc_chains(sampler, thin=None, discard=None, flat=True, Nsamples=1000, const_dim=None, const_vals=None)

Reduce the emcee sampler object into chains.

Parameters:

sampleremcee.EnsembleSampler

Sampler from completed MCMC run, as returned by lightning.fit(method=’emcee’)

thinint

Thin factor for chains. Note that None means that the thin factor will be determined from the autocorrelation time; if you instead want no thinning, use thin=1. (Default: None)

discardint

Number of trials (i.e. burn-in) to discard from the beginning of MCMC chains. Note that None means that the burn-in will be determined from the autocorrelation time; if you instead want no discard, use discard=0. (Default: None)

flatbool

If True, collapse the ensemble sampler to a single MCMC chain. Otherwise one chain per walker is retained (Default: True)

Nsamplesint

Number of posterior samples to retain after discarding/thinning/flattening (Default: 1000)

const_dimnp.array, boolean

An array of length Nparams showing which model parameters were constant (since emcee doesn’t know anything about these dimensions, we must provide them separately). If None, these dimensions will be excluded from the output (as if there were no constant dimensions).

const_valsnp.array, float

An array giving the values of the constant model parameters, if any.

Returns:

samplesnp.ndarray(Nsamples, Nparam)

Sampled posterior chain(s) for parameters.

logprob_samplesnp.ndarray(Nsamples, Nparam)

Sampled logprob chain(s).

tnp.ndarray(Nparams,)

Autocorrelation time computed before thinning and discarding burn-in. Preserved as a diagnostic, since it sets the scale for thinning and burn-in.

get_model_components_lnu_hires(params, stepwise=False)

Construct the individual components of the high-resolution spectral model.

This function returns a dictionary (or an array, I haven’t decided yet) containing the indiviudal model components interpolated to the same wavelength grid.

Parameters:

paramsnp.ndarray(Nmodels, Nparams) or np.ndarray(Nparams)

An array of model parameters. For purposes of vectorization this can be a 2D array, where the first dimension cycles over different sets of parameters.

stepwisebool

If true, this function returns the spectral model as a function of stellar age.

Returns:

hires_modelsdict

Keys are {‘stellar_attenuated’, ‘stellar_unattenuated’, ‘attenuation’, ‘dust’, ‘agn’} where ‘dust’ and ‘agn’ are only included if the model includes these components. Each key points to a numpy array containing the high-resolution models.

get_model_likelihood(params, negative=True)

Calculate the log-likelihood of the model under the given parameters.

If negative flag is set (on by default), returns the negative log likelihood (i.e. chi2 / 2).

Parameters:

paramsnp.ndarray(Nmodels, Nparams)

An array of the parameters expected by the model. See Lightning.print_params() for details on the current model parameters.

negativebool

A flag setting whether the log probability or its opposite is returned (as e.g. when using a minimization method). (Default: True)

Returns:

log_likenp.ndarray(Nmodels,)

The log of the likelihood.

get_model_lines(params, stepwise=False)

Construct the absorbed and intrinsic model lines.

Only available if the model has lines

Parameters:

paramsnp.ndarray(Nmodels, Nparams) or np.ndarray(Nparams)

An array of model parameters. For purposes of vectorization this can be a 2D array, where the first dimension cycles over different sets of parameters.

stepwisebool

If true, this function returns the spectral model as a function of stellar age.

Returns:

lines_extnp.ndarray(Nmodels, Nlines) or np.ndarray(Nmodels, Nlines, Nages)

Model line luminosities in Lsun after multiplication by the galaxy attenuation curve.

lnu_intrinsicnp.ndarray(Nmodels, Nlines) or np.ndarray(Nmodels, Nlines, Nages)

Intrinsic model line luminosities in Lsun.

get_model_lnu(params, stepwise=False)

Construct the low-resolution SED model.

Parameters:

paramsnp.ndarray(Nmodels, Nparams) or np.ndarray(Nparams)

An array of model parameters. For purposes of vectorization this can be a 2D array, where the first dimension cycles over different sets of parameters.

stepwisebool

If true, this function returns the spectral model as a function of stellar age.

Returns:

lnu_processednp.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

Model including the effects of ISM dust, convolved with the filters.

lnu_intrinsicnp.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

Model not including the effects of ISM dust, convolved with the filters.

get_model_lnu_hires(params, stepwise=False)

Construct the high-resolution spectral model.

Parameters:

paramsnp.ndarray(Nmodels, Nparams) or np.ndarray(Nparams)

An array of model parameters. For purposes of vectorization this can be a 2D array, where the first dimension cycles over different sets of parameters.

stepwisebool

If true, this function returns the spectral model as a function of stellar age.

Returns:

lnu_processednp.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

High resolution spectral model including the effects of ISM dust.

lnu_intrinsicnp.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

High resolution spectral model not including the effects of ISM dust.

get_model_log_prob(params, priors=None, negative=True, p_bound=inf)

Calculate the log-probability of the model under the given parameters.

If negative flag is set (on by default), returns the negative log probability (i.e. chi2 / 2 + log(prior)).

Parameters:

paramsnp.ndarray(Nmodels, Nparams)

An array of the parameters expected by the model. See Lightning.print_params() for details on the current model parameters.

priorslist of Nparams callables

Priors on the parameters.

negativebool

A flag setting whether the log probability or its opposite is returned (as e.g. when using a minimization method). (Default: True)

p_boundfloat

The magnitude of the log probability for models outside of the parameter space. (Default: np.inf)

Returns:

log_probnp.ndarray(Nmodels,)

The log of the probability, prior * likelihood.

get_xray_model_counts(params)

Construct the low-resolution X-ray instrumental SED.

Parameters:

paramsnp.ndarray(Nmodels, Nparams) or np.ndarray(Nparams)

An array of model parameters. For purposes of vectorization this can be a 2D array, where the first dimension cycles over different sets of parameters.

Returns:

counts_absorbednp.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

Model including the effects of the chosen absorption model, convolved with the filters.

counts_unabsorbednp.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

Model not including the effects of the chosen absorption model, convolved with the filters.

get_xray_model_lnu(params)

Construct the low-resolution X-ray SED model.

Parameters:

paramsnp.ndarray(Nmodels, Nparams) or np.ndarray(Nparams)

An array of model parameters. For purposes of vectorization this can be a 2D array, where the first dimension cycles over different sets of parameters.

Returns:

lnu_absorbednp.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

Model including the effects of the chosen absorption model, convolved with the filters.

lnu_unabsorbednp.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

Model not including the effects of the chosen absorption model, convolved with the filters.

get_xray_model_lnu_hires(params)

Construct the high-resolution X-ray spectral model.

Parameters:

paramsnp.ndarray(Nmodels, Nparams) or np.ndarray(Nparams)

An array of model parameters. For purposes of vectorization this can be a 2D array, where the first dimension cycles over different sets of parameters.

stepwisebool

If true, this function returns the spectral model as a function of stellar age.

Returns:

lnu_absorbed: np.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

High resolution spectral model including the effects of the chosen absorption model.

lnu_unabsorbednp.ndarray(Nmodels, Nwave) or np.ndarray(Nmodels, Nwave, Nages)

High resolution spectral model not including the effects of the chosen absorption model.

property line_flux

Observed line fluxes in erg cm-2 s-1.

Fluxes are converted to apparent luminosities.

property line_flux_unc

Observed line fluxes in erg cm-2 s-1.

Fluxes are converted to apparent luminosities.

print_params(verbose=False)

Print all the parameters of the current model.

If verbose, print a nicely formatted table of the models, their parameters, and the description of the parameters. Otherwise, just print the names of the parameters.

save_json(fname)

Save the information needed to reconstruct this Lightning object to a json file.

The Lightning object can be remade using Lightning.from_json.

The json configuration file is in theory human readable but note that the wavelength grids are reproduced in their entirety, so the file will likely be thousands of lines long.

save_pickle(fname)

Save this whole Lightning object to a pickle.

This will be larger than just saving the configuration to a json file, since it contains the whole object, all of the models, etc.

The normal caveats with pickles apply.

sed_plot_bestfit(samples, logprob_samples, **kwargs)

Make plot of the best-fitting SED.

See lightning.plots.sed_plot_bestfit

sed_plot_delchi(samples, logprob_samples, **kwargs)

Make residual plot.

See lightning.plots.sed_plot_delchi

sfh_plot(samples, **kwargs)

Make SFH plot.

See lightning.plots.sfh_plot