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.,
.. math::
\text{light curve} = \text{transit} + \sum_{i=1}^N X_i\theta_i,
where :math:`\theta_i` is a set of :math:`N` user-defined systematics vectors, and :math:`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:
.. code-block:: python
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.
.. code-block:: python
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.
.. code-block:: python
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.
.. toctree::
:maxdepth: 2
notebooks/tutorial_basic-transit-fitting