Transmission spectroscopy

Transmission spectroscopy#

The ExoIris class is the core class of ExoIris used for transmission spectroscopy. It serves as the primary tool for first fitting the white light curve model and subsequently fitting and sampling the spectroscopic light curve model.

Constructor#

The ExoIris class is initialized by providing a name for the analysis, selecting a limb darkening model, and passing the spectroscopic light curves as either a TSData or TSDataGroup object. Additional parameters can also be supplied to the initializer to refine the analysis, although these can be set later if preferred.

The transmission spectroscopy transit model used in ExoIris, pytransit.TSModel, is based on PyTransit’s RoadRunner transit model (pytransit.RRModel). The RoadRunner model is an advanced transit model that can efficiently use any radially symmetric function to model stellar limb darkening, as described in Parviainen (2020).

Since TSModel is based on RRModel, it offers the same flexibility for modeling stellar limb darkening. The ldmodel argument can be one of the following:

a string representing one of the built-in limb darkening models supported by RRModel, such as power-2 or quadratic,
an object that is a subclass of the pytransit.models.ldmodel.LDModel limb darkening model class,
a tuple of two functions, with the first returning the limb darkening profile as a function of \(\mu\) and the second returning its integral over the stellar disk, or
a single function that returns the stellar limb darkening profile as a function of \(\mu\) , in which case its integral is computed numerically.

ExoIris(name, ldmodel, data[, nk, nldc, ...])

The core ExoIris class providing tools for exoplanet transit spectroscopy.

Model saving and loading#

An ExoIris instance can be saved to a FITS file using the ExoIris.save method. This stores the model setup, optimiser state, and MCMC sampler state, allowing the model to be fully recreated later using the load_model function.

`ExoIris.save`([overwrite])	Save the ExoIris analysis to a FITS file.
`load_model`(fname[, name])	Load an ExoIris analysis from a FITS file.

Light curve model setup#

All parts of an ExoIris analysis can be modified after initialisation. This enables iterative analysis approaches where a saved low-resolution analysis can be loaded as a new analysis using the load_model function. Parameters like the radius ratio and limb darkening knots can be adjusted to increase the resolution of the estimated transmission spectrum, and even the observational data can be changed to improve the data resolution.

`ExoIris.set_data`(data)	Set the model data.
`ExoIris.set_radius_ratio_knots`(knot_wavelengths)	Set the radius ratio (k) knots.
`ExoIris.add_radius_ratio_knots`(knot_wavelengths)	Add radius ratio (k) knots.
`ExoIris.set_limb_darkening_knots`(...)	Set the limb darkening knots.
`ExoIris.free_radius_ratio_knot_locations`(...)	Add the wavelength locations of chosen radius ratio knots to the model as free parameters.
`ExoIris.create_dense_radius_ratio_block`(...)	Create a block of radius ratio knots using the full data resolution.
`ExoIris.plot_setup`([figsize, ax, xscale, ...])	Plot the model setup with limb darkening knots, radius ratio knots, and data binning.

Interpolation configuration#

ExoIris uses interpolation to model the wavelength-dependent radius ratio and limb darkening parameters. The interpolation method can be customized to balance smoothness against fidelity to the data. Available interpolators include: nearest, linear, pchip, makima, bspline, bspline-quadratic, and bspline-cubic.

`ExoIris.set_radius_ratio_interpolator`(...)	Set the interpolator for the radius ratio (k) model.
`ExoIris.set_limb_darkening_interpolator`(...)	Set the interpolator for the limb darkening model.

Parameterization and priors#

`ExoIris.set_prior`(parameter, prior, *nargs)	Set a prior on a model parameter.
`ExoIris.set_baseline_prior`(prior, *nargs)	Set an identical prior on all baseline knots.
`ExoIris.set_ldtk_prior`(teff, logg, metal[, ...])	Set priors on the limb darkening parameters using LDTk.
`ExoIris.set_radius_ratio_prior`(prior, *nargs)	Set an identical prior on all radius ratio (k) knots.
`ExoIris.print_parameters`()	Print the model parameterization.

Noise model setup#

The noise in the spectroscopic light curves can be modeled as either white noise or time-correlated noise (using a Gaussian process, GP). The noise model is chosen with the ExoIris.set_noise_model method, and can be set to "white", "fixed_gp", or "free_gp". Selecting "fixed_gp" models the noise as a time-correlated Gaussian process using the celerite2 package with fixed hyperparameters, while "free_gp" allows the GP hyperparameters to be sampled as free parameters. The corresponding celerite2.GaussianProcess object can be accessed directly via the ExoIris.gp attribute.

`ExoIris.set_noise_model`(noise_model)	Set the noise model for the analysis.
`ExoIris.set_gp_kernel`(kernel)	Set the Gaussian Process (GP) kernel.
`ExoIris.set_gp_hyperparameters`(sigma, rho[, ...])	Set Gaussian Process (GP) hyperparameters assuming a Matern-3/2 kernel.
`ExoIris.optimize_gp_hyperparameters`([...])
`ExoIris.gp`	Gaussian Process (GP) models.
`ExoIris.plot_white_gp_predictions`([axs, ...])	Plot the predictions of a Gaussian Process model for white light curves and residuals.

Star spot modeling#

ExoIris supports modeling of star spot crossings during transit and the Transit Light Source Effect (TLSE). Star spots can cause both localized bumps in the light curve (when the planet occults a spot) and wavelength-dependent baseline variations (TLSE) due to the inhomogeneous stellar surface.

To use spot modeling, first initialize the spot model with ExoIris.initialize_spots, then add spots for specific epoch groups using ExoIris.add_spot.

`ExoIris.initialize_spots`(tstar, wlref[, ...])	Initialize star spot model using given stellar and wavelength reference values.
`ExoIris.add_spot`(epoch_group)	Add a new star spot and associate it with an epoch group.
`ExoIris.nspots`	Number of star spots.

First steps#

The first steps of a transmission spectroscopy analysis include fitting a white light curve and normalising the spectroscopic light curves. ExoIris offers utility methods for both of these tasks, as well as for visualising the results.

`ExoIris.fit_white`([niter])	Fit a white light curve model and sets the out-of-transit mask.
`ExoIris.normalize_baseline`([deg])	Normalize the baseline flux for each spectroscopic light curve.
`ExoIris.plot_white`([axs, figsize, ncols])	Plot the white light curve data with the best-fit model.
`ExoIris.plot_residuals`([result, ax, pmin, ...])	Plot the model residuals.
`ExoIris.plot_baseline`([axs, figsize])	Plot the out-of-transit spectroscopic light curves before and after the normalization.

Fitting and sampling#

The main tasks of ExoIris are to fit a spectroscopic light curve model to the observations and then sample its parameter posterior to obtain a posterior transmission spectrum estimate. The fitting is carried out using a Differential Evolution global optimiser and the sampling with the emcee affine invariant ensemble sampler.

The DE optimiser works by clumping a population of npop parameter vectors near the global posterior mode over niter iterations. The optimisation can be stopped when the ptp width of the population’s log posterior distribution has decreased below a desired threshold (by default 2), after which the MCMC sampling phase can be started.

Both of these methods can be called iteratively, in which case they start from the state they finished in the previous call. At the first ExoIris.sample call, the sampler will start from the current DE optimiser population. Note that loading a previous analysis with load_model also loads the sampler state, so calling ExoIris.sample after loading a model continues the sampler from the saved sampler state. ExoIris.reset_sampler should be called after loading a saved model if you want to change the setup, optimise the new setup, and then sample the posterior.

`ExoIris.fit`([niter, npop, pool, lnpost, ...])	Fit the spectroscopic light curves jointly using Differential Evolution.
`ExoIris.sample`([niter, thin, repeats, pool, ...])	Sample the posterior distribution using the emcee MCMC sampler.
`ExoIris.reset_sampler`()	Reset the MCMC sampler

Accessing the results#

The main results from an ExoIris analysis are the model parameter posterior samples and the transmission spectrum. The transmission spectrum, represented as the planet-to-star area ratio as a function of wavelength, can be retrieved as a Pandas DataFrame using the ExoIris.transmission_spectrum attribute. Similarly, the model posterior samples can be accessed using the ExoIris.posterior_samples attribute, also in the form of a Pandas DataFrame.

`ExoIris.transmission_spectrum`([wavelengths, ...])	Compute the transmission spectrum.
`ExoIris.transmission_spectrum_table`	Get the posterior transmission spectrum as an Astropy Table.
`ExoIris.posterior_samples`	Posterior samples from the MCMC sampler.
`ExoIris.plot_fit`([result, figsize, ...])	Plot either the best-fit model or the posterior model.
`ExoIris.plot_transmission_spectrum`([result, ...])	Plot the transmission spectrum.
`ExoIris.plot_residuals`([result, ax, pmin, ...])	Plot the model residuals.
`ExoIris.plot_limb_darkening_parameters`([...])	Plot the limb darkening parameters.

Atmospheric retrieval#

ExoIris provides tools for atmospheric retrieval by creating a log-likelihood function that can be used with external retrieval codes. The ExoIris.create_loglikelihood_function method returns a callable that evaluates the log-likelihood for a given transmission spectrum model, accounting for the full covariance structure of the data.

`ExoIris.create_loglikelihood_function`(...[, ...])	Create a reduced-rank Gaussian log-likelihood function for retrieval.
`ExoIris.transmission_spectrum_samples`([...])	Calculate posterior transmission spectrum samples.

Utility methods#

`ExoIris.reset`([optimizer, sampler])	Reset the internal states of the optimizer and sampler.
`ExoIris.create_initial_population`(n, source)	Create an initial parameter vector population for the DE optimisation.
`ExoIris.lnposterior`(pvp)	Calculate the log posterior probability for a single parameter vector or an array of parameter vectors.

Properties#

The following properties expose key internal states and parameters of the analysis:

`ExoIris.name`	Analysis name.
`ExoIris.data`	Analysis data set.
`ExoIris.k_knots`	Radius ratio (k) knots.
`ExoIris.ndim`	Number of free model parameters.
`ExoIris.nk`	Number of radius ratio (k) knots.
`ExoIris.nldp`	Number of limb darkening knots.
`ExoIris.npb`	Number of passbands for each data set.
`ExoIris.nspots`	Number of star spots.
`ExoIris.ldmodel`	The limb darkening model.
`ExoIris.sampler`	The emcee sampler.
`ExoIris.optimizer`	The global optimization algorithm.
`ExoIris.optimizer_population`	DE optimizer parameter vector population.
`ExoIris.mcmc_chains`	Emcee sampler MCMC chains.
`ExoIris.white_times`	White light curve time arrays.
`ExoIris.white_fluxes`	White light curve flux arrays.
`ExoIris.white_models`	Fitted white light curve flux model arrays.
`ExoIris.white_errors`	White light curve flux error arrays.
`ExoIris.ps`	Model parameterization.