API Documentation¶

Data¶

class caustic.data.Data(event_dir=None)¶

Base class for microlensing data from various observatories.

Subclasses should overload the Data.__load_data() method. The time series data is stored as a list of Astropy tables, one for each photometric filter. Available subclasses for specific data sources are OGLEData, MOAData, KMTData, NASAExoArchiveData.

Example usage:

event = caustic.data.OGLEData("path_to_dir")
coords = event.coordinates  # Get coordinates of the event
name = event.event_name   # Get event name(s)
event.units = "fluxes"  # Change units from magitudes to fluxes
event.units = "magnitudes"  # Change units from fluxes to magnitudes

Parameters:	event_dir (str) – Path to the directory containing microlensing data.

get_standardized_data(rescale=True)¶

This function returns the light curves as a list of astropy tables in a format more suitable for modeling. In particular, the value of 2450000 is subtracted from the time axis, and if any sort of masks are specified for each light curve, the masked data is returned. The conversion from fluxes to magnitudes defines a flux of 1 to correspond to magnitude 22. In addition if rescale=True, the flux for all light curves is independently rescaled to zero median and unit variance. The conversion from fluxes to magnitudes defines a flux of 1 to correspond to magnitude 22.

Parameters:	rescale (bool) – If true, the flux for all light curves is independently rescaled to zero median and unit variance. By default `True`.
Returns:	List of :class:`astropy.table.table.Table()` tables, each table corresponding to a given observing band.
Return type:	list

plot(ax)¶

Plots raw data.

Parameters:	ax (Matplotlib axes object) –

plot_standardized_data(ax, rescale=True)¶

Plots data in standardized modeling format.

Parameters:	ax (Matplotlib axes object) – rescale (bool) – If true, the flux for all light curves is independently rescaled to zero median and unit variance. By default `True`.

Models¶

class caustic.models.SingleLensModel(data=None, standardize=False)¶

Abstract class for a single lens model. Subclasses should implement the should implement the compute_magnification() method.

Parameters:	data (`Data()`) – Caustic data object. standardize (bool) – If `True`, the fluxes for each band will be independently rescaled to zero medain and unit standard deviation. This can sometime improve the sampling efficiency. By default `False`.

compute_log_likelihood(r, var_F, gp_list=None, **kwargs)¶

” Computes the total log likelihood of the model assuming that the observations in different bands are independent. The likelihood is assumed to be multivariate Gaussian with an optional Gaussian Process modeling the covariance matrix elements.

Parameters:	r (list) – List of :code:`theano.tensor` residuals of the mean model with respect to the data, one for each band. var_F (list) – List of :code:`theano.tensor` diagonal elements of the covariance matrix. gp_list (list) – List of `exoplanet.gp.GP` objects, one per each band. If these are provided the likelihood which is computed is the GP marginal likelihood.
Returns:	Log likelihood.
Return type:	theano.tensor

compute_magnification(u, u0)¶

Computes the magnification fraction \([A(u) - 1]/[A(u_0) - 1]\) where \(A(u)\) is the magnification function.

Parameters:	u (theano.tensor) – Trajectory of the lens \(u(t)\) with respect to the source in units of ang. Einstein radii. u0 (theano.tensor) – Lens-source separation at time \(t_0\).
Returns:	The value of the magnification at each time t.
Return type:	theano.tensor

compute_marginalized_log_likelihood(magnification, var_F, L)¶

Computes the multivariate guassian log-likelihood analytically marginalized over the linear flux parameters.

Parameters:

magnification (theano.tensor) – Computed magnification, shape (n_bands, max_npoints).
var_F (theano.tensor) – Diagonal elements of the covariance matrix, shape (n_bands, max_npoints).
L (theano.tensor) – Covariance matrix for the multivariate gaussian prior on the linear flux parameters. The Gaussian prior is a requirement to make the analytical marginalization tractable. The prior is assumed to be equal for all bands, hence the matrix needs to be of shape (2, 2).

generate_mock_dataset()¶: Generates mock Data() object by sampling the prior predictive distribution.

Trajectory¶

class caustic.trajectory.Trajectory(data=None, t0=None, u0=None, tE=None, piEE=None, piEN=None, piE=None, psi=None, a_par=None, a_per=None)¶

Computes the magnitude of the separation vector \(\mathbf{u}(t)\) between the lens and the source star as a function of time assuming that either no parallax effects or annual parallax parametrized using one three different parametrizations. The standard parametrization in terms of the “microlensing parallax vector” components \(\pi_\mathrm{EE}\) and \(\pi_\mathrm{EN}\). The parametrization in terms of the relative lens-source parallax \(\pi_\mathrm{E}\) and an angle \(\psi\) or the parametrization in terms of the local acceleration of the lens at time t0 \((a_ot, a_\parallel)\). If you are planning to use the angle parametrization we recommend using the exoplanet.distributions.Angle object to avoid discontinuities at \(\pi\).

Example usage:

trajectory = caustic.trajectory.Trajectory(event, t0, u0, tE)

u = trajectory.compute_trajectory(model.t)

including parallax

trajectory = caustic.trajectory.Trajectory(event, t0, u0, tE,
    piEE=piEE, piEN=piEN)

u = trajectory.compute_trajectory(model.t)

or

trajectory = caustic.trajectory.Trajectory(event, t0, u0, tE,
    piE=piE, psi=psi)

u, un, ue = trajectory.compute_trajectory(model.t, return_components=True)

or

trajectory = caustic.trajectory.Trajectory(event, t0, u0, tE,
    a_per=a_per, a_par=a_par)

u, un, ue = trajectory.compute_trajectory(model.t, return_components=True)

Parameters:

data (Data()) – Microlensing event data object.
t0 (FreeRV()) – t0 parameter.
u0 (FreeRV()) – u0 parameter, needs to be positive if parallax parameters aren’t provided.
tE (FreeRV()) – tE parameter.
piEE (FreeRV()) – The \(\pi_mathrm{EE}\) components of the microlensing parallax “vector”.
piEN (FreeRV()) – The \(\pi_mathrm{EN}\) components of the microlensing parallax “vector”.
piE (FreeRV()) – The relative lens-source parallax \(\pi_\mathrm{E}=\sqrt{\pi_\mathrm{EE}^2 +\pi_\mathrm{EN}^2}\).
psi (FreeRV()) – The angle between the ecliptic coordinate system and the coordinate system tangential to the lens trajectory at time \(t=t_0\). We have \(\pi_mathrm{EE}=\pi_\mathrm{E}\sin\psi\) and \(\pi_mathrm{EN}=\pi_\mathrm{E}\cos\psi\).
a_per (FreeRV()) – The perpendicular component \(a_ot\) of the apparent lens acceleration at time \(t=t_0\) in units \(\mathrm{yr}^{-2}\).
a_par (FreeRV()) – The parallel component \(a_\parallel\) of the apparent lens acceleration at time \(t=t_0\) in units \(\mathrm{yr}^{-2}\).

compute_trajectory(t, return_components=False)¶

Computes the magnitude of the relative lens-source separation vector \(\mathbf{u}(t)\).

Parameters:	t (list) – List of theano.tensor containing times for which u(t) is to be computed. return_components (bool, optional) – If true, the function returns the tuple u, u_n, u_e, pi_E magnitude, by default False.
Returns:	The magnitude of the separation vector \(\mathbf{u}(t)\) for each time or a tuple with the two components of \(\mathbf{u}(t)\) in (north, east) basis.
Return type:	theano.tensor

Utils¶

caustic.estimate_t0(data)¶

Estimates the initial value for the \(t_0\) parameter. This is necessary because the posterior is highly multi-modal in \(t_0\) and the sampler usually fails to converge if \(t_0\) is not close to true value.

Parameters:	data (`Data()`) – Microlensing event data.
Returns:	Estimate of \(t_0\).
Return type:	float

caustic.estimate_baseline_flux(data)¶

Estimator for the baseline flux of an event.

Parameters:	data (`Data()`) – Microlensing event data.
Returns:	Estimate of baseline flux in each band.
Return type:	ndarray

caustic.estimate_peak_flux(data)¶

Estimator for peak flux of light curves.

Parameters:	data (`Data()`) – Microlensing event data.
Returns:	Estimate of peak flux in each band.
Return type:	ndarray

caustic.compute_source_mag_and_blend_fraction(data, Delta_F, F_base, u_0, model=None)¶

Converts flux parameters \((\Delta F, F_\mathrm{base})\) to physically more relevant interesting quantities, the source star brightness in magnitudes and the blend ratio \(g=F_B/F_S\).

Parameters:	data (`Data()`) – Microlensing event data. Delta_F (theano.tensor) – Tensor of shape `(n_bands)`. F_base (theano.tensor) – Tensor of shape `(n_bands)`. u_0 (theano.tensor) – Lens–source separation at time \(t_0\). standardized (bool) – Wether or not the flux is standardized to unit std deviation and zero median. By default `True`. model (pymc3.Model) – PyMC3 model object which was used to obtain posterior samples in the trace.
Returns:	`(m_source, g)`.
Return type:	tuple

caustic.plot_model_and_residuals(ax, data, samples, t_grid, prediction, gp_list=None, model=None, **kwargs)¶

Plots model in data space given samples from the posterior distribution. Also plots residuals with respect to the median model, where the median model is the median of multiple posterior draws of the model in data space, rather then a single draw corresponding to median values of all parameters. All extra keyword arguments are passed to the matplotlib plot function.

Parameters:

ax (matplotlib.axes) – Needs to be of shape (2, 1).
data (Data()) – Microlensing event data.
samples (list) – List of dictionaries representing a point in the parameter space which can then be evaluted in a model context.
t_grid (theano.tensor) – Times at which we want to evaluate model predictions. Shape (n_bands, n_pts).
prediction (theano.tensor) – Model prediction evaluated at t_grid.
gp_list (list) – List of exoplanet.gp.GP objects, one per each band. If these are provided the likelihood which is computed is the GP marginal likelihood.
model (pymc3.Model) – PyMC3 model object which was used to obtain posterior samples in the trace.

caustic.plot_map_model_and_residuals(ax, data, map_point, t_grid, prediction, gp_list=None, model=None, **kwargs)¶

Plots model in data space given samples from the posterior distribution. Also plots residuals with respect to the median model, where the median model is the median of multiple posterior draws of the model in data space, rather then a single draw corresponding to median values of all parameters. All extra keyword arguments are passed to the matplotlib plot function.

Parameters:

ax (matplotlib.axes) – Needs to be of shape (2, 1).
data (Data()) – Microlensing event data.
model (pymc3.Model) – PyMC3 model object which was used to obtain posterior samples in the trace.
map_point (dict) – Point in the parameter space for which we want to evaluate the prediction tensor.
t_grid (theano.tensor) – Times at which we want to evaluate model predictions. Shape (n_bands, n_pts).
prediction (theano.tensor) – Model prediction evaluated at t_grid.
gp_list (list) – List of exoplanet.gp.GP objects, one per each band. If these are provided the likelihood which is computed is the GP marginal likelihood.

caustic.plot_trajectory_from_samples(ax, samples, t_grid, u_n, u_e, color='C0', model=None, **kwargs)¶

Plots the trajectory of the lens with respect to the source on the plane of the sky given samples from the posterior probability distribution. All extra keyword arguments are passed to the matplotlib plot function.

Parameters:

ax (matplotlib.axes) – Needs to be of shape (2, 1).
samples (list) – List of dictionaries representing a point in the parameter space which can then be evaluted in a model context.
t_grid (theano.tensor) – Times at which we want to evaluate model predictions. Shape (n_bands, n_pts).
u_n (theano.tensor) – North component of the trajectory vector \(oldsymbol{u}(t)\).
u_e (theano.tensor) – East component of the trajectory vector \(oldsymbol{u}(t)\).
color (string) – Color of the plotted samples.
model (pymc3.Model) – PyMC3 model object which was used to obtain posterior samples in the trace.

caustic.compute_invgamma_params(data)¶

Returns parameters of an inverse zeta distribution \(p(x)\) such that 0.1% of total prob. mass is assigned to values of \(t < t_{min}\) and 1% of total prob. masss to values greater than \(t_{tmax}\). \(t_{min}\) is defined to be the median spacing between consecutive data points in the time series and \(t_{max}\) is the total duration of the time series.

Parameters:	data (`Data()`) – Microlensing event data.
Returns:	`(inv_gamma_a, inv_gamma_b)` where each of the parameters has shape `(n_bands, 1)`.
Return type:	tuple

caustic.get_log_likelihood_function(ll_tensor, model=None)¶

Builds a theano function from a PyMC3 model which takes a numpy array of shape (n_parameters) as an input and returns returns the log likelihood of the model. The function takes the untransformed free parameters defined within the model context. The ordering of the parameters in the input array should match the ordering of the RVs in model context. The purpose of this function is to enable to use external samplers with PyMC3 models.

Parameters:	ll_tensor (theano.tensor) – Theano scalar which is the log likelihood of the model. model (pymc3.Model) – PyMC3 model object.
Returns:	log likelihood of the model.
Return type:	ndarray

caustic.get_log_likelihood_function_grad(ll_tensor, model=None)¶: Same as caustic.utils.get_log_likelihood_function() except it returns the gradient of the log likelihood obtained with autodiff.

caustic.get_log_probability_function(model=None)¶

Builds a theano function from a PyMC3 model which takes a numpy array of shape (n_parameters) as an input and returns returns the total log probability of the model. This function takes the transformed random variables defined withing the model context which is a different behaviour from caustic.utils.get_log_likelihood_function(). The ordering of th para eters in the input array should match the ordering of the RVs in model context. The purpose of this function is to be able to use external samplers with PyMC3 models.

Parameters:	model (pymc3.Model) – PyMC3 model object.
Returns:	Total log probability of the model.
Return type:	ndarray

caustic.get_log_probability_function_grad(ll_tensor, model=None)¶: Same as caustic.utils.get_log_probability_function_grad() except it returns the gradient of the log probability obtained with autodiff.