Welcome to OrbDot!

OrbDot is a Python package for studying the secular (long-term) evolution of exoplanet orbits using observational data. Using nested sampling algorithms, it fits evolutionary models using any combination of transit and eclipse timing, radial velocities, and transit durations.

OrbDot can further aid in the interpretation of model fitting results through its Analyzer class, which generates reports of model comparisons, derived tidal decay parameters, predicted precession rates, implications for planetary companions, and more.

To see the OrbDot source code, check out the GitHub repository.

In addition to this documentation, there is a complementary TrES-1 b case study that showcases the full functionality of OrbDot’s model-fitting and interpretive tools, while providing a deeper dive into the theoretical foundations behind the package.

Why OrbDot?

1. It’s easy to get started.

• Just populate a settings file with file path names, model fitting parameters, and a bit of info about the planetary system. OrbDot will do the rest!

2. Nested sampling, simplified.

• With OrbDot, there’s no need to spend hours learning how to implement nested sampling packages. Just specify the model you want to fit and provide a list of free parameters, in any order.

3. Seamless joint fitting.

• Fit any combination of data types simultaneously.

4. Flexible model fitting options.

• Customize the evidence tolerance, number of live points, prior distributions, and more.

• Update prior distributions and fixed parameter values between model fits.

5. Smart data handling.

• Automatically splits radial velocity data from different sources when fitting instrument-dependent parameters.

• Recognizes transit vs. eclipse mid-times by a half-decimal epoch number (0.5).

• Automatically differentiates sources of data when plotting.

6. Saves all the outputs you need.

• Comprehensive output files include easy-to-read text summaries of the results, corner plots, weighted samples, best-fit model plots, and more.

7. Built-in functionality for scientific interpretation.

• With the Analyzer class, you can easily use the model fit results to determine key quantities under various theoretical frameworks for further interpretation.

8. Transparency.

• While this package is intended to make complex analyses simple, it is not designed to be a black box. Between this website, a published case-study (CITE), and well-documented source code, all the inner workings of OrbDot are discoverable.

Contents

• Installation
• Citing OrbDot
• Bibliography
• Acknowledgements
• Contributing to OrbDot

Examples

• Orbital Decay of WASP-12 b
  • Setup
    • Data
    • System Info File
    • Settings File
  • Model Fits
    • Constant-Period Model Fit
    • Orbital Decay Fit
    • Apsidal Precession Fit
  • Interpreting the Results
    • Model Comparison
    • Orbital Decay Analysis
  • Conclusion
• Long-Term Radial Velocity Trends
  • Setup
    • Data
    • System Info Files
    • Settings Files
  • HAT-P-4 b
    • Model Fits
    • Interpretation
      • Model Comparison
      • Outer Companion Constraints
  • HAT-P-22 b
    • Model Fits
    • Interpretation
      • Model Comparison
      • Outer Companion Constraints

Using OrbDot

• Getting Started
  • Creating a StarPlanet Instance
  • The Settings File
    • Default Settings
  • Data Files
    • TTV Data
    • RV Data
    • TDV Data
  • The System Info File
    • Default Info File
• Model Fitting
  • Running Model Fits
    • TTV Model Fits
      • TTV “clipping”
    • RV Model Fits
    • TDV Model Fits
    • Joint Fits
  • Fixed Parameter Values
  • Priors
  • Output Files
    • The "*_summary.txt" File
    • The "*_results.json" File
  • Interpreting the Results
    • Analyzer Methods
      • 1. Model Comparison
      • 2. Orbital Decay Model Fit
      • 3. Apsidal Precession Model Fit
      • 4. Systemic Proper Motion Analysis
      • 5. Orbital Decay Predictions
      • 6. Apsidal Precession Predictions
      • 7. Companion Planet Analysis
      • 8. Resolved Binary Analysis
    • Analyzer Attributes
• Theory
  • Model Parameters
  • Coordinate System
  • Transit and Eclipse Timing Models
    • Constant-Period
      • ttv_constant()
    • Orbital Decay
      • ttv_decay()
    • Apsidal Precession
      • ttv_precession()
  • Radial Velocity Models
    • Background
    • Constant-Period
      • rv_constant()
    • Orbital Decay
      • rv_decay()
    • Apsidal Precession
      • rv_precession()
  • Transit Duration Models
    • Constant-Period
      • tdv_constant()
    • Orbital Decay
      • tdv_decay()
    • Apsidal Precession
      • tdv_precession()
  • The theory Module
    • Equilibrium Tides
      • decay_star_pdot_from_quality_factor()
      • decay_star_quality_factor_from_pdot()
      • decay_planet_pdot_from_quality_factor()
      • decay_planet_quality_factor_from_pdot()
      • decay_empirical_quality_factor()
      • decay_timescale()
      • decay_energy_loss()
      • decay_angular_momentum_loss()
    • Apsidal Precession
      • General Relativity
        • precession_gr()
      • Rotation
        • precession_rotational_planet()
        • precession_rotational_planet_k2()
        • precession_rotational_star()
        • precession_rotational_star_k2()
      • Tides
        • precession_tidal_planet()
        • precession_tidal_planet_k2()
        • precession_tidal_star()
        • precession_tidal_star_k2()
      • Precession-Induced Transit Variations
        • get_pdot_from_wdot()
        • get_tdot_from_wdot()
    • Proper Motion
      • proper_motion_idot()
      • proper_motion_wdot()
      • proper_motion_pdot()
      • proper_motion_tdot()
      • proper_motion_shklovskii()
    • Companion Planets
      • Long-Term Radial Velocity Trends
        • companion_mass_from_rv_trend()
        • companion_rv_trend_from_mass()
        • companion_doppler_pdot_from_rv_trend()
        • companion_doppler_rv_trend_from_pdot()
        • companion_from_quadratic_rv()
      • Companion-Induced Precession
        • companion_precession()
        • companion_mass_from_precession()
    • Resolved Stellar Binary
      • resolved_binary_mass_from_rv_trend()
      • resolved_binary_rv_trend_from_mass()

API

• Classes
  • StarPlanet
    • StarPlanet.__init__()
    • StarPlanet.update_default()
    • StarPlanet.update_prior()
  • Analyzer
    • Analyzer.__init__()
    • Analyzer.apsidal_precession_fit()
    • Analyzer.apsidal_precession_predicted()
    • Analyzer.model_comparison()
    • Analyzer.orbital_decay_fit()
    • Analyzer.orbital_decay_predicted()
    • Analyzer.proper_motion()
    • Analyzer.resolved_binary()
    • Analyzer.rv_trend_linear()
    • Analyzer.rv_trend_quadratic()
    • Analyzer.unknown_companion()
  • NestedSampling
    • NestedSampling.__init__()
    • NestedSampling.clear_index()
    • NestedSampling.generate_random_samples()
    • NestedSampling.get_best_fit()
    • NestedSampling.get_index()
    • NestedSampling.get_vals()
    • NestedSampling.print_results()
    • NestedSampling.prior_transform()
    • NestedSampling.run_multinest()
    • NestedSampling.run_nestle()
    • NestedSampling.save_random_samples()
    • NestedSampling.save_results()
    • NestedSampling.save_summary()
    • NestedSampling.save_weighted_samples()
  • JointFit
    • JointFit.__init__()
    • JointFit.run_joint_fit()
    • JointFit.run_rv_tdv_fit()
    • JointFit.run_ttv_rv_fit()
    • JointFit.run_ttv_rv_tdv_fit()
    • JointFit.run_ttv_tdv_fit()
    • JointFit.rv_tdv_loglike_constant()
    • JointFit.rv_tdv_loglike_decay()
    • JointFit.rv_tdv_loglike_precession()
    • JointFit.ttv_rv_loglike_constant()
    • JointFit.ttv_rv_loglike_decay()
    • JointFit.ttv_rv_loglike_precession()
    • JointFit.ttv_rv_tdv_loglike_constant()
    • JointFit.ttv_rv_tdv_loglike_decay()
    • JointFit.ttv_rv_tdv_loglike_precession()
    • JointFit.ttv_tdv_loglike_constant()
    • JointFit.ttv_tdv_loglike_decay()
    • JointFit.ttv_tdv_loglike_precession()
  • TransitTiming
    • TransitTiming.__init__()
    • TransitTiming.clip()
    • TransitTiming.run_ttv_constant()
    • TransitTiming.run_ttv_decay()
    • TransitTiming.run_ttv_fit()
    • TransitTiming.run_ttv_precession()
    • TransitTiming.ttv_loglike_constant()
    • TransitTiming.ttv_loglike_decay()
    • TransitTiming.ttv_loglike_precession()
  • RadialVelocity
    • RadialVelocity.__init__()
    • RadialVelocity.run_rv_constant()
    • RadialVelocity.run_rv_decay()
    • RadialVelocity.run_rv_fit()
    • RadialVelocity.run_rv_precession()
    • RadialVelocity.rv_loglike_constant()
    • RadialVelocity.rv_loglike_decay()
    • RadialVelocity.rv_loglike_precession()
    • RadialVelocity.save_rv_residuals()
  • TransitDuration
    • TransitDuration.__init__()
    • TransitDuration.run_tdv_constant()
    • TransitDuration.run_tdv_decay()
    • TransitDuration.run_tdv_fit()
    • TransitDuration.run_tdv_precession()
    • TransitDuration.tdv_loglike_constant()
    • TransitDuration.tdv_loglike_decay()
    • TransitDuration.tdv_loglike_precession()
• Models
  • Theory
  • companion_doppler_pdot_from_rv_trend()
  • companion_doppler_rv_trend_from_pdot()
  • companion_from_quadratic_rv()
  • companion_mass_from_precession()
  • companion_mass_from_rv_trend()
  • companion_precession()
  • companion_rv_trend_from_mass()
  • decay_angular_momentum_loss()
  • decay_empirical_quality_factor()
  • decay_energy_loss()
  • decay_get_equilibrium_spin_freq()
  • decay_get_f_e()
  • decay_get_g_e()
  • decay_get_h_e()
  • decay_planet_pdot_from_quality_factor()
  • decay_planet_quality_factor_from_pdot()
  • decay_star_pdot_from_quality_factor()
  • decay_star_quality_factor_from_pdot()
  • decay_timescale()
  • get_pdot_from_wdot()
  • get_semi_major_axis_from_period()
  • get_tdot_from_wdot()
  • precession_gr()
  • precession_rotational_planet()
  • precession_rotational_planet_k2()
  • precession_rotational_star()
  • precession_rotational_star_k2()
  • precession_tidal_planet()
  • precession_tidal_planet_k2()
  • precession_tidal_star()
  • precession_tidal_star_k2()
  • proper_motion_idot()
  • proper_motion_pdot()
  • proper_motion_shklovskii()
  • proper_motion_tdot()
  • proper_motion_wdot()
  • resolved_binary_mass_from_rv_trend()
  • resolved_binary_rv_trend_from_mass()
  • Transit and Eclipse Timing Models
  • ttv_constant()
  • ttv_decay()
  • ttv_precession()
  • Radial Velocity Models
  • rv_constant()
  • rv_decay()
  • rv_precession()
  • solve_keplers_equation()
  • true_anomaly()
  • Transit Duration Models
  • tdv_constant()
  • tdv_decay()
  • tdv_precession()
  • transit_duration()
• Tools
  • Priors
  • gaussian_prior()
  • get_prior()
  • log_prior()
  • uniform_prior()
  • Stats
  • calc_chi2()
  • credible_intervals()
  • propagate_err_ecosw_esinw()
  • propagate_err_sq_ecosw_sq_esinw()
  • quantiles()
  • Utilities
  • assign_default_values()
  • bjd_to_hjd()
  • calculate_epochs()
  • hjd_to_bjd()
  • merge_dictionaries()
  • raise_not_valid_param_error()
  • read_rv_data()
  • read_tdv_data()
  • read_ttv_data()
  • split_rv_instrument_params()
  • split_rv_instrument_results()
  • wrap()
  • Plots
  • corner_plot()
  • make_rv_plots()
  • make_tdv_plot()
  • make_ttv_plot()
  • periodogram()
  • read_random_samples()