Welcome to Susie’s documentation!

Susie is a Python package for modeling the orbital evolution of exoplanets using transit and occultation timing data. It helps detect and characterize tidal orbital decay and apsidal precession, offering statistical tools to compare models and infer the physical processes shaping close-in planetary systems—linking timing data to insights on tidal dissipation, planetary interiors, and dynamical interactions.

About

Susie is a Python package for fitting models to exoplanet transit and occultation timing data in order to investigate orbital evolution. It is designed to detect deviations from constant orbital motion, such as tidal orbital decay or apsidal precession, by fitting the data to different timing models and comparing their statistical likelihoods.

Susie supports three models:

• Linear: constant-period orbit (no orbital evolution)

• Quadratic: changing orbital period (e.g., due to tidal decay)

• Sinusoidal: precession of the orbit (e.g., due to apsidal motion)

The workflow is as follows:

1. Fit your timing data to one or more of the models (linear, quadratic, or sinusoidal).

2. Evaluate the quality of the model fit using the Bayesian Information Criterion (BIC).

3. Compare models using ΔBIC (difference in BIC values) to determine which model best explains the data.

4. Visualize model parameters and fit residuals to better interpret the orbital behavior.

A lower BIC indicates a better-fitting model. ΔBIC is computed as the BIC of one model minus the BIC of another. While it’s common to compare a non-linear model (quadratic or sinusoidal) against a linear one to test for non-constant orbits, any pair of models can be compared. A positive ΔBIC value indicates that the second model better explains the data (i.e., it has a lower BIC).

Susie allows you to:

• Fit individual models and examine their parameter estimates and fit diagnostics.

• Automatically fit multiple models and return a summary of BIC values and pairwise ΔBIC comparisons.

• Generate clear visualizations to assess model performance and potential orbital changes.

To get started, load your timing data using the timing_data.py object, then pass it to ephemeris.py to perform model fitting, comparison, and visualization.

Planned features include:

• Integration with Astroplan to plan future transit observations.

• Improved parameter estimation using the emcee MCMC sampler.

• Extended support for distinguishing precession from decay in ambiguous timing signals.

Note

This project is under active development.

Quickstart

1. Install the latest released version from the Python Package Index PyPi:

   pip install susie
   

2. Include at the top of your Python file or notebook:

   import susie
   

   or

   from susie.timing_data import TimingData
   from susie.ephemeris import Ephemeris
   

Documentation

• User Guide
  • Timing Data module
    • TimingData
  • Ephemeris module
    • Ephemeris
      • Ephemeris.fit_model()
      • Ephemeris.get_model_uncertainties()
      • Ephemeris.calc_bic()
      • Ephemeris.calc_delta_bic()
      • Ephemeris.create_observer_obj()
      • Ephemeris.create_target_obj()
      • Ephemeris.get_observing_schedule()
      • Ephemeris.plot_model()
      • Ephemeris.plot_timing_uncertainties()
      • Ephemeris.plot_oc_plot()
      • Ephemeris.plot_running_delta_bic()
      • Ephemeris.plot_delta_bic_omit_one()
      • Ephemeris.plot_running_analytical_delta_bic_quadratic()
      • Ephemeris.plot_running_analytical_delta_bic_precession()
• Frequently Asked Questions
  • question here
  • another question here

Tutorials

• Basic Usage of TimingData and Ephemeris Objects
  • 🔵 Basic Usage
    • 🔷 STEP 1: Download the timing data (that includes occultations) from the GitHub repository
    • 🔷 STEP 2: Add your transit and occultation data to the TimingData object.
    • 🔷 STEP 3: Create the Ephemeris object and add your TimingData object.
    • 🔷 STEP 4: Fit your transit time data to an ephemeris model. You can specify what type of model with the options ‘linear’ or ‘quadratic’.
      • 🔹 The Linear Model
      • 🟢 EXAMPLE
      • 🔹 The Quadratic Model
      • 🟢 EXAMPLE
      • 🔹 The Precession Model
      • 🟢 EXAMPLE
    • 🔷 STEP 5: Get BIC Values
    • 🔷 STEP 6: Plot your data!
      • 🔹 Plot the model calculated mid-times
      • 🔹 Plot the model uncertainties
      • 🔹 The O-C Plot
      • 🔹 Plot the running $\Delta$ BIC
      • 🔹 Plot the analytical running $\Delta$ BIC
      • 🔹 Plot the omit one $\Delta$ BIC
• Special TimingData Object Usage
  • 🔵 Other Timing Data Formats and Options
    • 🔷 Download the example timing data (includes transit and occultation data in Barycentric Julian Date) from the GitHub repository
    • 🔷 Using Timing Data that is NOT in JD TDB Format and/or System
      • 🔹 Option 1: Including BOTH Object Coordinates and Observatory Coordinates
      • 🔹 Option 2: Including ONLY Object Coordinates
    • 🔷 Using Timing Data that does NOT include uncertainties
    • 🔷 Using Timing Data that does NOT include a transit or occultation array
• Generating an Observing Schedule
  • 🔵 Import the necessary python libraries and Susie objects.
  • 🔵 Import Data
  • 🔵 The Package
    • 🔷 STEP 1: Add your transit and occultation data to the TimingData object.
    • 🔷 STEP 2: Create the Ephemeris object and add your TimingData object.

Indices and tables

• Index

• Module Index

• Search Page

The developers were supported by grants from NASA’s TESS Cycle-5 Guest Investigator program (NNH21ZDA001N-TESS), Exoplanets Research Program (NNH21ZDA001N-XRP), and from the Idaho Space Grant Consortium.