API reference

bayesn-td: BayeSN for strongly-lensed Type Ia supernovae.

class bayesn_td.SEDmodel(num_devices=4, load_model='G26x_model', filter_yaml=None, fiducial_cosmology={'H0': 73.24, 'Om0': 0.28})

BayeSN-SED Model

Class which imports a BayeSN model, and allows one to fit or simulate Type Ia supernovae based on this model.

Parameters:

num_devicesint, optional

Number of CPU cores for numpyro to use. Defaults to 4.

load_modelstr, optional

A pre-defined BayeSN model name or a path to a BAYESN.YAML file. Built-in models: ‘G26x_model’, ‘T21_model’, ‘M20_model’, ‘W22_model’, etc. Default is ‘G26x_model’.

filter_yamlstr, optional

Path to filter YAML file. Defaults to the bundled filters.yaml.

fiducial_cosmologydict, optional

Kwargs {H0, Om0} for FlatLambdaCDM. Defaults to {H0: 73.24, Om0: 0.28}.

Methods

fit(num_samples, num_warmup, num_chains, output)	Run MCMC fitting for lensed SN time delays.
fit_lensed_sn(photometry[, image_col, ...])	Load data and fit a single lensed SN.
fit_postprocess(samples, extras, output)	Process MCMC output: compute time delays, save chains and summary statistics.
get_flux_batch(theta, Av, W0, W1, eps, Ds, ...)	Calculates observer-frame fluxes for multi-image (lensed) data.
get_mag_batch(theta, Av, W0, W1, eps, Ds, ...)	Calculates observer-frame magnitudes for multi-image (lensed) data.
get_spectra(theta, Av, W0, W1, eps, Rv, J_t, ...)	Calculates rest-frame spectra for given parameter values (multi-image).
parse_yaml_input(args, cmd_args)	Parse a YAML input file and command-line overrides, then load data.
process_dataset(photometry[, image_col, ...])	Load lensed SN photometry into the format expected by bayesn-td fitting.
run(args, cmd_args)	Main method to run bayesn-td from a YAML configuration.
sample_AV(N)	Samples AV from model prior.
sample_del_M(N)	Samples grey offset del_M from model prior.
sample_epsilon(N)	Samples epsilon from model prior.
sample_theta(N)	Samples theta from model prior.
simulate_light_curve_ml(mjds, N, bands, ...)	Simulates multi-image lensed light curves from the BayeSN model.
spline_coeffs_irr_step(x_now, x, invkd)	Vectorized version of cubic spline coefficient calculator for JAX vmap.
td_model(obs, weights[, include_eps, include_ml])	Unified numpyro probabilistic model for time-delay fitting of lensed SNe Ia.

fit(num_samples, num_warmup, num_chains, output, chain_method='parallel', init_strategy='median', include_eps=True, include_ml=True)

Run MCMC fitting for lensed SN time delays.

Data must be loaded first via process_dataset.

Parameters:

num_samplesint

Number of posterior samples per chain.

num_warmupint

Number of warmup steps.

num_chainsint

Number of chains.

outputstr

Output directory path for results.

chain_methodstr, optional

‘parallel’, ‘sequential’, or ‘vectorized’. Default ‘parallel’.

init_strategystr, optional

‘median’ or ‘sample’. Default ‘median’.

include_epsbool, optional

Include epsilon in model. Default True.

include_mlbool, optional

Include microlensing GP in model. Default True.

Returns:

samplesdict

Processed MCMC samples including time delays.

fit_lensed_sn(photometry, image_col=None, time_col=None, band_col=None, flux_col=None, fluxerr_col=None, mag_col=None, magerr_col=None, peak_mjds=None, z=None, ebv_mw=None, band_map=None, error_floor=None, sigma_psf=0, time_format='mjd', num_samples=500, num_warmup=500, num_chains=4, chain_method='parallel', init_strategy='median', include_eps=True, include_ml=True, output=None)

Load data and fit a single lensed SN.

Calls process_dataset then fit. Column names are auto-detected from the file header when not given explicitly.

Parameters:

photometrystr or pd.DataFrame

Path to photometry file or a DataFrame.

image_col, time_col, band_colstr, optional

Column names. Auto-detected if not given.

flux_col, fluxerr_colstr, optional

Flux column names (FLUXCAL system). Auto-detected if not given.

mag_col, magerr_colstr, optional

Magnitude column names. Auto-detected if not given.

peak_mjdslist of float, optional

Estimated peak MJD for each image. If not given, read from ECSV metadata.

zfloat, optional

Source redshift. If not given, read from ECSV metadata.

ebv_mwfloat, optional

Milky Way E(B-V). If not given, read from ECSV metadata.

band_mapdict, optional

Mapping from data band names to BayeSN band names.

error_floordict, optional

Per-band error floor in magnitudes.

sigma_psffloat, optional

PSF uncertainty to add in quadrature. Default 0.

time_formatstr, optional

‘mjd’ or ‘phase’. Default ‘mjd’.

num_samplesint, optional

Number of posterior samples per chain. Default 500.

num_warmupint, optional

Number of warmup steps. Default 500.

num_chainsint, optional

Number of chains. Default 4.

chain_methodstr, optional

‘parallel’, ‘sequential’, or ‘vectorized’. Default ‘parallel’.

init_strategystr, optional

‘median’ or ‘sample’. Default ‘median’.

include_epsbool, optional

Include epsilon in model. Default True.

include_mlbool, optional

Include microlensing GP in model. Default True.

outputstr, optional

Output directory. Default creates ‘results/fit’.

Returns:

samplesdict

Processed MCMC samples including time delays.

fit_postprocess(samples, extras, output)

Process MCMC output: compute time delays, save chains and summary statistics.

Parameters:

samplesdict

MCMC samples.

extrasdict

Extra MCMC fields (divergences, etc.).

outputstr

Output directory path.

Returns:

samplesdict

Processed samples with time delays and distance moduli added.

get_flux_batch(theta, Av, W0, W1, eps, Ds, Rv, band_indices, mask, J_t, hsiao_interp, weights, beta_t)

Calculates observer-frame fluxes for multi-image (lensed) data.

get_mag_batch(theta, Av, W0, W1, eps, Ds, Rv, band_indices, mask, J_t, hsiao_interp, weights, beta_t)

Calculates observer-frame magnitudes for multi-image (lensed) data.

get_spectra(theta, Av, W0, W1, eps, Rv, J_t, hsiao_interp)

Calculates rest-frame spectra for given parameter values (multi-image).

Parameters:

theta, Av, W0, W1, eps, Rv, J_t, hsiao_interparray-like

Model parameters and interpolation matrices.

Returns:

model_spectraarray-like

Model spectra for all SNe at all time-steps.

parse_yaml_input(args, cmd_args)

Parse a YAML input file and command-line overrides, then load data.

Parameters:

argsdict

Dictionary of arguments from YAML input file.

cmd_argsargparse.Namespace

Command-line arguments that override YAML values.

Returns:

argsdict

Merged configuration dictionary.

process_dataset(photometry, image_col=None, time_col=None, band_col=None, flux_col=None, fluxerr_col=None, mag_col=None, magerr_col=None, peak_mjds=None, z=None, ebv_mw=None, band_map=None, error_floor=None, sigma_psf=0, time_format='mjd', z_err=0.0005)

Load lensed SN photometry into the format expected by bayesn-td fitting.

Column names are auto-detected from the file header when not given explicitly. If the file has no header, columns are assumed to be in the order: mjd, filter, mag, magerr, image.

Parameters:

photometrystr or pd.DataFrame

Path to a photometry file (CSV, whitespace-delimited, or ECSV) or a DataFrame.

image_colstr, optional

Column name for the lensed image identifier. Auto-detected if not given.

time_colstr, optional

Column name for observation times. Auto-detected if not given.

band_colstr, optional

Column name for the filter/band. Auto-detected if not given.

flux_colstr, optional

Column name for flux values (FLUXCAL system, zeropoint 27.5). Auto-detected if not given.

fluxerr_colstr, optional

Column name for flux errors. Auto-detected if not given.

mag_colstr, optional

Column name for magnitudes. Auto-detected if not given.

magerr_colstr, optional

Column name for magnitude errors. Auto-detected if not given.

peak_mjdslist of float, optional

Estimated peak MJD for each image. The ordering matches sorted(df[image_col].unique()). If not given, read from ECSV metadata.

zfloat, optional

Source redshift. If not given, read from ECSV metadata.

ebv_mwfloat, optional

Milky Way E(B-V). If not given, read from ECSV metadata.

band_mapdict, optional

Mapping from column band names to BayeSN band names.

error_floordict, optional

Per-band error floor in magnitudes, e.g. {'F090W': 0.02}.

sigma_psffloat, optional

PSF uncertainty to add in quadrature to mag errors. Default 0.

time_formatstr, optional

'mjd' (default) or 'phase'.

z_errfloat, optional

Redshift error. Default 5e-4.

run(args, cmd_args)

Main method to run bayesn-td from a YAML configuration.

Parameters:

argsdict

Dictionary of arguments from YAML input file.

cmd_argsargparse.Namespace

Command-line arguments that override YAML values.

sample_AV(N)

Samples AV from model prior.

sample_del_M(N)

Samples grey offset del_M from model prior.

sample_epsilon(N)

Samples epsilon from model prior.

sample_theta(N)

Samples theta from model prior.

simulate_light_curve_ml(mjds, N, bands, peak_mjds, z, yerr=0, err_type='mag', zerr=0.0001, mu=0, ebv_mw=0, RV=None, del_M=None, AV=None, theta=None, eps=None, mag=True, save_to=None)

Simulates multi-image lensed light curves from the BayeSN model.

Parameters:

mjdsarray-like

Observer-frame observation MJDs (1D). If len(mjds) == len(bands), each observation uses the corresponding band (flat mode). Otherwise, every MJD is observed in every band (grid mode, band-major order).

Nint

Number of objects to simulate.

bandsarray-like

List of bands. See mjds for flat vs grid semantics.

peak_mjdsarray-like

Observer-frame peak MJD per image. Shape (N, n_images). Time delays between images are encoded by the differences between these values.

zfloat or array-like

Source redshift. Scalar or shape (N,).

yerrfloat or array-like, optional

Uncertainties. Default 0.

err_typestr, optional

‘mag’ or ‘flux’. Default ‘mag’.

zerrfloat, optional

Redshift error. Default 1e-4.

mufloat, array-like, or ‘z’, optional

Distance modulus. Default 0. Shape should be (N, n_images).

ebv_mwfloat or array-like, optional

MW E(B-V). Default 0.

RVfloat or array-like, optional

Host R_V. Default uses model value.

del_Mfloat or array-like, optional

Grey offset. Default sampled from prior.

AVfloat or array-like, optional

Host extinction. Default sampled from prior.

thetafloat or array-like, optional

Theta. Default sampled from prior.

epsarray-like or int, optional

Epsilon. Default sampled from prior. Pass 0 to disable.

magbool, optional

Return magnitudes if True. Default True.

save_tostr, optional

If given, write the simulated light curve(s) to ECSV file(s) with true parameters in the YAML header. Images are labelled 'A', 'B', … in the output file’s image column. For N=1, writes directly to save_to; for N>1, writes one file per SN with an index suffix (e.g. sim_0.ecsv).

Returns:

dataarray-like

Simulated flux or mag values. Shape (n_total_obs, n_images, N).

yerrarray-like

Corresponding errors.

param_dictdict

Parameter values for each simulated object.

static spline_coeffs_irr_step(x_now, x, invkd)

Vectorized version of cubic spline coefficient calculator for JAX vmap.

td_model(obs, weights, include_eps=True, include_ml=True)

Unified numpyro probabilistic model for time-delay fitting of lensed SNe Ia.

Parameters:

obsarray-like

Observation data tensor from process_dataset.

weightsarray-like

Band weights from _calculate_band_weights.

include_epsbool, optional

Whether to include residual colour variation (epsilon). Default True.

include_mlbool, optional

Whether to include microlensing GP model. Default True.

bayesn_td.model

BayeSN SED Model. Defines a class which allows you to fit or simulate from the BayeSN Optical+NIR SED model for strongly-lensed Type Ia supernovae.

class bayesn_td.model.SEDmodel(num_devices=4, load_model='G26x_model', filter_yaml=None, fiducial_cosmology={'H0': 73.24, 'Om0': 0.28})

BayeSN-SED Model

Class which imports a BayeSN model, and allows one to fit or simulate Type Ia supernovae based on this model.

Parameters:

num_devicesint, optional

Number of CPU cores for numpyro to use. Defaults to 4.

load_modelstr, optional

A pre-defined BayeSN model name or a path to a BAYESN.YAML file. Built-in models: ‘G26x_model’, ‘T21_model’, ‘M20_model’, ‘W22_model’, etc. Default is ‘G26x_model’.

filter_yamlstr, optional

Path to filter YAML file. Defaults to the bundled filters.yaml.

fiducial_cosmologydict, optional

Kwargs {H0, Om0} for FlatLambdaCDM. Defaults to {H0: 73.24, Om0: 0.28}.

Methods

fit(num_samples, num_warmup, num_chains, output)	Run MCMC fitting for lensed SN time delays.
fit_lensed_sn(photometry[, image_col, ...])	Load data and fit a single lensed SN.
fit_postprocess(samples, extras, output)	Process MCMC output: compute time delays, save chains and summary statistics.
get_flux_batch(theta, Av, W0, W1, eps, Ds, ...)	Calculates observer-frame fluxes for multi-image (lensed) data.
get_mag_batch(theta, Av, W0, W1, eps, Ds, ...)	Calculates observer-frame magnitudes for multi-image (lensed) data.
get_spectra(theta, Av, W0, W1, eps, Rv, J_t, ...)	Calculates rest-frame spectra for given parameter values (multi-image).
parse_yaml_input(args, cmd_args)	Parse a YAML input file and command-line overrides, then load data.
process_dataset(photometry[, image_col, ...])	Load lensed SN photometry into the format expected by bayesn-td fitting.
run(args, cmd_args)	Main method to run bayesn-td from a YAML configuration.
sample_AV(N)	Samples AV from model prior.
sample_del_M(N)	Samples grey offset del_M from model prior.
sample_epsilon(N)	Samples epsilon from model prior.
sample_theta(N)	Samples theta from model prior.
simulate_light_curve_ml(mjds, N, bands, ...)	Simulates multi-image lensed light curves from the BayeSN model.
spline_coeffs_irr_step(x_now, x, invkd)	Vectorized version of cubic spline coefficient calculator for JAX vmap.
td_model(obs, weights[, include_eps, include_ml])	Unified numpyro probabilistic model for time-delay fitting of lensed SNe Ia.

fit(num_samples, num_warmup, num_chains, output, chain_method='parallel', init_strategy='median', include_eps=True, include_ml=True)

Run MCMC fitting for lensed SN time delays.

Data must be loaded first via process_dataset.

Parameters:

num_samplesint

Number of posterior samples per chain.

num_warmupint

Number of warmup steps.

num_chainsint

Number of chains.

outputstr

Output directory path for results.

chain_methodstr, optional

‘parallel’, ‘sequential’, or ‘vectorized’. Default ‘parallel’.

init_strategystr, optional

‘median’ or ‘sample’. Default ‘median’.

include_epsbool, optional

Include epsilon in model. Default True.

include_mlbool, optional

Include microlensing GP in model. Default True.

Returns:

samplesdict

Processed MCMC samples including time delays.

fit_lensed_sn(photometry, image_col=None, time_col=None, band_col=None, flux_col=None, fluxerr_col=None, mag_col=None, magerr_col=None, peak_mjds=None, z=None, ebv_mw=None, band_map=None, error_floor=None, sigma_psf=0, time_format='mjd', num_samples=500, num_warmup=500, num_chains=4, chain_method='parallel', init_strategy='median', include_eps=True, include_ml=True, output=None)

Load data and fit a single lensed SN.

Calls process_dataset then fit. Column names are auto-detected from the file header when not given explicitly.

Parameters:

photometrystr or pd.DataFrame

Path to photometry file or a DataFrame.

image_col, time_col, band_colstr, optional

Column names. Auto-detected if not given.

flux_col, fluxerr_colstr, optional

Flux column names (FLUXCAL system). Auto-detected if not given.

mag_col, magerr_colstr, optional

Magnitude column names. Auto-detected if not given.

peak_mjdslist of float, optional

Estimated peak MJD for each image. If not given, read from ECSV metadata.

zfloat, optional

Source redshift. If not given, read from ECSV metadata.

ebv_mwfloat, optional

Milky Way E(B-V). If not given, read from ECSV metadata.

band_mapdict, optional

Mapping from data band names to BayeSN band names.

error_floordict, optional

Per-band error floor in magnitudes.

sigma_psffloat, optional

PSF uncertainty to add in quadrature. Default 0.

time_formatstr, optional

‘mjd’ or ‘phase’. Default ‘mjd’.

num_samplesint, optional

Number of posterior samples per chain. Default 500.

num_warmupint, optional

Number of warmup steps. Default 500.

num_chainsint, optional

Number of chains. Default 4.

chain_methodstr, optional

‘parallel’, ‘sequential’, or ‘vectorized’. Default ‘parallel’.

init_strategystr, optional

‘median’ or ‘sample’. Default ‘median’.

include_epsbool, optional

Include epsilon in model. Default True.

include_mlbool, optional

Include microlensing GP in model. Default True.

outputstr, optional

Output directory. Default creates ‘results/fit’.

Returns:

samplesdict

Processed MCMC samples including time delays.

fit_postprocess(samples, extras, output)

Process MCMC output: compute time delays, save chains and summary statistics.

Parameters:

samplesdict

MCMC samples.

extrasdict

Extra MCMC fields (divergences, etc.).

outputstr

Output directory path.

Returns:

samplesdict

Processed samples with time delays and distance moduli added.

get_flux_batch(theta, Av, W0, W1, eps, Ds, Rv, band_indices, mask, J_t, hsiao_interp, weights, beta_t)

Calculates observer-frame fluxes for multi-image (lensed) data.

get_mag_batch(theta, Av, W0, W1, eps, Ds, Rv, band_indices, mask, J_t, hsiao_interp, weights, beta_t)

Calculates observer-frame magnitudes for multi-image (lensed) data.

get_spectra(theta, Av, W0, W1, eps, Rv, J_t, hsiao_interp)

Calculates rest-frame spectra for given parameter values (multi-image).

Parameters:

theta, Av, W0, W1, eps, Rv, J_t, hsiao_interparray-like

Model parameters and interpolation matrices.

Returns:

model_spectraarray-like

Model spectra for all SNe at all time-steps.

parse_yaml_input(args, cmd_args)

Parse a YAML input file and command-line overrides, then load data.

Parameters:

argsdict

Dictionary of arguments from YAML input file.

cmd_argsargparse.Namespace

Command-line arguments that override YAML values.

Returns:

argsdict

Merged configuration dictionary.

process_dataset(photometry, image_col=None, time_col=None, band_col=None, flux_col=None, fluxerr_col=None, mag_col=None, magerr_col=None, peak_mjds=None, z=None, ebv_mw=None, band_map=None, error_floor=None, sigma_psf=0, time_format='mjd', z_err=0.0005)

Load lensed SN photometry into the format expected by bayesn-td fitting.

Column names are auto-detected from the file header when not given explicitly. If the file has no header, columns are assumed to be in the order: mjd, filter, mag, magerr, image.

Parameters:

photometrystr or pd.DataFrame

Path to a photometry file (CSV, whitespace-delimited, or ECSV) or a DataFrame.

image_colstr, optional

Column name for the lensed image identifier. Auto-detected if not given.

time_colstr, optional

Column name for observation times. Auto-detected if not given.

band_colstr, optional

Column name for the filter/band. Auto-detected if not given.

flux_colstr, optional

Column name for flux values (FLUXCAL system, zeropoint 27.5). Auto-detected if not given.

fluxerr_colstr, optional

Column name for flux errors. Auto-detected if not given.

mag_colstr, optional

Column name for magnitudes. Auto-detected if not given.

magerr_colstr, optional

Column name for magnitude errors. Auto-detected if not given.

peak_mjdslist of float, optional

Estimated peak MJD for each image. The ordering matches sorted(df[image_col].unique()). If not given, read from ECSV metadata.

zfloat, optional

Source redshift. If not given, read from ECSV metadata.

ebv_mwfloat, optional

Milky Way E(B-V). If not given, read from ECSV metadata.

band_mapdict, optional

Mapping from column band names to BayeSN band names.

error_floordict, optional

Per-band error floor in magnitudes, e.g. {'F090W': 0.02}.

sigma_psffloat, optional

PSF uncertainty to add in quadrature to mag errors. Default 0.

time_formatstr, optional

'mjd' (default) or 'phase'.

z_errfloat, optional

Redshift error. Default 5e-4.

run(args, cmd_args)

Main method to run bayesn-td from a YAML configuration.

Parameters:

argsdict

Dictionary of arguments from YAML input file.

cmd_argsargparse.Namespace

Command-line arguments that override YAML values.

sample_AV(N)

Samples AV from model prior.

sample_del_M(N)

Samples grey offset del_M from model prior.

sample_epsilon(N)

Samples epsilon from model prior.

sample_theta(N)

Samples theta from model prior.

simulate_light_curve_ml(mjds, N, bands, peak_mjds, z, yerr=0, err_type='mag', zerr=0.0001, mu=0, ebv_mw=0, RV=None, del_M=None, AV=None, theta=None, eps=None, mag=True, save_to=None)

Simulates multi-image lensed light curves from the BayeSN model.

Parameters:

mjdsarray-like

Observer-frame observation MJDs (1D). If len(mjds) == len(bands), each observation uses the corresponding band (flat mode). Otherwise, every MJD is observed in every band (grid mode, band-major order).

Nint

Number of objects to simulate.

bandsarray-like

List of bands. See mjds for flat vs grid semantics.

peak_mjdsarray-like

Observer-frame peak MJD per image. Shape (N, n_images). Time delays between images are encoded by the differences between these values.

zfloat or array-like

Source redshift. Scalar or shape (N,).

yerrfloat or array-like, optional

Uncertainties. Default 0.

err_typestr, optional

‘mag’ or ‘flux’. Default ‘mag’.

zerrfloat, optional

Redshift error. Default 1e-4.

mufloat, array-like, or ‘z’, optional

Distance modulus. Default 0. Shape should be (N, n_images).

ebv_mwfloat or array-like, optional

MW E(B-V). Default 0.

RVfloat or array-like, optional

Host R_V. Default uses model value.

del_Mfloat or array-like, optional

Grey offset. Default sampled from prior.

AVfloat or array-like, optional

Host extinction. Default sampled from prior.

thetafloat or array-like, optional

Theta. Default sampled from prior.

epsarray-like or int, optional

Epsilon. Default sampled from prior. Pass 0 to disable.

magbool, optional

Return magnitudes if True. Default True.

save_tostr, optional

If given, write the simulated light curve(s) to ECSV file(s) with true parameters in the YAML header. Images are labelled 'A', 'B', … in the output file’s image column. For N=1, writes directly to save_to; for N>1, writes one file per SN with an index suffix (e.g. sim_0.ecsv).

Returns:

dataarray-like

Simulated flux or mag values. Shape (n_total_obs, n_images, N).

yerrarray-like

Corresponding errors.

param_dictdict

Parameter values for each simulated object.

static spline_coeffs_irr_step(x_now, x, invkd)

Vectorized version of cubic spline coefficient calculator for JAX vmap.

td_model(obs, weights, include_eps=True, include_ml=True)

Unified numpyro probabilistic model for time-delay fitting of lensed SNe Ia.

Parameters:

obsarray-like

Observation data tensor from process_dataset.

weightsarray-like

Band weights from _calculate_band_weights.

include_epsbool, optional

Whether to include residual colour variation (epsilon). Default True.

include_mlbool, optional

Whether to include microlensing GP model. Default True.