The params file

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 params


[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).


[companion]_dil

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.


[companion]_phase_curve_beaming_[inst]

Amplitude of the Doppler boosting (beaming) modulation in a phase curve, approximated as a sine term (optional; default: None)


[companion]_phase_curve_atmospheric_[inst]

Amplitude of the atmospheric (thermal and reflected light) modulation in a phase curve, approximated as a cosine term (optional; default: None)


[companion]_phase_curve_ellipsoidal_[inst]

Amplitude of the ellipsoidal (tidal distortion) modulation in a phase curve, approximated as a second-order cosine term (optional; default: None)


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_Matern32 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.


Table 1: Available baseline and stellar variability models M(t) dependent on time t.


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.


Star spot params


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 flare params


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 and rarely needed params (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_[inst]

Sky-projected angle between orbital and rotation axes for the host (in degree; optional; default: None).


[companion]_lambda_[inst]

Sky-projected angle between orbital and rotation axes for the companion (in degree; optional; default: None).



host_vsini_[inst]

Rotational v sini for calculation of R-M effect for the host (in km/s; optional; default: None).


[companion]_vsini_[inst]

Rotational v sini for calculation of R-M effect for the companion (in km/s; optional; default: None).