Parameters
params.csv
All rows of this file are explained in the following.
Some 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'.
Columns explained
name
The name of the parameter, often decorated with [key], [inst] and [companion]. See ‘rows explained’ for a full list of all possible parameters.
value
The initial guess value. This is needed to make an initial guess plot, initiate the MCMC walkers, to shift the epoch (if shift_epoch in settings.csv is True), or to mask out out-of-transit photometry (if fast_fit in settings.csv is True).
fit
Do you want to fit or freeze this parameter? This can have two values:
0: You want to freeze this value to the one given in the column value.
1: You want to sample/fit for this value.
bounds
The bounds of the fit. This can have the following values:
uniform a b: a uniform prior ranging from a to b
normal mu sigma: a normal prior with mean mu and standard deviation sigma
trunc_normal a b mu sigma: a truncated normal prior with mean mu and standard deviation sigma, truncated to a range from a to b
label
The labels of each parameter (just needed for fancy output plots and tables).
unit
The units of each parameter (just needed for fancy output plots and tables).
coupled_with
Optional column. For example, if you have two files TESS1 and TESS2, and you want to couple their error scaling sampling, you can set ln_err_flux_TESS1 as usual, and leave all rows of ln_err_flux_TESS2 empty besides for its column coupled_with, in which you can then write ln_err_flux_TESS1. allesfitter will not sample for the parameter of ln_err_flux_TESS2, but instead copy the value of ln_err_flux_TESS1 at every sampling step. In summary, you will only sample for one parameter, and the other will mirror it.
truth
Optional column. If given, you can give all the ‘true values’ of the parameters (where known), and they will be marked in the output corner plots and trace plots.
Rows explained
Frequently needed astrophysical parameters
[companion]_rr
The radius ratio of companion to host; should usually be between 0 and 1 (optional; default: None).
[companion]_rsuma
The sum of stellar and companion radii, divided by the semi-major axis.; should usually be between 0 and 1 (optional; default: None).
[companion]_cosi
The cosine of the orbit of this companion; should usually be between 0 and 1 (optional; default: 0).
[companion]_epoch
The epoch, i.e. transit/eclipse midtime (optional; default: None).
This is often given as the first transit epoch, but should usually lie in the middle of the data set, to break as much of the degeneracy between epoch and period as possible. But no reason to work yourself. Simply activate shift_epoch in the settings file, and whatever epoch you give here will be automatically translated into the middle of the data set.
[companion]_period
The orbital period of the companion (optional; default: None).
[companion]_K
The host's RV semi-amplitude caused by the companion (optional; default: 0).
[companion]_f_c
Transformation of eccentricity and argument of periastron as sqrt(e) cos(omega) (optional; default: 0).
[companion]_f_s
Transformation of eccentricity and argument of periastron as sqrt(e) sin(omega) (optional; default: 0).
[companion]_sbratio_+[inst]
The surface brightness ratio between the companion and host star (optional; default: 0).
dil_[inst]
The dilution of the signals in the given instruments bandpass (optional; default: 0).
allesfitter's definition of dilution is D_0 = 1 - F_source / (F_source + F_blend)
Note 1: ellc's original definition of third light is light_3 = F_blend / F_source; therefore we can relate them as light_3 = D_0 / (1 - D_0) and D_0 = light_3 / (1 + light_3).
Note 2: the TESS SPOC lightcurve parameter CROWDSAP = F_source / (F_source + F_blend); hence D_0 = 1 - CROWDSAP
Note 3: the TICv8 definition of "Contamination Ratio" is equivalent to ellc's definition, i.e. Contamination Ratio = F_blend / F_source; hence D_0 = Contamination Ratio / (1 + Contamination Ratio); however, Contamination Ratio is only an estimation, hence the CROWDSAP value should be used if available.
Limb darkening coefficients per instrument
There are many ways this can go different here, all depends strongly on what you decided upon in the settings file.
1. Do you want to do a typical exoplanet fit where you chose a quadratic limb darkening for the star, and no limb darkening for the planet? If yes, give:
host_ldc_q1_[inst]
host_ldc_q2_[inst]
Note that q1 and q2 refer to the parametrization from Kipping et al. (2013). If you want to fix your limb darkening to tabulated values (evil), then you need to translate these first from (u1,u2) into (q1,q2) using the following equations:
u1 = 2 * \sqrt{q1} * q2
u2 = \sqrt{q1} * (1 - 2 * q2)
2. Do you want to do a typical binary fit where you chose a quadratic limb darkening for the star and its companion? If yes, give:
host_ldc_q1_[inst]
host_ldc_q2_[inst]
[companion]_ldc_q1_[inst]
[companion]_ldc_q2_[inst
Note that q1 and q2 refer to the parametrization from Kipping et al. (2013). If you want to fix your limb darkening to tabulated values (evil), then you need to translate these first from (u1,u2) into (q1,q2) using the following equations:
u1 = 2 * \sqrt{q1} * q2
u2 = \sqrt{q1} * (1 - 2 * q2)
3. Do you have low precision data and just want to see if a box will do? If yes, no need to give anything.
4. Do you have low precision data and want to fit only a linear limb darkening?
host_ldc_q1_[inst]
Note that in this case q1 = u1, so you can do all the evil freezing of tabulated limb darkening coefficients directly.
Errors (white noise) per instrument
If you selected sample in the settings file, these parameters get sampled as every other parameter:
ln_err_flux_[inst]: the error scaling for photometric instruments
ln_jitter_rv_[inst]: the jitter term, added in quadrature to the user-given errors for RV instruments
If you selected hybrid in the settings file, these things will be automatically optimized at every step in the sampling, so you don't need to give anything in the params file.
Baselines (red noise) per instrument
If you use the sample_* options in the settings file, these parameters get sampled as every other parameter, and boi oh boi are there many options:
1. Did you select sample_offset for this [key] and [inst] in the settings file? If yes, give:
baseline_offset_[key]_[inst]
2. Did you select sample_linear for this [key] and [inst] in the settings file? If yes, give:
baseline_offset_[key]_[inst] and
baseline_slope_[key]_[inst]:
If you want to physically interpret the slope result: to calculate the slope, the center point of the line fit per instrument will be put in the middle of the time stamps, and the time array will be normalized to 0 to 1.
3. Did you select sample_GP_Real for this [key] and [inst] in the settings file? If yes, give:
baseline_gp_real_lna_[key]_[inst] and
baseline_gp_real_lnc_[key]_[inst]:
The kernel is explained in Table 1 below.
lna reflects the amplitude.
lnc reflects the time scale.
4. Did you select sample_GP_Complex for this [key] and [inst] in the settings file? If yes, give:
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]
The kernel is explained in Table 1 below.
lna and lnb influence the amplitude.
lnc and lnb influence the time scale.
5. Did you select sample_GP_Matern32 for this [key] and [inst] in the settings file? If yes, give:
baseline_gp_matern32_lnsigma_[key]_[inst] and
baseline_gp_matern32_lnrho_[key]_[inst]:
The kernel is explained in Table 1 below.
lnsigma reflects the characteristic amplitude of the GP.
lnrho reflects the characteristic length scale of the GP.
6. Did you select sample_GP_SHO for this [key] and [inst] in the settings file? If yes, give:
baseline_gp_sho_lnS0_[key]_[inst],
baseline_gp_sho_lnQ_[key]_[inst]and
baseline_gp_sho_lnomega0_[key]_[inst]
The kernel is explained in Table 1 below.
lnS0 reflects the amplitude.
lnQ reflects the damping component.
lnomega0 relates to the signal's period as follows: P_rot = (2 pi) / exp(lnomega0).
For example, if you have a prior on the stellar rotation period, you can derive lnomega0 = ln( (2 pi) / P_rot ).
If you use the hybrid_* versions in the settings file, the baseline parameters will be automatically optimized at every step in the sampling, so you don't need to give anything in the params file.
TIP: For all sample_GP_* options, you can always optionally add baseline_gp_offset_[key]_[inst], in which case the GP mean is set to this parameter (rather than assumed to be 0). Note that the GP is constrained on the residuals (data-model), so typically the GP mean is 0; but, for example, if you need to sample for the systemic velocity of your RV data, you will need this.
Stellar variability
If you use the sample_* options in the settings file, these parameters get sampled as every other parameter, and boi oh boi are there many options:
1. Did you select sample_offset for this [key] in the settings file? If yes, give:
stellar_var_offset_[key]
2. Did you select sample_linear for this [key] in the settings file? If yes, give:
stellar_var_offset_[key] and
stellar_var_slope_[key]:
If you want to physically interpret the slope result: to calculate the slope, the center point of the line fit per instrument will be put in the middle of the time stamps, and the time array will be normalized to 0 to 1.
3. Did you select sample_GP_Real for this [key] in the settings file? If yes, give:
stellar_var_gp_real_lna_[key] and
stellar_var_gp_real_lnc_[key].
The kernel is explained in Table 1 below.
lna reflects the amplitude.
lnc reflects the time scale.
4. Did you select sample_GP_Complex for this [key] in the settings file? If yes, give:
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]
The kernel is explained in Table 1 below.
lna and lnb influence the amplitude.
lnc and lnb influence the time scale.
5. Did you select sample_GP_Matern32 for this [key] in the settings file? If yes, give:
stellar_var_gp_matern32_lnsigma_[key] and
stellar_var_gp_matern32_lnrho_[key]:
The kernel is explained in Table 1 below.
lnsigma reflects the characteristic amplitude of the GP.
lnrho reflects the characteristic length scale of the GP.
6. Did you select sample_GP_Matern32 for this [key] in the settings file? If yes, give:
stellar_var_gp_sho_lnS0_[key],
stellar_var_gp_sho_lnQ_[key] and
stellar_var_gp_sho_lnomega0_[key].
The kernel is explained in Table 1 below.
lnS0 reflects the amplitude.
lnQ reflects the damping component.
lnomega0 relates to the signal's period as follows: P_rot = (2 pi) / exp(lnomega0).
For example, if you have a prior on the stellar rotation period, you can derive lnomega0 = ln( (2 pi) / P_rot ).
If you use the hybrid_* versions in the settings file, the baseline parameters will be automatically optimized at every step in the sampling, so you don't need to give anything in the params file.
Phase curves I: sine series
If you selected sine_series in the settings file, this is your section :)
Standard set:
[companion]_phase_curve_A1_[inst]
Semi-amplitude of the sine term $A_1 \sin{\Phi(t)}$ approximating the Doppler boosting (beaming) modulation (in parts-per-thousand, ppt). Default None.
[companion]_phase_curve_B1_[inst]
Semi-amplitude of the cosine term $B_1 \cos{\Phi(t)}$ approximating the atmospheric (thermal and reflected light) modulation (in ppt). Default None.
[companion]_phase_curve_B1_shift_[inst]
Time shift $s$ of the cosine term $B_1 \cos{\Phi(t + s)}$ (in days). Default 0.
[companion]_phase_curve_B2_[inst]
Semi-amplitude of the cosine term $B_2 \cos{2\Phi(t)}$ approximating the leading-order ellipsoidal (tidal distortion) modulation (in ppt). Default None.
[companion]_phase_curve_B3_[inst]
Semi-amplitude of the cosine term $B_3 \cos{3\Phi(t)}$ approximating the next-order ellipsoidal (tidal distortion) modulation (in ppt); this is usually negligible for exoplanets but can become measurable for binary stars. Default None.
For differentiating thermal emission and reflected light, you can use:
[companion]_phase_curve_B1t_[inst]
Semi-amplitude of the cosine term $B_{1t} \cos{\Phi(t)}$ approximating the thermal emission part of the atmospheric modulation (in ppt). Default None.
[companion]_phase_curve_B1t_shift_[inst]
Time shift $s$ of the cosine term $B_{1t} \cos{\Phi(t + s)}$ (in days). Default 0.
[companion]_phase_curve_B1r_[inst]
Semi-amplitude of the cosine term $B_{1r} \cos{\Phi(t)}$ approximating the reflected light part of the atmospheric modulation (in ppt). Default None.
[companion]_phase_curve_B1r_shift_[inst]
Time shift $s$ of the cosine term $B_{1r} \cos{\Phi(t + s)}$ (in days). Default 0.
Phase curves II: sine physical
If you selected sine_physical in the settings file, this is your section :)
Standard set:
[companion]_phase_curve_beaming_[inst]
Positive semi-amplitude of the beaming effect, representing the term $A_1 \sin{\phi(t)}$, i.e. a mod. around the median flux level of the star \revision{(in ppt)}. Default None.
[companion]_phase_curve_atmospheric_[inst]
Positive full (peak-to-peak) amplitude of the atmospheric contribution, representing the term $-2 B_1 (1 - \cos{\phi(t)}$, i.e. an additive component to the companion's nightside flux (in ppt). Default None.
[companion]_phase_curve_atmospheric_shift_[inst]
Time shift of the atmospheric contribution term (in days). Default 0.
[companion]_phase_curve_ellipsoidal_[inst]
Positive full (peak-to-peak) amplitude of the leading-order term of the ellipsoidal mod., representing the term $-2 B_2 (1 - \cos{(2\phi(t))})$, i.e. an additive component to the system's flux from spherical (non-distorted) bodies (in ppt). Default None.
[companion]_phase_curve_ellipsoidal_2nd_[inst]
Positive full (peak-to-peak) amplitude of the next-order term of the ellipsoidal mod., representing the term $-2 B_3 (1 - \cos{(3\phi(t))})$, i.e. an additive component to the system's flux from spherical (non-distorted) bodies (in ppt). Default None.
For differentiating thermal emission and reflected light, you can use:
[companion]_phase_curve_atmospheric_thermal_[inst]
Positive full (peak-to-peak) amplitude of the atmospheric thermal emission (in ppt). Default None.
[companion]_phase_curve_atmospheric_thermal_shift_[inst]
Time shift of the atmospheric thermal emission (in days). Default 0.
[companion]_phase_curve_atmospheric_reflected_[inst]
Positive full (peak-to-peak) amplitude of the atmospheric reflected light (in ppt). Default None.
[companion]_phase_curve_atmospheric_reflected_shift_[inst]
Time shift of the atmospheric reflected light (in days). Default 0.
Star spots
host_spot_[i]_long_+[inst]
The longitude of the stellar spot on the host (in degree from 0 to 360)
host_spot_[i]_lat_+[inst]
The latitude of the stellar spot on the host (in degree from -90 to 90)
host_spot_[i]_size_+[inst]
The angular radius of the stellar spot on the host (in degree)
host_spot_[i]_brightness_+[inst]
The brightness ratio between the spot and the surface of the host
[companion]_spot_[i]_long_+[inst]
The longitude of the stellar spot on the companion (in degree from 0 to 360)
[companion]_spot_[i]_lat_+[inst]
The latitude of the stellar spot on the companion (in degree from -90 to 90)
[companion]_spot_[i]_size_+[inst]
The angular radius of the stellar spot on the companion (in degree)
[companion]_spot_[i]_brightness_+[inst]
The brightness ratio between the spot and the surface of the companion
Stellar flares
flare_tpeak_[i]
The peak time of flare number i (i=1,2,3...); only used if N_flares in settings.csv is given
flare_fwhm_[i]
The full-width at half maximum of flare number i (i=1,2,3...); only used if N_flares in settings.csv is given
flare_ampl_[i]
The amplitude of flare number i (i=1,2,3...); only used if N_flares in settings.csv is given
Advanced parameters (e.g., for ellc's physical phase curves)
Do not use these unless you completely understand what is going on under the hood! When in doubt, drop us an email before using these!
[companion]_q
The mass ratio between the companion and host (optional; default: 1).
Note that this is actually never used UNLESS you want to compute the ellipsoidal modulation via ellc’s roche/polytrop/etc. shapes. Then and only then, q is used to compute the shape; but never for any other property. This is because P, a, K and q are all degenerate with one another, so not all of them are needed to compute the orbits and light curve.
host_gdc
Gravity darkening coefficient for the host (optional; default: None).
[companion]_gdc
Gravity darkening coefficient for the companion (optional; default: None).
host_heat_[inst]
Coefficient of a simplified reflection and emission model on the host's side facing the companion (optional; default: None).
[companion]_heat_[inst]
Coefficient of a simplified reflection and emission model on the companion's side facing the host (optional; default: None).
host_bfac_[inst]
Doppler boosting factor of the host (optional; default: None).
[companion]_bfac_[inst]
Doppler boosting factor of the companion (optional; default: None).
didt_[inst]
Rate of change of inclination (in degrees per anomalistic period; optional; default: None).
domdt_[inst]
Rate of apsidal motion (in degrees per anomalistic period; optional; default: None).
host_rotfac
Asynchronous rotation factor for the host (optional; default: 1).
[companion]_rotfac
Asynchronous rotation factor for the companion (optional; default: 1).
host_hf_[inst]
Fluid second Love number for radial displacement, for the host; only used if host_shape_[inst] is love (optional; default: 1.5).
[companion]_hf_[inst]
Fluid second Love number for radial displacement, for the companion; only used if [companion]_shape_[inst] is love (optional; default: 1.5).
host_lambda
Sky-projected angle between orbital and rotation axes for the host (in degree; optional; default: None).
[companion]_lambda
Sky-projected angle between orbital and rotation axes for the companion (in degree; optional; default: None).
host_vsini
Rotational v sini for calculation of the Rossiter-McLaughlin effect for the host (in km/s; optional; default: None).
[companion]_vsini
Rotational v sini for calculation of the Rossiter-McLaughlin effect for the companion (in km/s; optional; default: None).
Table 1: Available baseline and stellar variability models M(t) dependent on time t.