Transit models for TTV measurements

Transit models for TTV measurements#

The TTV transit models fit independent mid-transit times instead of forcing all events to follow the same Tc + N * P ephemeris. They keep the usual transit shape parameters (R_Rs, impact parameter or inclination, stellar density or a_Rs, eccentricity parametrization and limb darkening), but replace the single global conjunction epoch with one fitted Tc per observed transit.

These models are the right choice when the measured transit times themselves are the scientific product. For ordinary transit fits with one shared inferior-conjunction epoch, use Transit light-curve models.

The examples in the external PyORBIT_examples TTV directory show the same four workflows described below: one file per transit, transit identifiers in a subset column, an external transit-time list, and ancillary columns carrying the transit identifiers.

Shared planet setup#

TTV models force the planet to use inferior-conjunction times. It is still good practice to state this explicitly in the planet common object:

1planet_b:
2  common: planets
3  orbit: circular
4  parametrization: Eastman2013
5  use_time_inferior_conjunction: True

The period P is still part of the planet common object. It provides the linear ephemeris used to label or initialize transit events, while the observed mid-times are fitted as independent Tc parameters.

The optional model keywords Tc_boundaries, Tc_bounds and Tc_priors can be used to override the default bounds or priors assigned to the fitted transit times.

Model families#

Workflow

Batman model

PyTransit model

Transit-time parameters

One dataset per transit

batman_transit_ttv

pytransit_transit_ttv

one dataset-level Tc for each dataset

Transit IDs from subset

batman_transit_ttv_subset

pytransit_transit_ttv_subset

Tc_0, Tc_1, … from the dataset subsets

External transit-time list

batman_transit_ttv_tclist

pytransit_transit_ttv_tclist

Tc_N for events selected from the list

Transit IDs from ancillary columns

batman_transit_ttv_ancillary

pytransit_transit_ttv_ancillary

Tc_N from the selected ancillary flag

The aliases subset_batman_transit_ttv, subset_pytransit_transit_ttv, tclist_batman_transit_ttv, tclist_pytransit_transit_ttv, ancillary_batman_transit_ttv and ancillary_pytransit_transit_ttv are also accepted.

Sharing transit times across datasets#

By default, fitted TTV parameters can be local to each dataset/model instance. Set use_shared_ttv: True when the same transit time must be shared by multiple light curves, instruments or passbands.

1lc_model:
2  model: batman_transit_ttv_tclist
3  planets: [b]
4  limb_darkening: ld_quadratic
5  use_shared_ttv: True

This is especially useful for simultaneous multi-instrument observations and for multi-planet configurations where each planet has its own transit-time list.

One dataset per transit#

Use batman_transit_ttv or pytransit_transit_ttv when each input file contains one transit event. This is the most explicit layout: every dataset gets its own dataset-level Tc.

 1input:
 2  LCdata_transit00:
 3    file: individual_transits/lc_transit00.dat
 4    kind: Phot
 5    models:
 6      - lc_model
 7
 8  LCdata_transit01:
 9    file: individual_transits/lc_transit01.dat
10    kind: Phot
11    models:
12      - lc_model
13
14lc_model:
15  model: batman_transit_ttv
16  planets: [b]
17  limb_darkening: ld_quadratic

Use this form when the light curves are already split by transit and no extra transit identifier column is needed.

TTVs from dataset subsets#

Use the _subset models when one file contains many transits and the dataset has a subset column identifying the event. The example data in PyORBIT_examples/ttv_measurement/subset_transits use a header like:

# time flux flux_error jitter offset subset

Each non-negative subset value identifies a fitted transit time. For example, subset 0 maps to Tc_0, subset 1 maps to Tc_1, and so on.

 1input:
 2  LCdata_inst0:
 3    file: subset_transits/lc_inst0.dat
 4    kind: Phot
 5    models:
 6      - lc_model_inst0
 7
 8lc_model_inst0:
 9  model: pytransit_transit_ttv_subset
10  planets: [b]
11  limb_darkening: ld_quadratic
12  use_shared_ttv: True

This layout is convenient when different instruments observe the same sequence of transits and the fitted Tc_N values must be common to all of them.

TTVs from an external transit-time list#

Use the _tclist models when the expected transit windows are stored in a separate file. The examples use a table with a planet label, transit identifier, expected transit time and transit window:

# planet transit_id transit_time transit_window
b 0 2.170000 0.50000
b 1 6.330000 0.50000

Declare the list in the planet common object:

 1planet_b:
 2  common: planets
 3  orbit: circular
 4  parametrization: Eastman2013
 5  use_time_inferior_conjunction: True
 6  TTV_Tc_list: tclist_transits/WASP47_simulated_planetb_tclist.dat
 7
 8lc_model:
 9  model: batman_transit_ttv_tclist
10  planets: [b]
11  limb_darkening: ld_quadratic
12  minimum_number_of_observations: 20
13  use_shared_ttv: False

The model searches the dataset around each listed transit window and creates a fitted Tc_N parameter for the events with enough data points. Increase minimum_number_of_observations to skip poorly covered windows.

For a multi-planet TTV fit, give each planet its own TTV_Tc_list and include all planets in the same model:

1lc_model:
2  model: batman_transit_ttv_tclist
3  planets: [b, c]
4  limb_darkening: ld_quadratic
5  use_shared_ttv: True

TTVs from ancillary transit flags#

Use the _ancillary models when the input file already includes one column that labels the transit number for each planet. The two-planet examples use columns like:

# time flux flux_error jitter offset subset id_transit_b id_transit_c

Connect the planet to the correct ancillary column with TTV_Tc_flag:

 1planet_b:
 2  common: planets
 3  orbit: circular
 4  parametrization: Eastman2013
 5  use_time_inferior_conjunction: True
 6  TTV_Tc_flag: id_transit_b
 7
 8lc_model:
 9  model: pytransit_transit_ttv_ancillary
10  planets: [b]
11  limb_darkening: ld_quadratic
12  use_shared_ttv: False

Rows with a negative flag are ignored; non-negative identifiers are mapped to the corresponding Tc_N parameter.

Choosing the workflow#

Use the one-dataset-per-transit models for small, already segmented light-curve sets. Use _subset when a standard PyORBIT subset column already identifies the transit event. Use _tclist when the event windows are easier to maintain outside the light-curve files, especially for multi-planet systems. Use _ancillary when the transit IDs are already part of the data table or when different planets require different event labels in the same file.