The settings file

settings.csv

All rows of this file are explained in the following.

Pretty much all of them are optional; if you do not give them, the default settings will apply.

Replace [key] with 'flux' or 'rv'.

Replace [inst] with the name of your instrument, for example 'TESS' or 'HARPS'.

Replace [companion] with the name of the respective companion, for example 'b' or 'c'.

General settings

companions_phot

(space separated string; mandatory)

Example: companions_phot,b c

The companion(s) to the host star covered in the photometric data, space separated if there are multiple. For one planet for example b; for multiple planets for example b c d. For a binary companion for example B. Could also be Hans or anything really, if you feel rebellious.


companions_rv

(space separated string; mandatory)

Example: companions_rv,b c

The companion(s) to the host star covered in the radial velocity data, space separated if there are multiple. For one planet for example b; for multiple planets for example b c d. For a binary companion for example B. Could also be Hans or anything really, if you feel rebellious.


inst_phot

(space separated string; mandatory)

Example: inst_phot,TESS

The name of the photometric instrument(s), space separated if there are multiple. The only condition is that the data file must be named exactly the same, for example TESS.csv.


inst_rv

(space separated string; mandatory)

Example: inst_rv,HARPS ESPRESSO

The name of the radial velocity instrument(s), space separated if there are multiple. The only condition is that the data file must be named exactly the same, for example HARPS.csv and ESPRESSO.csv.


Fit performance settings

multiprocess

(bool; optional; default: False)

Example: multiprocess,True

Do you want to run on multiple cores? Yes, you do.


multiprocess_cores

(integer or 'all'; optional; default: 1)

Example 1: multiprocess_cores,4

Example 2: multiprocess_cores,all

On how many cores do you want to run? On all, of course. Well, actually 'all' means to all your CPUs minus 1 (which will be saved for spare tasks).


fast_fit

(bool; optional; default: False)

Example: fast_fit,True

Do you want to mask out the out-of-transit data, and run a fast fit on the transits alone? Yes, you do.


fast_fit_width

(float; optional; default: 0.33333)

Example: fast_fit_width,0.3

How big of a window around the transit midpoint do you want to keep (in days). For example , the default keeps a 0.33333 day (= 8 hours) window centered on the transit midpoint in your initial guess.

Careful: if your initial epoch and period values are off by too much, this will cut out the wrong parts of the data!


secondary_eclipse

(bool; optional; default: False)

Example: secondary_eclipse,False

When using fast fit, do you also want to keep a window centred around phase 0.5? For example, to keep information of the secondary eclipse in the light curve.


phase_curve

(bool; optional; default: False)

Example: phase_curve,False

This is just for plotting. Do you want to plot zooms onto the phase curve? Can also be done via allesclass plots later.


shift_epoch

(bool; optional; default: False)

Do you want to automatically put the epoch into the middle of the data set? This is to avoid correlations between epoch and period, which would occur if the epoch is set far off one edge of the data set.


inst_for_[companion]_epoch

(space separated string; optional; default: blank)

Which data sets do you want to regard for shifting the epoch? For example, you might have 10 year old, sparse archival radial velocity data, and a brand-new TESS light curve. In this case, it is best to just pass TESS, because this instrument is what really pins down the epoch and period. In other cases you might want to pass all.


MCMC settings

mcmc_nwalkers

(integer; optional; default: 100)

Example: mcmc_nwalkers,200

The number of MCMC walkers. Only used if you actually do MCMC sampling.


mcmc_total_steps

(integer; optional; default: 2000)

Example: mcmc_total_steps,200000

The total steps in the MCMC chain, including burn-in steps. Only used if you actually do MCMC sampling.


mcmc_burn_steps

(integer; optional; default: 1000)

Example: mcmc_burn_steps,10000

The burn-in steps in the MCMC chain; obviously must be smaller than the total steps. Only used if you actually do MCMC sampling.


mcmc_thin_by

(integer; optional; default: 1)

Example: mcmc_thin_by,1

Only save every n-th step in the MCMC chain. Only used if you actually do MCMC sampling.


mcmc_pre_run_steps

(integer; optional; default: 0)

Example: mcmc_pre_run_steps,1000

Run n steps of a pre-burn-in. Then pick the values corresponding to the maximum likelihood as new initial guesses, and start the "real" run from there. This can help if your initial guess is absolutely horrible, for example if you have no clue about some parameters. Only used if you actually do MCMC sampling.


mcmc_pre_run_loops

(integer; optional; default: 0)

Example: mcmc_pre_run_loops,2

Run m loops with n steps of pre-burn-ins. For example, if mcmc_pre_run_loops==2 and mcmc_pre_run_steps,1000 , then this will do the following:

  • run 1000 steps of pre-burn-in from the original initial guesses
  • pick the values corresponding to the maximum likelihood as new initial guesses
  • run a second loop of 1000 steps of pre-brun-in starting form the updated initial guesses,
  • pick the values corresponding to the maximum likelihood as new initial guesses
  • then finally it will start the "real" run from there.

This can help if your initial guess is absolutely horrible, for example if you have no clue about some parameters. Only used if you actually do MCMC sampling.


Nested Sampling settings

ns_modus

(dynamic or static; optional; default: dynamic)

Example: ns_modus,dynamic

Which Nested Sampling algorithm do you want to pick? There shouldn't be any reason to change the default.


ns_nlive

(integer; optional; default: 500)

Example: ns_modus,500

How many live points to set at the beginning of a Nested Sampling run? There shouldn't be any reason to change the default.


ns_bound

(single or multiple; optional; default: single)

Example: ns_bound,single

Use a single ellipse, or multiple ellipses? Usually, exoplanet related problems have a unique global likelihood maximum, so single should do.


ns_sample

(rwalk or unif or slice; optional; default: rwalk)

Example: ns_sample,rwalk

Which sampling method to use to update the live points? There shouldn't be any reason to change the default.


ns_tol

(float; optional; default: 0.01)

Example: ns_tol,0.01

The tolerance of the convergence criterion. There shouldn't be any reason to change the default.


External priors: stellar host density

use_host_density_prior

(bool; optional; default: True)

Example: use_host_density_prior,True

If True and stellar_params.csv is given, an external normal prior on the stellar host density will be calculated from the user input. Then at each step in the MCMC/NS run, the stellar density is derived from the planets orbit (R/a and P), and the fit gets penalized for deviation from the normal prior.


Limb darkening law per object and instrument

host_ld_law_[inst]
[companion]_ld_law_[inst]

(options below; optional; default: None)

Example: host_ld_law_TESS,quad

Example: b_ld_law_TESS,None

  • None: you are fitting a box. This is not what you want for the host star, but it is what you want for planetary companions.
  • lin: one corresponding parameter called ldc_q1_[inst] has to be given in params.csv.
  • quad: two corresponding parameter called ldc_q1_[inst] and ldc_q2_[inst] have to be given in params.csv,
  • sing: three corresponding parameter called ldc_q1_[inst], ldc_q2_[inst] and ldc_q3_[inst] have to be given in params.csv,


Baseline settings per instrument

baseline_[key]_[inst]

(options below; optional; default: None)

Example 1: baseline_flux_TESS,sample_GP_Matern32

Example 2: baseline_rv_HARPS,sample_offset

The baseline / detrending method used per instrument, choose between:

  • None: the baseline is frozen at 1 for flux, and at 0 for RV. This is not what you want.
  • sample_offset: sample for a simple, constant offset. The corresponding parameter (to be given in params.csv) is
    • baseline_offset_[key]_[inst]
  • sample_linear: sample for a linear slope. The two corresponding parameters called
    • baseline_offset_[key]_[inst] and
    • baseline_slope_[key]_[inst].
  • sample_GP_real: sample a GP with a real kernel. The two corresponding parameters are
    • baseline_gp_real_lna_[key]_[inst] and
    • baseline_gp_real_lnc_[key]_[inst].
  • sample_GP_complex: sample a GP with a complex kernel. The four corresponding parameters are
    • baseline_gp_complex_lna_[key]_[inst],
    • baseline_gp_complex_lnb_[key]_[inst],
    • baseline_gp_complex_lnc_[key]_[inst] and
    • baseline_gp_complex_lnd_[key]_[inst].
  • sample_GP_Matern32: sample for the parameters of a Gaussian Process with a Matern 3/2 kernel. The two corresponding parameters are
    • baseline_gp_matern32_lnsigma_[key]_[inst] (the characteristic amplitude of the GP) and
    • baseline_gp_matern32_lnrho_[key]_[inst] (the characteristic length scale of the GP).
  • sample_GP_SHO: sample a GP with a simple harmonic oscillator (SHO) kernel. The two corresponding parameters are
    • baseline_gp_sho_lnS0_[key]_[inst],
    • baseline_gp_sho_lnQ_[key]_[inst] and
    • baseline_gp_sho_lnomega0_[key]_[inst].
  • hybrid_offset: at each step, this offsets your data by the median of the residuals, automatically at every sampling step. Quick & dirty. Can save you some extra parameters in the sampling.
  • hybrid_poly_1: at each step, a least squares minimization will determine the linear polynomial parameters to set the baseline.
  • hybrid_poly_2: at each step, a least squares minimization will determine the quadratic polynomial parameters to set the baseline.
  • hybrid_poly_3: at each step, a least squares minimization will determine the 3rd order polynomial parameters to set the baseline.
  • hybrid_poly_4: at each step, a least squares minimization will determine the 4th order polynomial parameters to set the baseline.
  • hybrid_spline: this is pretty neat, as it tries to describe your residuals with a smooth spline, automatically at every sampling step. Quick & dirty. Can save you some extra parameters in the sampling.


Stellar variability settings per instrument

stellar_var_[key]

(options below; optional; default: None)

Example 1: stellar_var_flux,sample_GP_Matern32

Example 2: stellar_var_rv,sample_offset

The stellar variability method used, which is the same trend for all instruments. Choose between:

  • None: the baseline is frozen at 1 for flux, and at 0 for RV. This is not what you want.
  • sample_offset: sample for a simple, constant offset. The corresponding parameter (to be given in params.csv) is
    • stellar_var_offset_[key]
  • sample_linear: sample for a linear slope. The two corresponding parameters called
    • stellar_var_offset_[key] and
    • stellar_var_slope_[key].
  • sample_GP_real: sample a GP with a real kernel. The two corresponding parameters are
    • stellar_var_gp_real_lna_[key] and
    • stellar_var_gp_real_lnc_[key].
  • sample_GP_complex: sample a GP with a complex kernel. The four corresponding parameters are
    • stellar_var_gp_complex_lna_[key],
    • stellar_var_gp_complex_lnb_[key],
    • stellar_var_gp_complex_lnc_[key] and
    • stellar_var_gp_complex_lnd_[key].
  • sample_GP_Matern32: sample for the parameters of a Gaussian Process with a Matern 3/2 kernel. The two corresponding parameters are
    • stellar_var_gp_matern32_lnsigma_[key] (the characteristic amplitude of the GP) and
    • stellar_var_gp_matern32_lnrho_[key] (the characteristic length scale of the GP).
  • sample_GP_SHO: sample a GP with a simple harmonic oscillator (SHO) kernel. The two corresponding parameters are
    • stellar_var_gp_sho_lnS0_[key],
    • stellar_var_gp_sho_lnQ_[key] and
    • stellar_var_gp_sho_lnomega0_[key].
  • hybrid_offset: at each step, this offsets your data by the median of the residuals, automatically at every sampling step. Quick & dirty. Can save you some extra parameters in the sampling.
  • hybrid_poly_1: at each step, a least squares minimization will determine the linear polynomial parameters to set the baseline.
  • hybrid_poly_2: at each step, a least squares minimization will determine the quadratic polynomial parameters to set the baseline.
  • hybrid_poly_3: at each step, a least squares minimization will determine the 3rd order polynomial parameters to set the baseline.
  • hybrid_poly_4: at each step, a least squares minimization will determine the 4th order polynomial parameters to set the baseline.
  • hybrid_spline: this is pretty neat, as it tries to describe your residuals with a smooth spline, automatically at every sampling step. Quick & dirty. Can save you some extra parameters in the sampling.


Error settings per instrument

error_[key]_[inst]

(options below; optional; default: hybrid)

Example 1: error_flux_TESS,sample

Example 2: error_rv_HARPS,hybrid

The white noise scaling per instrument, choose between:

  • sample: one corresponding parameter called ‘ln_err_key_inst’ (photometry) or ‘ln_jitter_key_inst’ (RV) has to be given in params.csv.
  • hybrid: the code will intrinsically scale the error bars at each step of the sampling to minimize the likelihood. Quick & dirty. Can save you some extra parameters in the sampling.


Exposure times for interpolation

t_exp_[inst]

(float; optional; default: blank)

Example: t_exp_TESS,0.0208333

In unit of days. If you work on long exposure data or binned data (for example TESS 30 minute cadence lightcurves), then you will want to account for that. This will sample a fine cadence lightcurve model and bin it up to match your data binning. If you neglect this, your fit will be massively biased.

For 2 minute TESS data or shorter exposures you can get away without this.


Number of points for exposure interpolation

t_exp_n_int_[inst]

(integer; optional; default: blank)

Example: t_exp_n_int_TESS,10

Again, if you work on long exposure data, sample as fine as possible. This is not really needed for lightcurves with 2 minute cadence. However, use at least a value of 10 for lightcurves with 30 minute cadence. The impact on RV data is not as drastic and generally can be neglected.


Number of spots per object and instrument

host_N_spots_[inst]

(integer; optional; default: blank)

Example: host_N_spots_TESS,2

How many star spots do you want to include in your model? This will unlock the respective rows in the params file.


Number of flares (in total)

N_flares

(integer; optional; default: blank)

Example: N_flares,2

How many stellar flares do you want to include in your model? This will unlock the respective rows in the params file.


TTVs

fit_ttvs

(bool; optional; default: blank)

Example: fit_ttvs,True

Do you want to freely fit for transit timing variations? This will unlock the respective rows in the params file.


Stellar grid per object and instrument

host_grid_[inst]
[companion]_grid_[inst]

(options below; optional; default: default for host, very_sparse for planets)

Example: host_grid_TESS,default

Example: b_grid_TESS,very_sparse

How finely do you want to integrate over the surface of your stellar and planetary models? This has a strong impact on the computational speed, but usually does not impact the results too much. We recommend you do all your test runs with very_sparse, and then run the very final model for the paper plots and tables with default. Choose between:

  • very_sparse: super fast speed and precise enough in most cases.
  • sparse: fast speed and precise enough in almost all cases.
  • default: moderate speed and very precise.
  • fine: slow but even more precise. Almost always way too precise.
  • very_fine: very slow but hyper precise. Almost always way too precise.


Stellar shape per object and instrument

host_shape_[inst]
[companion]_shape_[inst]

(options below; optional; default: sphere)

Example: host_shape_TESS,roche

Example: b_shape_TESS,sphere

Phase curve enthusiasts! This is for you! How deformed are your stars and planets in binary systems or close-in exoplanets with phase curves? What about all that ellipsoidal modulation. Worry not, we have you covered. Choose between:

  • sphere: a spherical cow. If you don't care about phase curves, this is for you.
  • roche: automatically calculates the shape deformation of the body using the Roche equation. The go to choice in almost all cases.
  • roche_v: for synchronous rotation, the volume of the star can be modeled via Kopal "Dynamics of Close Binary Systems" (Springer, 1978).
  • poly1p5: the body is modeled as a polytrope with index n=1.5. The tidal distortion for polytropes is from Chandrasekhar, 1933, MNRAS, 93, 449 and the rotational distortion is from James, 1964, ApJ, 140, 552.
  • poly3p0: the body is modeled as a polytrope with index n=3.0. The tidal distortion for polytropes is from Chandrasekhar, 1933, MNRAS, 93, 449 and the rotational distortion is from James, 1964, ApJ, 140, 552.
  • love: the body is modeled using equation (10) and (11) from Correia, 2014, A&A 570, L5.

More details in Maxted (2016).


Flux weighted RVs per object and instrument

flux_weighted

(bool; optional; default: False)

Example: flux_weighted,False

True for Rossiter-McLaughlin effect, for all other purposes this can be neglected.