exoUPRF Usage Guide

exoUPRF is designed to be easy-to-use and hackable, allowing flexibility in light curve model selection necessary for JWST exoplanet light curves.

Built-in Light Curve Models

The following is a list of light curve models built in to exoUPRF, as well as their necessary parameters and calls.

Simple Transit

call: transit

Parameter Name	Description
`P_p1`	The orbital period of the planet (days).
`t0_p1`	The time of mid-transit of the planet (days).
`rp_p1`	Planet-to-star radius ratio (Rp/Rs).
`inc_p1`	Orbital inclination (deg).
`a_p1`	Scaled orbital semi-major axis (a/R*).
`ecc_p1`	Orbital eccentricity.
`w_p1`	Argument of periastron (deg).

Transit models include limb darkening. Supported limb darkening models are: linear, quadratic, quadratic-kipping, square-root, or nonlinear.

Asymmetric transits can also be fit using the functionalities of catwoman. To fit an asymmetric transit, also add the following parameters in addition to the above:

Parameter Name	Description
`rp2_p1`	Planet-to-star radius ratio of second hemisphere.
`phi_p1`	Rotation angle of hemispheres (90deg is vertical).

In this case, the original rp_p1 becomes the radius ratio of the first hemisphere. For more information, see the catwoman documentation.

Simple Eclipse

call: eclipse

In addition to the simple transit parameters listed above, the eclipse model has two extras:

Parameter Name	Description
`tsec_p1`	The time of secondary eclipse (days).
`fp_p1`	Planet-to-star flux ratio (Fp/Fs).

Built-in Systematics Models

Systematics are handled in exoUPRF via three methods: linear models, parametric models, and/or Gaussian processes.

Linear Models

Linear model detrending is one of the simplest forms of systematics correction. A user-defined vector is linearlly scaled to attempt to remove systematic noise froma light curve, i.e.,

\[\text{light curve} = \text{transit} + \sum_{i=1}^N X_i\theta_i,\]

where \(\theta_i\) is a set of \(N\) user-defined systematics vectors, and \(X_i\) is the set of scalars multiplying the systematics vectors.

Parametric Systematics Models

A parametric systematics model is used to correct a source of systematic noise with a well-defined funcational form. Currently supported parametric systematics models and their necessary parameters are:

Spot Crossing (modelled as a Gaussian “bump”)

Parameter Name	Description
`spot-amp`	Amplitude of the Gaussian bump.
`spot-pos`	Position of the Gaussian bump (days).
`spot-dur`	Width of the Gaussian bump (days).

Baseline Curvature (assumed to be quadratic)

Parameter Name	Description
`curv-amp`	Amplitude of the curvature.
`curv-pos`	Position center of curvature, relative to mid-transit (days).

Exponential Ramp (Assumed to be at the start of the observations)

Parameter Name	Description
`ramp-amp`	Amplitude of the exponential ramp.
`ramp-tmsc`	Ramp e-folding timescale (values < 0 indicate decay; days)

Gaussian Processes

Gaussian processes (GPs) are non-parametric models often used to handle systematic trends for which we don’t have an analytical model.

Currently supported GP kernels and their parameters are:

Matérn 3/2

Parameter Name	Description
`GP_sigma`	Characteristic amplitude of the GP.
`GP_rho`	Characteristic timescale of the GP.

Simple Harmonic Oscillator

Parameter Name	Description
`GP_S0`	Characteristic amplitude of the GP.
`GP_omega0`	Characteristic frequency of the GP.
`GP_Q`	Quality factor of the oscillation.

For more information on the SHO kernel see Foreman-Mackey et al. (2017).

SHO for Stellar Granulation

This is a slight transformation of the above SHO kernel to model the impacts of stellar granulation in exoplanet light curves. The transformations are outlined in equation 12 of Pereira et al. (2019).

Parameter Name	Description
`GP_ag`	Characteristic amplitude of the granulation signal.
`GP_bg`	Characteristic frequency of the granulation signal.

Using Custom Light Curve Models

exoUPRF comes with two built-in light curve models: a simple transit and a simple eclipse model with no extra bells and whistles. However, exoUPRF is also made to allow for users to easily swap in their own light curve models, as long as they obey a couple of key rules. The custom function call must take the observation time array, and the planet parameters dictionary as inputs, and return a single flux array with the same shape as the time array. Here’s an example function definition:

def custom_transit(time,            # Array of timestamps.
                   pl_params        # exoUPRF planet parameters dictionary.
                   ):
    flux = ...                      # Code to calculate the custom transit model.
    assert len(flux) == len(time)   # Flux must have the same length as time.
    return flux

Getting exoUPRF to use the custom model is also incredibly easy! First, in the model_type dictionary, instead of indicating transit or eclipse as usual, instead specify custom-transit or custom-eclipse, depending on the light curve in question.

model_type = {'inst': {'p1': 'custom-transit'}}

Then, define a model_functions dictionary, to which we will pass the call to the custom_transit function defined above.

from custom_models import custom_transit
model_functions = {'inst': {'p1': custom_transit}}

Finally, simply pass both of these dictionaries to either the compute_lightcurves or fit function calls.

Tutorial Notebooks

Below is a tutorial notebook that will walk you through the basics fitting JWST light curves with exoUPRF.

Basic Transit Light Curve Fits