# 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.- l
*in:*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.