PyLightcurve

A python package for analysing exoplanet light-curves.

In PyLightcurve you will find tools for:

Calculation of limb darkening coefficients.
Calculation of exoplanetary orbits.
Calculation of exoplanet transit and eclipse properties.
Exoplanet transit and eclipse modeling.
Flexible fitting of multi-epoch and multi-colour exoplanet transit and eclipse light-curves.
Transformations between different angle and timing systems.

Developed by Angelos Tsiaras

PyLightcurve makes use of the following packages:

and of the following catalogues:

Exoplanet Characterisation Catalogue, developed as part of the ExoClock Project, Kokori et al. 2020

If you are using PyLightcurve for your research please cite all the above references individually and also:

Tsiaras et al. 2016

Updates in version 4.0

Deprecation notice

PyLightcurve 4.0 no longer supports the use of the Open Exoplanet Catalogue (OEC), due to the large number of mistakes in the catalogue and the absence of parameters updates. OEC has been replaced by the Exoplanet Characterisation Catalogue, dedicated to transiting exoplanets. This catalogue does not contain all the exoplanets at the moment but will be continuously updated with more planets.

Multi-epoch and multi-color data fitting

Version 4.0 brings a new easy way of simultaneously fitting light curves from different sources (different flux and time formats, different exposure times), different filters (multi-colour) and different epochs (multi-epoch).

Eclipse model and eclipse data fitting

We now have the option of modeling eclipse data (finally!) and also tools to calculate the eclipse mid-time, eclipse depth and eclipse duration, based of the orbital characteristics of the planet.

Limb-darkening coefficients

In this version, the default limb-darkening coefficients are calculated using the new package ExoTETHyS. This allows the calculation of the limb-darkening coefficients even for stars cooler than 3500 K.

Angles and times

PyLighrcurve 4.0 includes flexible objects for converting different expressions of angles (e.g. '+47:12:34.05' to degrees) and of timing systems (e.g. HJD_UTC to BJD_TDB).

Installation

Install PyLightcurve through pip:

pip install pylightcurve

... or download this repo, cd in it and use the setup.py file:

git clone https://github.com/ucl-exoplanets/pylightcurve
cd pylightcurve
python setup.py install

If you are looking for the previous version of PyLightcurve (v.3), check the relevant branch:

https://github.com/ucl-exoplanets/pylightcurve/tree/pylightcurve-3

Usage

Exoplanets - using the plc.Planet object

In Pylightcurve 4.0.0 we can access all the old and new calculations related to exoplanets through the newly introduced plc.Planet object. These calculation aare:

limb-darkening coefficients
transit model
transit data fitting
transit duration
transit depth
planet-to-star flux ratio
eclipse time
eclipse model
eclipse data fitting
eclipse duration
eclipse depth
exoplanet orbital position
planet-star projected distance

We start by importing Pylightcurve, together with Numpy and Matplotib.

import pylightcurve as plc
import matplotlib.pyplot as plt
import numpy as np

We can then define a plc.Planet object for our favorite exoplanet, HD 209458 b.

planet = plc.Planet(
    name='HD209458b', 
    
    ra = 330.795,                  # float values are assumed to be in degrees,
                                   # alternatively, you can provide a plc.Hours or plc.Degrees object
                                   # here it would be plc.Hours('22:03:10.7729')
    
    dec = 18.884,                  # float values are assumed to be in degrees,
                                   # alternatively, you can provide a plc.Hours or plc.Degrees object
                                   # here it would be plc.Degrees('+18:53:03.548')
    
    stellar_logg = 4.36,           # float, in log(cm/s^2)
    
    stellar_temperature = 6065.0,  # float, in Kelvin
    
    stellar_metallicity = 0.0,     # float, in dex(Fe/H) or dex(M/H)
    
    rp_over_rs = 0.12086,          # float, no units
    
    period = 3.5247486,            # float, in days
    
    sma_over_rs = 8.76,            # float, no units
    
    eccentricity = 0.0,            # float, no units
    
    inclination = 86.71,           # float values are assumed to be in degrees,
                                   # alternatively, you can provide a plc.Hours or plc.Degrees object
                                   # here it would be plc.Degrees(86.71)           
    
    periastron = 0.0,              # float values are assumed to be in degrees,
                                   # alternatively, you can provide a plc.Hours or plc.Degrees object
                                   # here it would be plc.Degrees(0.0)
    
    mid_time = 2452826.62928,      # float, in days
    
    mid_time_format = 'BJD_TDB',   # str, available formats are JD_UTC, MJD_UTC, HJD_UTC, HJD_TDB, BJD_UTC, BJD_TDB    
    
    ldc_method = 'claret',         # str, default = claret, the other methods are: linear, quad, sqrt
    
    ldc_stellar_model = 'phoenix', # str, default = phoenix, the other model is atlas
    
    albedo = 0.15,                 # float, default = 0.15, no units 
    
    emissivity = 1.0,              # float, default = 1.0, no units
)

We can quickly create a plc.Planet object based on catalague data as follows:

planet = plc.get_planet('hd209458b')

At the moment the data provided are base on the Exoplanet Characterisation Catalogue (ECC) developed as part of the ExoClock Project. The catalogue contains 370 objects and will gradually expand in future releases.

To retrieve a list of all the available planet names we can type:

all_planets = plc.get_all_planets()

Filters

There is a number of parameters for every planet that do depend on the observing filter and are necessary to calculate the correct transit/eclipse models at different wavelengths and to allow the simultaneous analysis of multi-wavelength light-curves:

the planet-to-star radius ratio (rp_over_rs)
the limb-darkening coefficients (limb_darkening_coefficients)
the planet-to-star flux ratio (fp_over_fs)

By default, a plc.Planet object contains the above parameters for a number of standard filters:

clear
luminance
JOHNSON_U
JOHNSON_B
JOHNSON_V
COUSINS_R
COUSINS_I
2mass_j
2mass_h
2mass_ks
sdss_u
sdss_g
sdss_r
sdss_i
sdss_z
Kepler
TESS
irac1 (available only for the atlas model, if phoenix is chosen, it will change automatically to atlas, with more restrictions on the minimum temperature available, 3500K)
irac2 (available only for the atlas model, if phoenix is chosen, it will change automatically to atlas, with more restrictions on the minimum temperature available, 3500K)
irac3 (available only for the atlas model, if phoenix is chosen, it will change automatically to atlas, with more restrictions on the minimum temperature available, 3500K)
irac4 (available only for the atlas model, if phoenix is chosen, it will change automatically to atlas, with more restrictions on the minimum temperature available, 3500K)

In these default calculations:

the rp_over_rs is equal to the value defined when creating the plc.Planet object,
the limb-darkening coefficients are calculated using the filter response curves, together with the stellar parameters, the ldc_method and the the ldc_stellar_model defined when creating the plc.Planet object (more in the ExoTETHyS package),
the planet-to-star flux ratio (reflected + emmitted) is calculated using the albedo and

Pylightcurve

Install / Use

README