API¶

This page details the methods and classes provided by the TransitFit module.

Top-Level Interface¶

A function which will run everything when given a path to light curve and priors!

transitfit._pipeline.run_retrieval(data_files, priors, filter_info=None, detrending_list=[['nth order', 1]], limb_darkening_model='quadratic', ld_fit_method='independent', fitting_mode='auto', max_batch_parameters=25, batch_overlap=2, host_T=None, host_logg=None, host_z=None, host_r=None, nlive=300, dlogz=None, maxiter=None, maxcall=None, dynesty_sample='rslice', dynesty_bounding='multi', normalise=True, detrend=True, results_output_folder='./output_parameters', final_lightcurve_folder='./fitted_lightcurves', summary_file='summary_output.csv', full_output_file='full_output.csv', plot_folder='./plots', plot=True, marker_color='dimgrey', line_color='black', ldtk_cache=None, ldtk_samples=20000, do_ld_mc=False, data_skiprows=0, allow_ttv=False, filter_delimiter=None, detrending_limits=None, normalise_limits=None, bin_data=False, cadence=2, binned_color='red', walks=100, slices=10, n_procs=1, check_batchsizes=False, median_normalisation=False, error_scaling=False, error_scaling_limits=None, ldtk_uncertainty_multiplier=1.0)¶

Runs a full retrieval of posteriors using nested sampling on a transit light curve or a set of transit light curves. For more guidance on the use of input files and structuring, see the TransitFit documentation.

Parameters:

data_files (str) – The path to the data input .csv file, which contains the paths to the light curve data.
priors (str) – Path to a .csv file containing prior information on each variable to be fitted.
filter_info (str, optional) –
Path to a .csv file containing information on the wavelengths of the filters that observations were made at.

This is required if ld_fit_method is ‘single’ or ‘coupled’. If not None and host_T, host_logg and host_z are not None, retrieval will include fitting realistic limb darkening parameters for the filters. Default is None.
detrending_list (array_like, shape (n_detrending_models, 2)) –
A list of different detrending models. Each entry should consist of a method and a second parameter dependent on the method. Accepted methods are

['nth order', order]

['custom', function, [global fit indices], [filter fit indices], [epoch fit indices]]

['off', ]

function here is a custom detrending function. TransitFit assumes that the first argument to this function is times and that all other arguments are single-valued - TransitFit cannot fit list/array variables. If ‘off’ is used, no detrending will be applied to a light curve using this model.

If a custom function is used, and some inputs to the function should not be fitted individually for each light curve, but should instead be shared either globally, within a given filter, or within a given epoch, the indices of where these fall within the arguments of the detrending function should be given as a list. If there are no indices to be given, then use an empty list: [] e.g. if the detrending function is given by:
```
foo(times, a, b, c, t0, P):
    # do something
```
and a should be fitted globally, then the entry in the method_list would be ['custom', foo, [1], [], []].
limb_darkening_model (str, optional) –
The limb darkening model to use. Allowed models are
- 'linear'
- 'quadratic'
- 'squareroot'
- 'power2'
- 'nonlinear'
With the exception of the non-linear model, all models are constrained by the method in Kipping (2013), which can be found at https://arxiv.org/abs/1308.0009. Default is ‘quadratic’.
ld_fit_method (str, optional) –
Determines the mode of fitting of limb darkening parameters. The available modes are:
- 'coupled' : all limb darkening parameters are fitted independently, but are coupled to a wavelength dependent model based on the host parameters through ldkt
- 'single' : LD parameters are still tied to a model, but only the first filter is actively fitted. The remaining filters are estimated based off the ratios given by ldtk for a host with the given parameters. This mode is useful for a large number of filters, as ‘coupled’ or ‘independent’ fitting will lead to much higher computation times.
- 'independent' : Each LD coefficient is fitted separately for each filter, with no coupling to the ldtk models.
- 'off' : no limb darkening fitting will occurr. If using this mode, it it strongly recommended to set values for the Kipping q parameters using the priors file.
Default is ‘independent’
fitting_mode ({'auto', 'all', '2_stage', 'folded', 'batched'}, optional) –
The approach TransitFit takes towards limiting the number of parameters being simultaneously fitted. The available modes are: - 'auto' : Will calculate the number of parameters required to fit

all the data simulataneously. If this is less than max_parameters, will set to 'all' mode, else will set to 'folded' if at least one filter has at least 3 epochs in it. Otherwise will set to 'batched'
- 'all' : Fits all parameters simultaneously, with no folding or batching of curves. Should be used with caution when fitting very large (~< 30) numbers of parameters.
- '2_stage' : Fits in 2 stages, first detrending the light curves and then fitting the detrended curves simultaneously, using the 'batched' approach if required.
- 'folded' : Useful for fitting curves with multiple epochs for each filter. TransitFit will fit each filter separately and produce a period-folded light curve for each filter, before fitting these simultaneously, using the 'batched' approach if required.
- 'batched' : Useful for large numbers of light curves with relatively few shared filters, so 'folded' loses large amounts of multi-epoch information. This mode splits the filters into sets of overlapping batches, runs each batch and uses the weighted means of each batch to produce a final result.
Default is 'auto'.
max_batch_parameters (int, optional) – The maximum number of parameters to use in a single retrieval when using 'folded' or 'batched' fitting modes. Default is 25.
batch_overlap (in, optional) – The number of filters or epochs to overlap adjacent batches by where possible. This ensures that adjacent batches share information. Default is 2.
host_T (tuple or None, optional) – The effective temperature of the host star, in Kelvin. Should be given as a (value, uncertainty) pair. Required if ld_fit_method is 'single' or 'coupled'. Default is None.
host_logg (tuple or None, optional) – The log_10 of the surface gravity of the host star, with gravity measured in cm/s2. Should be given as a (value, uncertainty) pair. Required if ld_fit_method is 'single' or 'coupled'. Default is None
host_z (tuple or None, optional) – The metalicity of the host, given as a (value, uncertainty) pair. Required if ld_fit_method is 'single' or 'coupled'. Default is None
host_r (tuple or None, optional) – The host radius in Solar radii, given as a (value, uncertainty) pair. Required for conversion of host-planet separation from AU to host radii
nlive (int, optional) – The number of live points to use in the nested sampling retrieval.
normalise (bool, optional) –
If True, will assume that the light curves have not been normalised and will fit normalisation constants within the retrieval. The range to fit normalisation constants c_n are automatically detected using

1/f_max <= c_n <= 1/f_min

as the default range, where f_min and f_max are the minimum and maximum flux values for a given light curve. Default is True.
detrend (bool, optional) – If False, no detrending will be attempted, even if specified by detrending list. Default is True
dlogz (float, optional) – Retrieval iteration will stop when the estimated contribution of the remaining prior volume to the total evidence falls below this threshold. Explicitly, the stopping criterion is ln(z + z_est) - ln(z) < dlogz, where z is the current evidence from all saved samples and z_est is the estimated contribution from the remaining volume. The default is 1e-3 * (nlive - 1) + 0.01.
maxiter (int or None, optional) – The maximum number of iterations to run. If None, will continue until stopping criterion is reached. Default is None.
maxcall (int or None, optional) – The maximum number of likelihood calls in retrieval. If None, will continue until stopping criterion is reached. Default is None.
dynesty_sample (str, optional) – Method used to sample uniformly within the likelihood constraint, conditioned on the provided bounds. Unique methods available are: uniform sampling within the bounds('unif'), random walks with fixed proposals ('rwalk'), random walks with variable (“staggering”) proposals ('rstagger'), multivariate slice sampling along preferred orientations ('slice'), “random” slice sampling along all orientations ('rslice'), “Hamiltonian” slices along random trajectories ('hslice'), and any callable function which follows the pattern of the sample methods defined in dynesty.sampling. ‘auto’ selects the sampling method based on the dimensionality of the problem (from ndim). When ndim < 10, this defaults to 'unif'. When 10 <= ndim <= 20, this defaults to 'rwalk'. When ndim > 20, this defaults to 'hslice' if a gradient is provided and 'slice' otherwise. 'rstagger' and 'rslice' are provided as alternatives for 'rwalk' and 'slice', respectively. Default is 'rslice'.
dynesty_bounding ({'none', 'single', 'multi', 'balls', 'cubes'}, optional) – The decomposition to use in sampling. Default is ‘multi’
results_output_folder (str, optional) – Folder to save results to. TransitFit will create subfolders within this if folded or batched runs are being used. Default is './output_parameters'
fitted_lightcurve_folder (str, optional) – The folder to save fitted light curves to. These files contain the normalised and detrended light curves, as well as the best fit curve. Default is './fitted_lightcurves'
summary_file (str, optional) – The file to save the summarised final parameter results to. These are calculated by taking weighted averages over any batched fitting. Default is 'summary_output.csv'
full_output_file (str, optional) – The file to save the full, non-summarised results to. This file gives the results for each batch, without averaging over batches to get summaried results. Default is 'full_output.csv'
plot_folder (str, optional) – Path to folder to save plots to. Default is './plots'
plot (bool, optional) – If True, will plot all fitted light curves within the fitting routine, including any from partial fitting (eg, single filter modes). Default is True.
marker_color (matplotlib color, optional) – The colour to plot data points on plots. Default is 'dimgray'.
line_colour (matplotlib color, optional) – The colour to plot best fit light curves on plots. Default is 'black'.
ldtk_cache (str, optional) – This is the path to cache LDTK files to. If not specified, will default to the LDTK default.
ldtk_samples (int, optional) – Controls the number of samples taken by PyLDTk when calculating LDCs when using 'coupled' or 'single' modes for limb darkening fitting. Default is 20000
do_ld_mc (bool, optional) – If True, will use MCMC sampling to more accurately estimate the uncertainty on intial limb darkening parameters provided by PyLDTk. Default is False.
data_skiprows (int, optional) – The number of rows to skip when reading in light curve data from a .txt file. Default is 0.
allow_ttv (bool, optional) – If True, will fit t0 for each epoch individually. Default is False.
filter_delimiter (str, optional) – The delimiter in filter profile files. Default is None, which will lead to pandas trying to auto detect the delimiter.
detrending_limits (list, optional) – The bounds on detrending coefficients, given as (lower, upper) pair for each detrending method. IF not provided, will default to ±10
bin_data (bool, optional) – If True, any folded light curves will be plotted with data binned to an observing cadence given by cadence. Default is False.
cadence (float, optional) – The observing cadence, in minutes, to bin data to if bin_data is True. Default is 2 (mirroring TESS observations)
binned_color (str, optional) – The color to use for binned data. Default is ‘red’.
n_procs (int, optional) – The maximum number of processes to use when running batches. If >1, will run batches in parallel. Default is 1.
median_normalisation (bool, optional) – Normalising lightcurves by the median of the flux value reduces the runtime in many cases. Default is False.
error_scaling (bool, optional) – If True, scales the errorbars in the lightcurves following https://emcee.readthedocs.io/en/stable/tutorials/line/
error_scaling_limits (list, optional) – If error_scaling=True, this is the limit of the parameter.
ldtk_uncertainty_multiplier (float, optional) – (From LDTK:) The uncertainty multiplier ϵ is a subjective factor that defines how strongly the LD profile (or the prior created from it) constrains the final analysis (that is, how much we trust the stellar atmosphere models used to create the profiles.)

Returns:

results – The results returned by Retriever.run_dynesty()

Return type:

dict

Retriever¶

Object which actually handles the retrieval process

class transitfit.retriever.Retriever(data_files, priors, n_telescopes, n_filters, n_epochs, filter_info=None, detrending_list=[['nth order', 1]], limb_darkening_model='quadratic', host_T=None, host_logg=None, host_z=None, host_r=None, ldtk_cache=None, n_ld_samples=20000, do_ld_mc=False, data_skiprows=0, allow_ttv=False, filter_delimiter=None, detrending_limits=None, normalise=True, normalise_limits=None, detrend=True, median_normalisation=False, error_scaling=False, error_scaling_limits=None, ldtk_uncertainty_multiplier=1.0)¶

Bases: object

Handles the nested sampling retrieval and acts as a high-level interface

Parameters:

data_files (str) – Path to the data input config file
priors (str) – Path to the priors config file
n_telescopes (int) – The number of different telescopes used in the data set
n_filters (int) – The number of different filters used in the data set
n_epochs (int) – The number of different epochs used in the data set
filter_info (str, optional) – The path to the filter profiles config file
detrending_list (list, optional) – The different detrending models to use
limb_darkening_model (str) – The limb darkening model to use
host_T (tuple or None, optional) – The effective temperature of the host star, in Kelvin. Should be given as a (value, uncertainty) pair. Required if ld_fit_method is 'single' or 'coupled'. Default is None.
host_logg (tuple or None, optional) – The log_10 of the surface gravity of the host star, with gravity measured in cm/s2. Should be given as a (value, uncertainty) pair. Required if ld_fit_method is 'single' or 'coupled'. Default is None
host_z (tuple or None, optional) – The metalicity of the host, given as a (value, uncertainty) pair. Required if ld_fit_method is 'single' or 'coupled'. Default is None
host_r (tuple or None, optional) – The host radius in Solar radii, given as a (value, uncertainty) pair. Required for conversion of host-planet separation from AU to host radii
ldtk_cache (str, optional) – This is the path to cache LDTK files to. If not specified, will default to the LDTK default.
n_ld_samples (int, optional) – Controls the number of samples taken by PyLDTk when calculating LDCs when using 'coupled' or 'single' modes for limb darkening fitting. Default is 20000
do_ld_mc (bool, optional) – If True, will use MCMC sampling to more accurately estimate the uncertainty on intial limb darkening parameters provided by PyLDTk. Default is False.
data_skiprows (int, optional) – The number of rows to skip when reading in light curve data from a .txt file. Default is 0.
allow_ttv (bool, optional) – If True, will fit t0 for each epoch individually. Default is False.
filter_delimiter (str, optional) – The delimiter in filter profile files. Default is None, which will lead to pandas trying to auto detect the delimiter.
detrending_limits (list, optional) – The bounds on detrending coefficients, given as (lower, upper) pair for each detrending method. If not provided, will default to ±10
error_scaling (bool, optional) – If True, scales the errorbars in the lightcurves following https://emcee.readthedocs.io/en/stable/tutorials/line/
error_scaling_limits (list, optional) – If error_scaling=True, this is the limit of the parameter.
ldtk_uncertainty_multiplier (float, optional) – (From LDTK:) The uncertainty multiplier ϵ is a subjective factor that defines how strongly the LD profile (or the prior created from it) constrains the final analysis (that is, how much we trust the stellar atmosphere models used to create the profiles.)

_calculate_n_params(lightcurves, indices, ld_fit_method, normalise, detrend)¶

Calculates the number of parameters which would be fitted for a given set of filter and epoch indices

This function exists because it’s much faster than repeatedly making PriorInfos for different combos.

Parameters:: indices (tuple) – The tuple of indices to consider. Must be given as (telescope_indices, filter_indices, epoch_indices)

_fold_lightcurves(results, priors, lightcurves)¶

Produces a set of folded lightcurves which can then be fitted across filters

Parameters:

results (array_like, shape (n_filters, )) – Each entry should be a list of results objects for each batch
priors (array_like, shape (n_filters, )) – Each entry should be a list of PriorInfo objects for each batch
lightcurves (array_like, shape (n_filters, )) – The lightcurves. Each entry should be a list of LightCurve arrays used for the batches within each filter

Returns:

folded_lightcurves (np.array, shape (1, n_filters, 1)) – All the lightcurves, with each filter folded onto one epoch.
folded_P (float) – The period that the lightcurves are folded with
folded_t0 (float) – The t0 that all lightcurves are centred on.

_format_indices(indices)¶: If passed a set of indices, checks they are usable. If indices is None, sets them to cover all of the possible values

_full_to_subset_index(subset_indices, full_index)¶

Converts an index which uses the notation of full parameter space to a subset. USeful for converting between overall indexing and indexing within a batch

Parameters:

subset_indices (tuple) – The indices which define the full subset of light curves
full_index (array_like, shape (3, )) – The full-notation index to be converted

_get_detrending_subset(indices)¶: Pulls out the detrending indices for the given telescope, filter and epoch indices (given as tuple), assuming that we are working on all input lightcurves, not a folded version (though that shouldn’t be using this function)

_get_folding_batches(max_parameters, ld_fit_method, detrend, normalise, overlap=2, random_order=True)¶

Splits all_lightcurves into single-filter, multi-epoch batches to be fitted, which will allow us to produce folded lightcurves. This includes the option to have batches overlapping so that they share some info.

Parameters:

max_parameters (int) – The maximum number of parameters to have in a single batch
ld_fit_method (str) – The limb darkening fit method
detrend (bool) – If True, detrending will be used
normalise (bool) – If true, normalisation will be used
overlap (int, optional) – The number of epochs to overlap in each batch. This will be adhered to where possible. Default is 2.
random_order (bool, optional) – If True, will shuffle the epochs before batching to reduce correlations from grouping them. Default is True

Returns:

batches – Each entry in the array is a list of batches for the given filter.

Return type:

array_like, shape (n_filters,)

_get_lightcurve_subset(lightcurves, indices)¶: Pulls out the subset of lightcurves given by the indices.

_get_non_folding_batches(lightcurves, max_parameters, ld_fit_method, detrend, normalise, overlap=2, error_scaling=False)¶

Splits lightcurves into batches by filter, attempting to ensure that batches do not require more than max_parameters to fit. Each batch will contain every light curve in the filter, which trumps max_parameters. Where possible, the filter batches will overlap, allowing each batch to share information on some level.

Parameters:

lightcurves (array_like, shape (n_telescopes, n_filters, n_epochs)) – The LightCurves
max_parameters (int) – The maximum number of parameters to have in a single batch
ld_fit_method (str) – The limb darkening fit method
detrend (bool) – If True, detrending will be used
normalise (bool) – If true, normalisation will be used
overlap (int, optional) – The number of epochs to overlap in each batch. This will be adhered to where possible. Default is 2.
lightcurves – The lightcurves to be batched.

Returns:

batches – The final batches. Each entry is a tuple of (telescope indices, filter indices, epoch indices) using the indices of lightcurves. Each of these batches can then be passed to _get_priors_and_curves.

Return type:

array_like, shape (n_batches)

_get_priors_and_curves(lightcurves, ld_fit_method, indices=None, detrend=True, normalise=True, folded=False, folded_P=None, folded_t0=None, suppress_warnings=False)¶

Generates a prior info for a particular run:

Parameters:

lightcurves (array_like) – An array of the light curves which will be golbally considered for fitting.
ld_fit_method ({'independent', 'single', 'coupled', 'off'}) – The mode to fit limb darkening coefficients with.
indices (tuple or None) – If None, will fit all light curves. Otherwise, supply relevant indices of lightcurves to fit as a tuple: (telescope_indices, filter_indices, epoch_indices)
detrend (bool, optional) – If True, will initialise detrending fitting. Default is True.
normalise (bool, optional) – If True, will initialise normalisation fitting. Default is True.
folded (bool, optional) – Set to True if using folded light curves (functionally only one epoch). Also turns off detrending and normalisation fitting. Default is False.
folded_P (float, optional) – Required if folded is True. This is the period that the light curves are folded to
folded_t0 (float, optional) – Required if folded is True. This is the t0 that the light curves are folded to. In the case where ttv mode is used (each epoch has been fitted to a different t0), then this should be the t0 of the first epoch (the one which everything else is folded back to)

Returns:

priors (PriorInfo) – The fully initialised PriorInfo object
lightcurves – The LightCurves in the correct format, with detrending and normalisation initialised

_get_unique_indices(indices)¶: When given a tuple of indices of all light curves to consider, gets all the unique values

_run_batched_retrieval(lightcurves, batches, ld_fit_method, detrend, normalise, maxiter, maxcall, sample, nlive, dlogz, full_return=False, folded=False, folded_P=None, folded_t0=None, output_folder='./output_parameters', summary_file='summary_output.csv', full_output_file='full_output.csv', lightcurve_folder='./fitted_lightcurves', plot=True, plot_folder='./plots', marker_color='dimgrey', line_color='black', bound='multi', filter_idx=None, walks=100, slices=10, n_procs=1)¶

Runs a retrieval using the given batches

lightcurvesarray_like, shape (n_telescopes, n_filters, n_epochs): The full lightcurves array to be retrieved.
full_returnbool, optional: If True will return all_results, all_priors, all_lightcurves. If False, will just return all_results. Default is False

_run_dynesty(lightcurves, priors, maxiter=None, maxcall=None, sample='auto', nlive=300, dlogz=None, bound='multi', plot_folder='./plots', walks=100, slices=10)¶

Runs dynesty on the given lightcurves with the given priors. Returns the result.

Returns:

results
ndof

_run_folded_retrieval(ld_fit_method, detrend, normalise, maxiter, maxcall, sample, nlive, dlogz, output_folder='./output_parameters', summary_file='summary_output.csv', full_output_file='full_output.csv', lightcurve_folder='./fitted_lightcurves', plot=True, plot_folder='./plots', marker_color='dimgrey', line_color='black', max_parameters=25, overlap=2, bound='multi', walks=100, slices=10, n_procs=1)¶: For each filter, runs retrieval, then produces a phase-folded lightcurve. Then runs retrieval across wavelengths on the folded curves.

_run_full_retrieval(ld_fit_method, detrend, normalise, maxiter, maxcall, sample, nlive, dlogz, output_folder='./output_parameters', summary_file='summary_output.csv', full_output_file='full_output.csv', lightcurve_folder='./fitted_lightcurves', plot=True, plot_folder='./plots', marker_color='dimgrey', line_color='black', bound='multi', walks=100, slices=10)¶: Runs full retrieval with no folding/batching etc. Just a straight forward dynesty run.

_subset_to_full_index(subset_indices, subset_index)¶

Converts an index from notation within a batch to the full indexing. Inverse of _full_to_subset_index

Parameters:

subset_indices (tuple) – The indices which define the full subset of light curves
subset_index (array_like, shape (3, )) – The subset-notation index to be converted

detrending_limits¶

detrending_limits = np.array(detrending_limits) if not detrending_limits.ndim == 2:

raise ValueError(f’Detrending limits should be provided as a list of length {len(self.detrending_info)} where each entry is the [lower, upper] limits on each method.’)

if not detrending_limits.shape[1] == 2:: raise ValueError(f’Detrending limits should be provided as a list of length {len(self.detrending_info)} where each entry is the [lower, upper] limits on each method.’)

run_retrieval(ld_fit_method='independent', fitting_mode='auto', max_parameters=25, maxiter=None, maxcall=None, sample='auto', nlive=300, dlogz=None, plot=True, output_folder='./output_parameters', lightcurve_folder='./fitted_lightcurves', summary_file='summary_output.csv', full_output_file='full_output.csv', plot_folder='./plots', marker_color='dimgray', line_color='black', bound='multi', normalise=True, detrend=True, overlap=2, bin_data=True, cadence=2, binned_color='red', walks=100, slices=10, n_procs=1)¶

Runs dynesty on the data. Different modes exist and can be specified using the kwargs.

Parameters:

ld_fit_method ({‘coupled’, ‘single’, ‘independent’, ‘off’}, optional) –
Determines the mode of fitting of limb darkening parameters. The available modes are:
- ’coupled’ : all limb darkening parameters are fitted independently, but are coupled to a wavelength dependent model based on the host parameters through ldkt
- ’single’ : LD parameters are still tied to a model, but only the first filter is actively fitted. The remaining filters are estimated based off the ratios given by ldtk for a host with the given parameters. This mode is useful for a large number of filters, as ‘coupled’ or ‘independent’ fitting will lead to much higher computation times.
- ’independent’ : Each LD coefficient is fitted separately for each filter, with no coupling to the ldtk models.
- ’off’ : Will use the fixed value provided in the input file
Default is ‘independent’
fitting_mode ({'auto', 'all', 'folded', 'batched'}, optional) – Determines if the fitting algorithm is limited by max_parameters. If the number of parameters to be fitted exceeds max_parameters, then the retrieval will split into fitting each filter independently, phase-folding the detrended light curves to produce a single light curve for each filter and then fitting these phase-folded curves simultaneously. If fitting_mode is ‘auto’, then the mode used will be determined automatically. If fitting_mode is ‘all’, then all light curves will be attempted to be fitted simultaneously, regardless of the value of max_parameters. If fitting_mode is ‘folded’, then the folding approach will be used. Default is ‘auto’.
max_parameters (int, optional) – The maximum number of parameters to use in a single retrieval. Default is 25.
maxiter (int or None, optional) – The maximum number of iterations to run. If None, will continue until stopping criterion is reached. Default is None.
maxcall (int or None, optional) – The maximum number of likelihood calls in retrieval. If None, will continue until stopping criterion is reached. Default is None.
sample (str, optional) – Method used to sample uniformly within the likelihood constraint, conditioned on the provided bounds. Unique methods available are: uniform sampling within the bounds(‘unif’), random walks with fixed proposals (‘rwalk’), random walks with variable (“staggering”) proposals (‘rstagger’), multivariate slice sampling along preferred orientations (‘slice’), “random” slice sampling along all orientations (‘rslice’), “Hamiltonian” slices along random trajectories (‘hslice’), and any callable function which follows the pattern of the sample methods defined in dynesty.sampling. ‘auto’ selects the sampling method based on the dimensionality of the problem (from ndim). When ndim < 10, this defaults to ‘unif’. When 10 <= ndim <= 20, this defaults to ‘rwalk’. When ndim > 20, this defaults to ‘hslice’ if a gradient is provided and ‘slice’ otherwise. ‘rstagger’ and ‘rslice’ are provided as alternatives for ‘rwalk’ and ‘slice’, respectively. Default is ‘auto’.
nlive (int, optional) – The number of live points to use in the nested sampling retrieval. Default is 300.
dlogz (float, optional) – Retrieval iteration will stop when the estimated contribution of the remaining prior volume to the total evidence falls below this threshold. Explicitly, the stopping criterion is ln(z + z_est) - ln(z) < dlogz, where z is the current evidence from all saved samples and z_est is the estimated contribution from the remaining volume. The default is 1e-3 * (nlive - 1) + 0.01.

transitfit.retriever._run_batch(x)¶: Subprocess to run a batch

Prior handling¶

Object to handle and deal with prior info for retrieval

class transitfit.priorinfo.PriorInfo(default_dict, limb_dark, n_telescopes, n_filters, n_epochs, allow_ttv=False, lightcurves=None)¶

Bases: object

Object to deal with anything involving priors

Parameters:

default_dict (dictionary) – Dictionary containing default parameter values.
limb_dark (str) – The limb darkening model to use.
n_telescopes (int) – The number of different telescopes used in the data set
n_filters (int) – The number of different filters used in the data set
n_epochs (int) – The number of different epochs used in the data set
allow_ttv (bool, optional) – If True, will fit t0 to each transit. Default is False.
lightcurves (array_like, shape(n_telescopes, n_filters, n_epochs)) – Array of the light curves. If there is no observation for a particular telescope, filter, epoch combination, then the value should be set to None.

_convert_unit_cube(cube)¶: Takes the unit cube provided by dynesty (all values between 0 and 1) and converts them into physical values

_interpret_final_results(results)¶: Generates a dictionary of results and a dictionary of errors from the final results of a run

_interpret_param_array(array)¶: Interprets the parameter cube generated by dynesty and returns them in a format usable by the LikelihoodCalculator

add_gaussian_fit_param(name, mean, stdev, telescope_idx=None, filter_idx=None, epoch_idx=None)¶: Adds a new parameter which will be fitted with a Gaussian prior

add_uniform_fit_param(name, low_lim, high_lim, telescope_idx=None, filter_idx=None, epoch_idx=None)¶: Adds a new parameter which will be fitted uniformly in the range given by low_lim and high_lim

fit_detrending(lightcurves, method_list, method_index_array, limits=None)¶: Intialises detrending

fit_limb_darkening(fit_method='independent', host_T=None, host_logg=None, host_z=None, filters=None, n_samples=20000, do_mc=False, cache_path=None, ldtk_uncertainty_multiplier=1.0)¶

Initialises fitting of limb darkening parameters, either independently or coupled across wavebands.

Parameters:

fit_method (str, optional) –
Determines the mode of fitting of LD parameters. The available modes are:
- ’coupled’ : all limb darkening parameters are fitted independently, but are coupled to a wavelength dependent model based on the host parameters
- ’single’ : LD parameters are still tied to a model, but only the first filter is actively fitted. The remaining filters are estimated based off the ratios given by ldtk for a host with the given parameters. This mode is useful for a large number of filters, as ‘coupled’ or ‘independent’ fitting will lead to much higher computation times.
- ’independent’ : Each LD coefficient is fitted separately for each filter, with no coupling to the ldtk models.
The default is ‘independent’.
host_T (tuple or None, optional) – The effective temperature of the host star, in Kelvin, given as a (value, uncertainty) pair. Must be provided if fit_method is ‘coupled’ or ‘single’. Default is None.
host_logg (tuple or None, optionalor None, optional) – The log_10 of the surface gravity of the host star, with gravity measured in cm/s2. Should be given as a (value, uncertainty) pair. Must be provided if fit_method is ‘coupled’ or ‘single’. Default is None.
host_z (tuple or None, optional) – The metalicity of the host, given as a (value, uncertainty) pair. Must be provided if fit_method is ‘coupled’ or ‘single’. Default is None.
filters (array_like or None, optional) – The set of filters, given in [low, high] limits for the wavelengths with the wavelengths given in nanometers. The ordering of the filters should correspond to the filter_idx parameter used elsewhere. Must be provided if fit_method is ‘coupled’ or ‘single’. Default is None.
n_samples (int, optional) – The number of limb darkening profiles to create. Passed to ldtk.LDPSetCreator.create_profiles(). Default is 20000.
do_mc (bool, optional) – If True, will use MCMC to estimate coefficient uncertainties more accurately. Default is False.
cache_path (str, optional) – This is the path to cache LDTK files to. If not specified, will default to the LDTK default
ldtk_uncertainty_multiplier (float, optional) – (From LDTK:) The uncertainty multiplier ϵ is a subjective factor that defines how strongly the LD profile (or the prior created from it) constrains the final analysis (that is, how much we trust the stellar atmosphere models used to create the profiles.)

fit_normalisation(lightcurves, normalise_limits)¶

When run, the Retriever will fit normalisation of the data as a free parameter.

Parameters:

lightcurves (np.array of `LightCurve`s, shape (n_telescopes, n_filters, n_epochs)) –

The array of LightCurves to be normalised. We can use the value of fluxes to estimate a normalisation constant (c_n) range for each light curve. We use

1/f_median -1 <= c_n <= 1/f_median + 1

as the default range, where f_median is the median flux value.

get_latex_friendly_labels()¶: Adds a $ around the underscored text to make the latex displays work

set_error_scaling(lightcurves, scaling_limits, method_index_array)¶

transitfit.priorinfo.setup_priors(P, t0, a, rp, inc, ecc, w, limb_dark, n_telescopes, n_filters, n_epochs, q0=None, q1=None, q2=None, q3=None, allow_ttv=False, lightcurves=None, error_scaling=False)¶

Factory function to initialise a PriorInfo object

qX should either be a single value or a list of values length n_filters

Limb darkening handling¶

Class to handle limb darkening

class transitfit._limb_darkening_handler.LimbDarkeningHandler(default_model, low_lim=-5, high_lim=5)¶

Bases: object

The LimbDarkeningHandler is designed to convert fitting parameters in the range [0,1] and convert them into physically allowed values for limb darkening coefficients for different models. This conversion is based on Kipping 2013 https://arxiv.org/abs/1308.0009.

Parameters:

default_model (str) –
The default limb darkening model to use. Accepted values are
- ’linear’
- ’quadratic’
- ’squareroot’
- ’power2’
- ’nonlinear’
This model will be the default for conversions unless otheriwse specified.
low_lim (float, optional) – The lower limit to use in conversion in the case where there are open bounds on a coefficient (power2 and nonlinear models). Note that in order to conserve sampling density in all regions for the power2 model, you should set lower_lim=-high_lim. Default is -5
high_lim (float, optional) – The upper limit to use in conversion in the case where there are open bounds on a coefficient (power2 and nonlinear models). Note that in order to conserve sampling density in all regions for the power2 model, you should set lower_lim=-high_lim. Default is 5

convert_qtou(*q, model=None)¶

Takes parameters q distributed between [0,1] and converts them into physical values for limb darkening coefficients.

Conversions for quadratic, square root, and logarithmic are from Kipping 2013 https://arxiv.org/abs/1308.0009 for two-parameter limb darkening methods

Notes

This is the inverse of convert_utoq

convert_qtou_with_errors(q, q_err, model=None)¶: Converts kipping parameters with errors into physical LDCs with errors

convert_utoq(*u, model=None)¶

Takes actual values of the LD coefficients and converts them to a value q between [0,1].

Conversions for quadratic, square root, and logarithmic are from Kipping 2013 https://arxiv.org/abs/1308.0009 for two-parameter limb darkening methods

Notes

This is the inverse of convert_qtou

get_required_coefficients(model=None)¶

Finds the number of coefficients required for a given model and returns a string name for each of the form ‘uX’ where X is a number.

Parameters:: model (str or None, optional) – Model to get the coefficients for. Default is self.default_model
Returns:: coeficient names – The coefficient names
Return type:: list of str

initialise_ldtk(host_T, host_logg, host_z, filters, model=None, n_samples=20000, do_mc=False, cache_path=None, ldtk_uncertainty_multiplier=1.0)¶

Sets up an LDTKHandler to deal with interfacing between ldtk and TransitFit

Parameters:

host_T (tuple) – The effective temperature of the host star, in Kelvin, given as a (value, uncertainty) pair.
host_logg (tuple) – The log_10 of the surface gravity of the host star, with gravity measured in cm/s2. Should be given as a (value, uncertainty) pair.
host_z (tuple) – The metalicity of the host, given as a (value, uncertainty) pair.
filters (array_like) – The set of filters, given in [low, high] limits for the wavelengths with the wavelengths given in nanometers. The ordering of the filters should correspond to the filter_idx parameter used elsewhere.
ld_method (str or None, optional) – The model of limb darkening to use. Allowed values are ‘linear’, ‘quadratic’, ‘squareroot’, ‘power2’, and ‘nonlinear’. If None, will default to self.default_model. Default is None.
n_samples (int, optional) – The number of limb darkening profiles to create. Passed to ldtk.LDPSetCreator.create_profiles(). Default is 20000.
do_mc (bool, optional) – If True, will use MCMC to estimate coefficient uncertainties more accurately. Default is False.
cache_path (str, optional) – This is the path to cache LDTK files to. If not specified, will default to the LDTK default
ldtk_uncertainty_multiplier (float, optional) – (From LDTK:) The uncertainty multiplier ϵ is a subjective factor that defines how strongly the LD profile (or the prior created from it) constrains the final analysis (that is, how much we trust the stellar atmosphere models used to create the profiles.)

ldtk_estimate(ld0_values, model=None)¶

Uses LDTK to estimate the LDCs for all filters when given a set of LDCs for filter 0, based on the ratios between the best values found in initialisation.

Parameters:

ld1_values (float or array_like) – The LD parameters for filter 0
ld_model (str, optional) – The limb darkening model to use. Defaults to self.default_model

Returns:

all_ld_values – The estimated limb darkening parameters

Return type:

array_like, shape (n_filters, n_coeffs)

ldtk_lnlike(coeffs, model=None)¶

Uses LDTK to evaluate the log likelihood for a set of coefficients. Note that coeffs should be the values returned by convert_qtoA and NOT the unit values.

Parameters:

coeffs (array_like, shape (n_filters, n_coeffs)) – The coefficients to evaluate the log likelihood for.
ld_model (str, optional) – The model to use. Defaults to self.default_model

Returns:

lnlike – The log likelihood of the coefficients

Return type:

float

LDTK interfacing¶

Class to handle limb darkening parameters through PyLDTK

class transitfit._ldtk_handler.LDTKHandler(host_T, host_logg, host_z, filters, ld_model='quadratic', n_samples=20000, do_mc=False, cache_path=None, ldtk_uncertainty_multiplier=1.0)¶

Bases: object

The LDTKHandler provides an easy way to interface ldtk with TransitFit.

Parameters:

host_T (tuple) – The effective temperature of the host star, in Kelvin, given as a (value, uncertainty) pair.
host_logg (tuple) – The log_10 of the surface gravity of the host star, with gravity measured in cm/s2. Should be given as a (value, uncertainty) pair.
host_z (tuple) – The metalicity of the host, given as a (value, uncertainty) pair.
filters (array_like) – The set of filters, given in [low, high] limits for the wavelengths with the wavelengths given in nanometers if a uniform filter is to be used, or [[wavelength…], [transmission]] if a fully-defined profile is being used. The ordering of the filters should correspond to the filter_idx parameter used elsewhere.
ld_method (str, optional) – The model of limb darkening to use. Allowed values are ‘linear’, ‘quadratic’, ‘squareroot’, ‘power2’, and ‘nonlinear’. Default is ‘quadratic’.
n_samples (int, optional) – The number of limb darkening profiles to create. Passed to ldtk.LDPSetCreator.create_profiles(). Default is 20000.
do_mc (bool, optional) – If True, will use MCMC to estimate coefficient uncertainties more accurately. Default is False.
cache_path (str, optional) – This is the path to cache LDTK files to. If not specified, will default to the LDTK default
ldtk_uncertainty_multiplier (float, optional) – (From LDTK:) The uncertainty multiplier ϵ is a subjective factor that defines how strongly the LD profile (or the prior created from it) constrains the final analysis (that is, how much we trust the stellar atmosphere models used to create the profiles.)

_extract_best_coeffs(ld_model, do_mc=False)¶

Extracts the best values for a limb darkening model for the filters

Parameters:

ld_model (str) – The limb darkening model to obtain the values for.

Returns:

coeffs (array_like, shape (n_filters, n_coeffs)) – The coefficients for each filter
err (array_like, shape (n_filters, n_coeffs)) – The uncertainty on each of the coefficients

estimate_values(ld0_values, ld_model)¶

If given a set of LD param values for filter 0, will estimate the LD parameters for all filters based on the ratios between the best values found in initialisation.

Parameters:

ld1_values (float or array_like) – The LD parameters for filter 0
ld_model (str) – The limb darkening model to use

Returns:

all_ld_values – The estimated limb darkening parameters

Return type:

array_like, shape (n_filters, n_coeffs)

lnlike(coeffs, ld_model)¶

Evaluates the log likelihood for a set of coefficients

Parameters:

coeffs (array_like, shape (n_filters, n_coeffs)) – The coefficients to evaluate the log likelihood for.
ld_model (str, optional) – The model to use. Defaults to self.default_model

Likelihood calculations¶

Module to calculate the likelihood of a set of parameters

class transitfit._likelihood.LikelihoodCalculator(lightcurves, priors)¶

Bases: object

Object to quickly calculate the likelihood of a set of parameters to fit a given set of light curves.

Parameters:

lightcurves (array_like, shape (n_telescopes, n_filters, n_epochs)) – An array of LightCurves. If no data exists for a point in the array then the entry should be None.
priors (PriorInfo) – The PriorInfo object for retrieval

find_likelihood(params)¶: Finds the likelihood of a set of parameters

find_likelihood_parallel_processed(cube)¶

update_params(telescope_idx, filter_idx, epoch_index, t0=None, P=None, rp=None, a=None, inc=None, ecc=None, w=None, limb_dark=None, u=None)¶: Updates self.params with values given

Detrending¶

detrender.py

A module to deal with arbitrary detrending

class transitfit.detrender.DetrendingFunction(function, method=None)¶

Bases: object

The DetrendingFunction is designed to handle detrending with an arbitrary function.

Basically gets around dealing with varying number of args in a neat way

Parameters:: function (function) – The detrending function. Must have signature of f(times, a, b, c,…,t0,P) where a, b, c etc are the detrending coefficients, t0 is the time of conjunction and P is period.

Some detrending functions for use with LightCurve

class transitfit.detrending_funcs.NthOrderDetrendingFunction(order)¶

Bases: object

Arbitrary order detrending function which conserves flux.

Parameters:: order (int) – The detrending function order. Must be greater than 0.

Input and output¶

Object to deal with writing fitting results to files

class transitfit.output_handler.OutputHandler(lightcurves, full_prior, host_r=None)¶

Bases: object

Designed to handle writing outputs from retrieval to files

Parameters:

lightcurves (array_like, shape (n_telescopes, n_filters, n_epochs)) – The full lightcurves array to be retrieved.
full_prior (PriorInfo) – The prior for the complete light curve dataset.

_batch_to_full_idx(i, param_name, lightcurves, allow_ttv)¶

Converts a batch index into a full index

Parameter¶

ituple: (batch_tidx, batch_fidx, batch_eidx)

rtype:: (tidx, fidx, eidx)

_initialise_batman(all_lightcurves)¶

Sets up batman so we can generate best-fit models for outputs

Parameters:: all_lightcurves (array_like) – Array containing the global set of light curves

_initialise_best_model(mode, global_prior, output_folder, summary_file)¶

Sets up the best fit model used to output best fit

Parameters:

mode (str) – The fitting mode being used
global_prior (PriorInfo) – The full_prior from the retriever. Used to determine array shapes.

Returns:

best_model – A dictionary containing param arrays of the best values

Return type:

dict

Notes

To do this, we go through all output parameter files and pull in the values. In folded mode, we pull in from the global summary first and add from the filter summaries after

_initialise_dict_entry(d, param, prior=None)¶

Initialises param in results dictionaries using ParamArray

If prior is not provided, defaults to self.full_prior

_plot_data(phase, flux, flux_err, model_phase, model_curve, residuals, fname, title=None, folder='./plots', figsize=(12, 8), marker_color='dimgrey', line_color='black', phase_lims=None, bin_data=False, cadence=2, binned_colour='red')¶

Plots the lightcurve and model consistently

Parameters:: cadence (float) – The cadence to bin to in phase, not minutes

_plot_samples(result, prior, fname, folder='./plots')¶: Makes a corner plot of the samples from a result

_print_results(result)¶: Prints a results dict to terminal

_quicksave_result(results, priors, lightcurves, base_output_path='./outputs', filter=None, batch=None)¶: Quickly saves a batch result to file and pickle the Result and Prior objects

_results_dict_to_dataframe(results_dict, batched)¶: Converts a results dict to a pandas dataframe

_save_results_dict(results_dict, path, batched)¶: Saves a dict to csv

add_best_u(best_dict, combined_dict)¶

Given results dicts, adds in the u vals

Parameters:

best_dict (dict) – The dictionary of best results
combined_dict (dict) – The full results

Returns:

best_dict (dict) – The same dictionary with the best u vals added.
combined_dict (dict) – The same dictionary with the u vals added.

combine_results_dicts(results_dicts)¶

Combines the given results dicts into one dict

Parameters:: results_dicts (array_like, shape (n_batches, )) – The results_dicts obtained from get_results_dict
Returns:: combined_dict – The combined results dictionary. Each entry is a list of values from the results dictionaries - [[best value, median, 16th percentile, 84th percentile, stdev],…]
Return type:: dict

get_best_vals(results_dicts, priors, fit_ld=True, return_combined=True)¶

Gets the best values for a set of runs from the given results dicts

Parameters:

results_dicts (array_like, shape (n_batches, )) – The results_dicts obtained from get_results_dict
fit_ld (bool, optional) – Should be True if LDC fitting. Default is True
return_combined (bool, optional) – If True, will return the results dicts combined into a single dict. Default is True.

Returns:

best_vals (dict) – Each entry is [best val, error]
combined_dict (dict) – The combined results dictionary. Returned if return_combined is True

get_results_dict(results, priors, lightcurves)¶

Makes dictionaries of results from a single dynesty run.

Useful for putting results in a form which allows for easy summary etc.

Parameters:

results (dict) – Results from a single dynesty run
priors (PriorInfo) – The priors for the run
lightcurves (array_like, shape (n_telescopes, n_filters, n_epochs)) – The lightcurves for the run

Returns:

results_dict – Each entry is [best value, median, 16th percentile, 84th percentile, stdev]

Return type:

dict

plot_final_light_curves(all_lightcurves, global_prior, folder='./plots', figsize=(12, 8), marker_color='dimgrey', line_color='black', plot_folded=True, titles=False, bin_data=True, cadence=2, binned_color='red')¶

Plots the detrended light curves with the global best-fit model

Parameters:: cadence (float, optional) – The cadence to bin to in minutes

save_complete_results(mode, global_prior, output_folder, summary_file)¶: Once all batches etc are run, collates all results and saves to csv

save_final_light_curves(all_lightcurves, global_prior, folder='./final_light_curves', folded=False)¶

Saves the final curves and best fit model to file

Requires best model to be initialised

Parameters:: all_lightcurves (array_like) – Array containing the global set of light curves - these should be raw and not normalised or detrended.

save_results(results, priors, lightcurves, output_folder='./output_parameters', summary_file='summary_output.csv', full_output_file='full_output.csv', samples_plot_folder='./plots', folded=False, plot_posteriors=True, batch_idx=None, stage=1)¶

Saves results to .csv files

Parameters:

results (array_like, shape (n_batches, )) – The results from each run
priors (array_like, shape (n_batches, )) – The priors for each run
lightcurves (array_like, shape (n_batches, )) – The light curves for each run
fit_ld (bool, optional) – Must be true if LDCs are fitted. Default is True
output_folder (str, optional) – The folder to save output files to (not plots). Default is ‘./output_parameters’
summary_file (str, optional) – The file name for the final output. This file only gives the averaged values, rather than individual values fitted within batches if there are any. Default is ‘summary_output.csv’
full_output_file (str, optional) – The file name for the full output file. This file gives partial results from batches, rather than the averaged results. Default is ‘full_output.csv’

Returns:

best_vals (dict) – Each entry is [best val, error]
combined_dict (dict) – The combined results dictionary. Each entry is a list of values from the results dictionaries - [[best value, median, 16th percentile, 84th percentile, stdev],…]

class transitfit.output_handler.Results(sampler)¶

Bases: object

Dynesty>v 1.1 doesn’t allow setting attributes directly. This new class help in creating a new instance with attributes for easier handling.

class transitfit.output_handler.ResultsException(sampler)¶

Bases: object

Handles results (same as above) during exception raised by dynesty.

Module to deal with all the reading in of inputs, as well as printing final results to terminal

transitfit.io._read_data_csv(path, usecols=None)¶: Given a path to a csv with columns [time, flux, errors], will get all the data in a way which can be used by the Retriever

transitfit.io._read_data_txt(path, skiprows=0, usecols=None, delimiter=' ')¶: Reads a txt data file with columns

transitfit.io.get_filter_path(input_str, unit)¶

Checks if a path or name of a default provided filter is given.

Parameters:: input (str) – The input string from the filter file input
Returns:: path – The path to the relevant filter
Return type:: str

transitfit.io.parse_data_path_list(data_path_list)¶

Parses a list of paths to data files and places them into an array which can be passed to read_data_file_array

Parameters:

data_path_list (array_like, shape (n_light_curves, 5)) – The list of paths. Each row should contain [data path, telescope idx, filter idx, epoch idx, detrending idx]

Returns:

data_path_array (array_like, shape (num_filters, num_epochs, num_telescopes)) – The paths inserted into an array which can be used by TransitFit
detrending_index_array (array_like, shape (num_filters, num_epochs, num_telescopes)) – The array of detrending model indices for each light curve

transitfit.io.parse_filter_list(filter_list, delimiter=None, unit='nanometers')¶

Parses a list of filter information into a usable form for the ‘filters’ argument in PriorInfo.fit_limb_darkening.

Parameters:

filter_list (array_like, shape (n_filters, 3)) – The information on the filters. Each row should contain [filter_index, low wavelength/file path, high wavelength] The filter indices should refer to the indices used in the priors file. Wavelengths should be in nm.
delimiter (str, optional) – The delimiter used in filter profile files. Default is None, which automatically detects using csv.Sniffer

Returns:

filter_info – The filter information pass to PriorInfo.fit_limb_darkening.

Return type:

np.array, shape (n_filters, 2)

transitfit.io.parse_priors_list(priors_list, n_telescopes, n_filters, n_epochs, ld_model, filter_indices=None, folded=False, folded_P=None, folded_t0=None, host_radius=None, allow_ttv=False, lightcurves=None, suppress_warnings=False, error_scaling=False)¶

Parses a list of priors to produce a PriorInfo with all fitting parameters initialised.

Parameters:

priors_list (array_like, shape(X, 5)) – A list of prior information for each variable to be fitted. Can also set fixed values by setting the low and high values to None or np.nan. Each row should be of the form [key, mode, input A, input B, filter index]
n_telescopes (int) – The number of different telescopes being used. Required so that simultaneous observations from different observatories can be used by TransitFit
n_filters (int) – The number of different filters being used
n_epochs (int) – The number of different epochs being used
ld_model (str) – The limb darkening model to use
filter_indices (array_like, optional) – If provided, will only initialise fitting for parameters which are relevant to the filter indices given. Note that this will result in a difference between the filter indices used at the top, user level and those used within this PriorInfo
folded (bool, optional) – If True, will not initialise P or t0 from the priors list. Instead will use folded_P and folded_t0 to set fixed values. Default is False
folded_P (float, optional) – Required if folded is True. This is the period that the light curves are folded to
folded_t0 (float, optional) – Required if folded is True. This is the t0 that the light curves are folded to
host_radius (float, optional) – The host radius in Solar radii. If this is provided, then will assume that the orbital separation is given in AU rather than host radii and will convert the values accordingly

Returns:

priors – The fully initialised PriorInfo which can then be used in fitting.

Return type:

PriorInfo

transitfit.io.print_results(results, priorinfo, n_dof)¶

Prints the results nicely to terminal

Parameters:

results (dynesty.results.Results) – The Dynesty results object, but must also have weights, cov and uncertainties as entries.
priorinfo (transitfit.priorinfo.PriorInfo) – The PriorInfo object

transitfit.io.read_data_file(path, skiprows=0, folder=None, usecols=None, delimiter=None)¶

Reads a file in, assuming that it is either a:: .csv .txt

with columns in the order time, depth, errors. Note that TransitFit assumes BJD times.

Parameters:

path (str) – Full path to the file to be loaded
skiprows (int, optional) – Number of rows to skip in reading txt file (to avoid headers)
folder (str or None, optional) – If not None, this folder will be prepended to all the paths. Default is None.
usecols (int or sequence, optional) – Which columns to read, with 0 being the first. For example, usecols = (1,4,5) will extract the 2nd, 5th and 6th columns. These should be given in the order time, flux, uncertainty The default, None, results in all columns being read.

Returns:

times (np.array) – The times of the data series
flux (np.array) – The flux
error (np.array) – The uncertainty on the flux

transitfit.io.read_data_path_array(data_path_array, skiprows=0)¶

If passed an array of paths, will read in to produce an array of `LightCurve`s

Parameters:: data_path_array (array_like, shape (n_telescopes, n_filters, n_epochs)) – Array with paths to data to load
Returns:: lightcurves – The data loaded and stored as an array of LightCurves
Return type:: np.array of `LightCurve`s, shape (n_telescopes, n_filters, n_epochs)

transitfit.io.read_filter_info(path, delimiter=None, unit='nanometers')¶

Reads in information on the filters from .csv file and puts them in a format which can be passed to the filters argument in PriorInfo.fit_limb_darkening.

Parameters:

path (str) –
Path to the .csv file containing the information on the filters. This file should have three columns:

filter_idx | low_wl_or_path | high_wl |

Filters can either be specified as uniform between low_wl and high_wl, or a full profile can be passed through a file. Filter profile files must be two columns, giving wavelength and transmission fraction in range [0,1]. The filter indices should refer to the indices used in the priors file. All wavelengths should be in nm.
delimiter (str, optional) – The delimiter used in filter profile files. Default is None, which automatically detects using csv.Sniffer

Returns:

filter_info – The filter information pass to PriorInfo.fit_limb_darkening.

Return type:

np.array, shape (n_filters, 2)

transitfit.io.read_input_file(path, skiprows=0)¶

Reads in a file with listed inputs and produces data arrays for use in retrieval.

Parameters:

path (str) –

The path to the .csv file with the paths to input parameters and their telescope, filter, epoch, and detrending indices.

Returns:

lightcurves (np.array of `LightCurve`s, shape (n_telescopes, n_filters, n_epochs)) – The data loaded and stored as an array of LightCurves
detrending_index_array (array_like, shape (n_telescopes, n_filters, n_epochs)) – The detrending indices for each lightcurve

transitfit.io.read_priors_file(path, n_telescopes, n_filters, n_epochs, limb_dark='quadratic', filter_indices=None, folded=False, folded_P=None, folded_t0=None, host_radius=None, allow_ttv=None, lightcurves=None, suppress_warnings=False, error_scaling=False)¶

If given a csv file containing priors, will produce a PriorInfo object based off the given values

Parameters:

path (str) –
Path to .csv file containing the priors.

key | mode | input_A | input_B | filter |

The available modes and the expected values of inputs A and B are:
- ’uniform’: input A should be lower limit, input B should be upper
  limit
- ’gaussian’: input_A should be mean, input_B should be standard
  deviation.
- ’fixed’: input_A should be the fixed value. input_B is not used and
  should be left blank.
n_telescopes (int) – The number of different telescopes being used. Required so that simultaneous observations from different observatories can be used by TransitFit
n_filters (int) – The number of different filters being used
n_epochs (int) – The number of different epochs being used
limb_dark (str, optional) –
The model of limb darkening you want to use. Accepted are
- linear
- quadratic
- squareroot
- power2
- nonlinear
Default is quadratic
filter_indices (array_like, optional) – If provided, will only initialise fitting for parameters which are relevant to the filter indices given. Note that this will result in a difference between the filter indices used at the top, user level and those used within this PriorInfo
folded (bool, optional) – If True, will not initialise P or t0 from the priors list. Instead will use folded_P and folded_t0 to set fixed values. Default is False
folded_P (float, optional) – Required if folded is True. This is the period that the light curves are folded to
folded_t0 (float, optional) – Required if folded is True. This is the t0 that the light curves are folded to
host_radius (float, optional) – The host radius in Solar radii. If this is provided, then will assume that the orbital separation is given in AU rather than host radii and will convert the values accordingly.

Notes

Detrending currently cannot be initialised in the prior file. It will be available as a kwarg in the pipeline function

transitfit.io.save_final_light_curves(lightcurves, priorinfo, results, folder='./final_light_curves', folded=False)¶

Applies detrending and normalisation to each light curve and saves to .csv

Parameters:

lightcurves (array_like, shape (n_telescopes, n_filters, n_epochs)) – An array of LightCurves. If no data exists for a point in the array then the entry should be None.
priorinfo (transitfit.priorinfo.PriorInfo) – The PriorInfo object
results (dynesty.results.Results) – The Dynesty results object, but must also have weights, cov and uncertainties as entries.
folder (str, optional) – The folder to save the files to. Default is ‘./final_light_curves’
folded (bool, optional) – If True, will assume that the lightcurves provided are folded and will change the filenames accordingly. Default is False

This python file takes output_parameters folder as input and provides asymmetric errors using the distribution of samples.

class transitfit.error_analysis.ErrorLimits(output_parmeters)¶

Bases: object

Initializes the error limit analysis.

Parameters:: output_parmeters (str) – path of the output_parameters folder generated by TransitFit

get_errors()¶: Gets the upper and lower error bound on values.

handle_ttv()¶: Handles the case of TTV analysis.

transitfit.error_analysis.get_quantiles_on_best_val(samples, weights, best_val)¶

Generates lower and upper limit of errors for the best values. Sorts the samples and corresponding weights. Gets value of samples such that they encompass 68.27% of the samples by weight on both sides of the best value.

Parameters:

samples (array) – the sampled values for the parameter from dynesty
weights (array) – weights of the samples
best_val (float) – best value among the samples

Returns:

the lower and upper error on the best value.

Return type:

tuple

transitfit.error_analysis.make_dict(val_dict, key, vals)¶

makes dictionary using the given values. if the key already exists, then the values get appended.

Parameters:

val_dict (dict) – the dictionary where the values are to be added
key (str) – the key of the value
vals (array) – the values to be added

transitfit.error_analysis.q_to_u(q, q_err_l, q_err_u)¶

Converts q (Kipping parameters) to limb darkening parameters u. Handles only quadratic limb darkening currently.

Parameters:

q (list) – values of q0, q1
q_err_l (list) – lower bound of errors on q0, q1
q_err_u (list) – upper bound of errors on q0, q1

Returns:

the values of u, lower bound on values, upper bound on values.

Return type:

tuple

transitfit.error_analysis.q_to_u_err(q, q_err)¶

Converts error in q to errors in u parameters for quadratic limb-darkening

Parameters:

q (list) – values of q0, q1
q_err (list) – errors on q0, q1

Returns:

errors on u0, u1

Return type:

list

Parameter handling¶

LightCurve objects for TransitFit

class transitfit.lightcurve.LightCurve(times, flux, errors, telescope_idx=None, filter_idx=None, epoch_idx=None, curve_labels=None, telescope_array=None, filter_array=None, epoch_array=None)¶

Bases: object

The transit data which we are trying to fit.

The LightCurve is designed to simplify dealing with detrending etc across multiple data sets. It allows us to clearly keep values pointed at specific data sets.

Parameters:

times (array_like, shape (X, )) – The times of observation
flux (array_like, shape (X, )) – The fluxes
errors (array_like, shape (X, )) – The absolute uncertainty on the fluxes
telescope_idx (int, optional) – The telescope index associated with this light curve
filter_idx (int, optional) – The filter index associated with this light curve
epoch_idx (int, optional) – The epoch index associated with this light curve
curve_labels (array_like, shape (X, ), optional) – Used to identify if different data points come from different observations. Useful when combining curves if you want to undo that!
telescope_array (array_like, shape (X, ), optional) – Array of the telescope indices for each data point. Useful when dealing with combined curves.
filter_array (array_like, shape (X, ), optional) – Array of the filter indices for each data point. Useful when dealing with combined curves.
epoch_array (array_like, shape (X, ), optional) – Array of the epoch indices for each data point. Useful when dealing with combined curves.

bin(cadence, residuals=None)¶

Bins the light curve to a given observation cadence

Parameters:

cadence (float) – The observation cadence to bin to in the units of self.times
residuals (array_like, shape (n_times,)) – If provided, will also bin any model residuals

Returns:

time (array_like) – The time centers of each bin
flux (array_like) – The flux in each bin, calculated as the weighted mean of all flux values in the bin
err (array_like) – The error on the flux of each bin

combine(lightcurves, telescope_idx=None, filter_idx=None, epoch_idx=None)¶: Combines the LightCurve with a list of other lightcurves which are passed to it and returns a new lightcurve containing all the data of the input curves. Note that you should probably only do this with lightcurves which have already been detrended, otherwise you might struggle to detrend the combined one.

create_detrended_LightCurve(d_new, norm, escale=None)¶: Creates a detrended LightCurve using detrend_flux() and returns it

decombine()¶

Splits a lightcurve according to its curve labels.

Inverse of combine

detrend_flux(d_new, norm=1, force_normalise=False)¶

When given a normalisation constant and some detrending parameters, will return the detrended flux and errors

Parameters:

d (array_like, shape(n_detrending_params,)) – Array of the detrending parameters to use
norm (float, optional) – The normalisation constant to use. Default is 1
force_normalise (bool, optional) – Override to allow normalisation to be forced if the LightCurve does not have normalisation initialised. Default is False.

Returns:

detrend_flux (array_like, shape(num_times)) – The detrended flux
detrended_errors (array_like, shape(num_times)) – The errors on the detrended flux

estimate_normalisation_limits()¶

Estimates the range for fitting a normalisation constant, and also finds a reasonable first guess.

Returns:

median_factor (float) – The initial best guess factor
low_factor (float) – The low limit on the normalisation factor
high_factor (float) – The high limit on the normalisation factor

Notes

We use: 0.5/f_max <= c_n <= 1.5/f_min

as the default range.

fold(t0, period, base_t0=None)¶

Folds the LightCurve so that all times are between t0 - period/2 and t0 + period/2.

If base_t0 is provided, this will ensure that the folded lightcurve is centred on base_t0. This is to allow for ttv mode where the differences between the retrieved t0 for each epoch must be accounted for.

returns a new LightCurve

get_phases(t0, P)¶: Converts times into phase given t0 and P values, with t0 at phase=0

save(filepath)¶: Saves the LightCurve to a .csv file

set_detrending(method, order=None, function=None, method_idx=None)¶

Sets detrending method

Parameters:

method (str) –
Accepted
- ’nth order’
- ’custom’
order (int, optional) – The order of detrending to use if method is ‘nth order’. Must be provided.
function (function, optional) – If method is ‘custom’, this is the custom detrending function to use.

set_error_scaling(scaling_limits)¶

Turns on normalisation. Also estimates limits and a best initial guess.

Parameters:

default_low (float, optional) – The lowest value to consider as a multiplicative normalisation constant. Default is 0.1.

Returns:

median_factor (float) – The initial best guess factor
low_factor (float) – The low limit on the normalisation factor
high_factor (float) – The high limit on the normalisation factor

Notes

We use: 0.5/f_max <= c_n <= 1.5/f_min

as the default range, where f_median is the median flux value.

set_normalisation(normalise_limits)¶

Turns on normalisation. Also estimates limits and a best initial guess.

Parameters:

default_low (float, optional) – The lowest value to consider as a multiplicative normalisation constant. Default is 0.1.

Returns:

median_factor (float) – The initial best guess factor
low_factor (float) – The low limit on the normalisation factor
high_factor (float) – The high limit on the normalisation factor

Notes

We use: 0.5/f_max <= c_n <= 1.5/f_min

as the default range, where f_median is the median flux value.

split(t0, P, t14, cutoff=0.25, window=None)¶

Splits the LightCurve into multiple LightCurves containing a single transit. This is useful for dealing with multi-epoch observations which contain TTVs, or have long term periodic trends, since single-epoch observation trends can be approximated with polynomial fits.

Parameters:

t0 (float) – The centre of a transit
P (float) – The estimated period of the planet in days
t14 (float, optional) – The approximate transit duration in minutes.
cutoff (float, optional) – If there are no data within t14 * cutoff of t0, a period will be discarded. Default is 0.25
window (float, optional) – If provided, data outside of the range [t0 ± (0.5 * t14) * window] will be discarded.

Returns:

lightcurves – A list of LightCurve objects

Return type:

list

Notes

Will reset the telescope, filter and epoch indices to None.

A class for parameters in TransitFit which can be retrieved. These are used by the PriorInfo to determine dimensionality etc.

class transitfit._params._GaussianParam(best, sigma, negative_allowed=True, clipped_gaussian=False)¶

Bases: _Param

from_unit_interval(u)¶: Function to convert value u in range (0,1], will convert to a value to be used by Batman

uniform_to_clipped_gaussian(u)¶: Function to convert value u in range (0,1], will convert to a value to be used by Batman

class transitfit._params._Param(value, uncertainty=None)¶

Bases: object

from_unit_interval(u)¶

class transitfit._params._UniformParam(low_lim, high_lim, negative_allowed=True)¶

Bases: _Param

from_unit_interval(u)¶: Function to convert value u in range (0,1], will convert to a value to be used by Batman

class transitfit._paramarray.ParamArray(name, shape, telescope_dependent, filter_dependent, epoch_dependent, default_value=None, lightcurves=None)¶

Bases: object

The _ParamArray is designed to handle parameters which are being fitted by TransitFit. It can deal with parameters which are being fitted over different combinations of telescope, filter, and epoch

If a parameter is lightcurve specific, providing lightcurves will ensure that only parameters where a lightcurve exists will be initialised

Parameters:

name (str) – The parameter name
shape (tuple) – The shape of the array to use
telescope_dependent (bool) – Set to True if the parameter varies across telescopes
filter_dependent (bool) – Set to True if the parameter varies across filters
epoch_dependent (bool) – Set to True if the parameter varies across epoch
default_value (float) – The default value for the parameter
lightcurves (array-like, shape(shape), optional) – The array of relevant light curves.

_generate_idx(telescope_idx, filter_idx, epoch_idx)¶: Takes the given indices and converts them into a usable index, omitting any that are given for variables that the ParamArray does not depend on and raises ValueErrors if None is provided when required.

add_gaussian_fit_param(mean, stdev, telescope_idx=None, filter_idx=None, epoch_idx=None, negative_allowed=True, clipped_gaussian=False)¶: Adds a gaussian sampled fitting parameter

add_uniform_fit_param(low_lim, high_lim, telescope_idx=None, filter_idx=None, epoch_idx=None, negative_allowed=True)¶: Adds a parameter to be fitted with uniform sampling

clipped_gaussian_transform(u, telescope_idx=None, filter_idx=None, epoch_idx=None)¶: Converts a value u in the range [0,1] to a physical value. Used in the dynesty routine

from_unit_interval(u, telescope_idx=None, filter_idx=None, epoch_idx=None)¶: Converts a value u in the range [0,1] to a physical value. Used in the dynesty routine

generate_blank_ParamArray()¶: Produces a ParamArray with the same telescope, filter, and epoch dependencies and shape, but with everything else initialised to None

get_flat_array()¶: Returns the array as a flat list. Useful for getting average values

get_value(telescope_idx=None, filter_idx=None, epoch_idx=None)¶

set_value(value, telescope_idx=None, filter_idx=None, epoch_idx=None)¶

Sets the array entry at the provided value

Value can be any object

General utility functions¶

This is a series of utility functions for TransitFit, including input validation

transitfit._utils.AU_to_host_radii(a, R, a_err=0, R_err=0, calc_err=False)¶: Converts a number in AU to a value in host radii when given the host radius R in Solar radii. Inverse of host_radii_to_AU.

transitfit._utils.calculate_logg(host_mass, host_radius)¶

Calculates log10(g) for a host in units usable by TransitFit. g is in cm s^-2

Parameters:

host_mass (tuple) – The host mass in solar masses and the uncertainty
host_radius (tuple) – The host radius in solar radii and the uncertainty

transitfit._utils.check_batches(allow_ttv, data_files)¶

Taken from firefly/_utils.py, with minor modifications. This was needed to prevent uneven batchsizes. Now it is not required in most of the cases, but has been kept as a failsafe.

Parameters:

allow_ttv (bool) – To allow for TTV or not.
data_files (str) – The path to the data input .csv file, which contains the paths to the
data. (light curve) –

Returns:

The path to modified data input .csv file, which contains the paths to the light curve data. It removed some lightcurves randomly to take care of batching issue in uneven batches.

Return type:

str

transitfit._utils.estimate_t14(Rp, Rs, a, P)¶: Estimates t14 in minutes, if P is in days

transitfit._utils.get_covariance_matrix(results)¶

Gets a covariance matrix from Dynesty results

Parameters:: results (dynesty.results.Results) – The Dynesty results object, but must also have weights as an entry
Returns:: cov – The covariance matrix for the results object.
Return type:: np.array, shape (ndims, ndims)

transitfit._utils.get_normalised_weights(results)¶

Obtains normalised weights for the Dynesty results

Parameters:: results (dynesty.results.Results) – The Dynesty results object
Returns:: weights – The normalised weights for each sample set
Return type:: np.array, shape (n_iterations,)

transitfit._utils.host_radii_to_AU(a, R, a_err=0, R_err=0, calc_err=False)¶: converts a separation in host radii into a separation in AU when given the host radius R in Solar radii. Inverse of AU_to_host_radii.

transitfit._utils.split_lightcurve_file(path, t0, P, t14=20, cutoff=0.25, window=5, new_base_fname='split_curve')¶

Split a light curve file into multiple single epoch files

Splits a multi-epoch lightcurve data file into multiple single-epoch files and saves these. This is useful for dealing with multi-epoch observations which contain TTVs, or have long term periodic trends, since single-epoch observation trends can be approximated with polynomial fits. New files are created of the form new_base_name_X

Parameters:

path (str) – The path to the light curve data to be split
t0 (float) – The centre of a transit
P (float) – The estimated period of the planet in days
t14 (float, optional) – The approximate transit duration in minutes. Default is 20
cutoff (float, optional) – If there are no data within t14 * cutoff of t0, a period will be discarded. Default is 0.25
window (float, optional) – Data outside of the range [t0 ± (0.5 * t14) * window] will be discarded. Default is 5.
new_base_fname (str, optional) – The base name for the new files, which will have numbers appended depending on the epoch. This can be used to specify a relative path for saving. Default is ‘split_curve’.
return_names (bool) –

Returns:

paths – The paths to each of the new data files

Return type:

array_like, shape (n_curves,)

transitfit._utils.validate_variable_key(key)¶: Checks that a key is valid for use with PriorInfo, and corrects when it is obvious what is meant. Raises KeyError if unable to correct.

transitfit._utils.weighted_avg_and_std(values, weights, axis=-1, single_val=False)¶

Calculates the weighted average and error on some data.

axis defaults to the last one (-1)

time_conversions

Module which uses astropy.time to convert between different time standards.

transitfit.time_conversions.MJD_to_BJD(mjd_times, ra, dec, lat, lon, elevation, ra_unit='hourangle')¶

Takes an array of times in MJD and converts to BJD, using observation and telescope data.

Parameters:

mjd_times (array_like, shape (N, )) – The times to be converted from MJD
ra (tuple, length 3) – The right ascension of the observation in either (d, m, s) or (h, m, s) depending on if unit is ‘deg’ or ‘hourangle’
dec (tuple, length 3) – The declination of the observation in (d, m, s)
lat (float or str) – The latitude of the observer in degrees or “dd:mm:ss”
log (float or str) – The longitude of the observer in degrees or “dd:mm:ss”
elevation (float) – The elevation of the observer in meters
unit (str, optional) – The unit being used for ra. Either ‘deg’ for degrees or ‘hourangle’ for hour angle. Default is ‘hourangle’.

Returns:

bjd_times – The times in Barycentric Julian Date

Return type:

array_like, shape (N, )