Models, priors and outputs

As it was shown in the Getting started section, a typical juliet run will make use of two objects which form the core of the library: the load object and the fit object. The former is used to load a dataset, and the second is used to fit that dataset using the samplers supported within juliet, which in turn spits out the result of the fit including posterior distributions, fits, etc. In general, a dataset can be loaded to juliet by the simple call

import juliet
dataset = juliet.load(priors=priors, t_lc = times, y_lc = fluxes, \
                      yerr_lc = fluxes_error, t_rv = rvtimes, y_rv = rvs, \
                      yerr_rv = rv_errs, out_folder = yourfolder)

Here times, fluxes and fluxes_error are dictionaries containing the lightcurve data and rvtimes, rvs and rv_errs contain the radial-velocity data, where each key should have the instrument name and under each of those instruments an array should be given with the corresponding data. Alternatively, you might give paths to files that contain your data given they have times in the first column, data in the second, errors in the data in the third column and instrument names in the fourth via the lcfilename and rvfilename options (e.g., juliet.load(...,lcfilename = path_to_lc)).

The priors variable, on the other hand, is either a dictionary or a filename containing the prior distribution information for each parameter in the model (see below) and yourfolder is a user-defined folder that is used to save the results (and the data!).

Once a dataset is loaded it can be fit by doing dataset.fit(). The options of the fit can of course be modified — we refer the users to the API on this documentation for details on this front.

Exoplanets with juliet, pt. I: planetary parameters

To date, juliet is able to model transit and radial-velocities (RVs), each of which have their own set of parameters. We have divided the types of parameters into what we call the planetary parameters and the instrument parameters. Within juliet, the former set of parameters are always of the form parameter_pN, where N is a number identifier for a given planet (yes, juliet handles multiple-planet systems!). The instrument parameters, on the other hand, are always of the form parameter_instrument, where instrument is an instrument name.

The (basic) planetary parameters currently supported by juliet are:

Parameter name Description
P_p1 The planetary period of the planet under study (days).
t0_p1 The time-of-transit center of the planet under study (days).
p_p1 Planet-to-star radius ratio (Rp/Rs).
b_p1 Impact parameter of the orbit.
a_p1 Scaled semi-major axis of the orbit (a/R*).
ecc_p1 Eccentricity of the orbit.
omega_p1 Argument of periastron passage of the orbit (in degrees).
K_p1 RV semi-amplitude of the orbit of the planet (same units as RV data).

Within juliet, it is very important that the periods of the planets are in chronological order, i.e., that P_p1 < P_p2 < ..... This is to avoid solutions in which the periods of the planets can be exchanged between the variables. When fitting for transit data, all of the above but K have to be defined for each planet. When fitting radial-velocities, only P, t0, ecc, omega and K have to be defined. When fitting both, all of these have to be defined.

Although the above are the basic planetary parameters allowed by juliet, the library allows to perform three more advanced and efficient parametrizations for some of its parameters:

  • The first is the one proposed by Espinoza (2018), in which instead of fitting for p and b, one fits for the parameters r1 and r2 which, if sampled with uniform priors between 0 and 1, are able to allow only physically plausible values for p and b (i.e., b < 1 + p). This parametrization needs one to define the smallest planet-to-star radius ratio to be considered, pl and the maximum planet-to-star radius ratio to be considered, pu. For a coarse search, one could set pl to zero and pu to 1 — these are the default values within juliet.
  • The second parametrization allowed by juliet is to define a prior for the stellar density, rho (in kg/m^3) instead of the scaled semi-major axis of the planets, a. This is useful because setting this for a system, using Kepler’s third law one can recover a for each planet using only the period, P, which is a mandatory parameter for any juliet run. In this way, instead of fitting for a for different planetary systems, a single value of rho can be defined for the system.
  • The third parametrization has to do with the eccentricity and the argument of periastron. juliet allows either to (1) fit for them directly (via the ecc and omega parameters), (2) to fit for the parameters esinomega = ecc*sin(omega*pi/180) and ecosomega = ecc*cos(omega*pi/180) or (3) to fit for the parameters sesinomega = sqrt(ecc)*sin(omega*pi/180) and secosomega = sqrt(ecc)*cos(omega*pi/180). The latter two are typically defined between -1 and 1, and within juliet it is always ensured that the eccentricity is smaller than 1.

Finally, for RVs there are three additional “planetary parameters” that can be passed, which are helpful to model long-period planets for which no full cycles have been observed in the data yet. These are the rv_intercept, rv_slope and rv_quad. These fit a long-term trend to the RVs which is added to the Keplerian model and is of the form rv_intercept + (t-ta)*rv_slope + (t-ta)**2*rv_quad. ta is an arbitrary time, which within juliet is defined to be 2458460 — this arbitrary time can of course be changed by the user. To do it, when fitting a dataset simply do dataset.fit(..., ta = yourdate).

Exoplanets with juliet, pt. II: instrumental parameters

The instrument parameters currently supported by juliet are:

Parameter name Description
mdilution_instrument The dilution factor for the photometric instrument.
mflux_instrument The offset relative flux for the photometric instrument.
sigma_w_instrument A jitter (in ppm or RV units) added in quadrature to the errorbars of instrument.
q1_instrument Limb-darkening parametrization for photometric instrument.
q2_instrument Limb-darkening parametrization for photometric instrument.
mu_instrument Systemic radial-velocity for a radial-velocity instrument (same units as data).

Here, q1 and q2 are the limb-darkening parametrizations of Kipping (2013) for two-parameter limb-darkening laws for all laws except for the logarithmic, where they correspond to the transformations in Espinoza & Jordan (2016). If the linear law is to be used, the user has to only define q1 which will be interpreted directly as the limb-darkening coefficient of the linear law. For juliet analyses only using photometry, mdilution, mflux, sigma_w, q1 and q2 have to defined. For analyses only using radial-velocity measurements, mu and sigma_w have to be defined. All must be defined in the case of joint fits.

By default, the limb-darkening law assumed in the fits for all instruments is the quadratic law. However, one can define different limb-darkening laws for different instruments passing a string to the ld_laws input of the juliet.load() object, where the string defines the names and laws to be used for each instrument separated by commas (e.g., juliet.load(...,ld_laws = 'TESS-quadratic,K2-logarithmic,LCOGT-linear'). Limb-darkening coefficients and dilution factors can be common within instruments, too. To force this, simply give all the instruments that should be common to different instruments separated by underscores when passing the priors (see below) to juliet, e.g., q1_TESS_K2.

Warning

Because in juliet the internal parameters include underscores (_), the instrument names should not contain underscores. In this way, for example, instead of naming your instrument My_Instrument (as in, e.g., mdilution_My_instrument), prefer My-Instrument or MyInstrument instead.

Exoplanets with juliet, pt. III: linear models & gaussian processes

There are additional instrument parameters that can be given to juliet to account for linear models in the data and/or gaussian-processes. For linear models, it is assumed each linear regressor X of instrument instrument will be weighted by a parameter thetaX_instrument. There is no limit to the number of linear terms a given instrument can have, and the linear regressors can either be given directly as a dictionary through the juliet.load call (through the linear_regressors_lc input for lightcurve linear regressors and/or the linear_regressors_rv input for linear regressors for the radial-velocities), or as extra columns in any input lightcurve or radial-velocity file the user is giving as input to that same call. For details, check out the Incorporating linear models tutorial.

For Gaussian Processes (GPs), the regressors can be given in a similar manner as for linear regressors when doing the juliet.load call (i.e., via the analogous GP_regressors_lc and GP_regressors_rv inputs). Alternatively, the name of a file which contains the different regressors on each column with the last column being the instrument name can be given through the same juliet.load call using the GPlceparamfile for the file defining the GP regressors for the lightcurves and GPrveparamfile for the file defining the GP regressors for the radial-velocities.

juliet automatically identifies which kernel the user wants to use for each instrument depending on the name of the GP hyperparameters in the priors. For instrument-by-instrument models (i.e., GP regressions which are individual to each instrument) the parameter names follow the pname_instrument form, where pname is any of the parameter names listed below and instrument is a given instrument (e.g., GP_sigma_TESS). For so-called “global” models, which are models that are not instrument-specific (for more details on the difference between those types of models, check the juliet paper and/or the Incorporating Gaussian Processes tutorial), the parameter names follow the pname_lc form for global lightcurve models, and pname_rv for radial-velocity global models.

Below we list the GP kernels implemented so far within juliet. More kernels can be implemented upon request and/or via git push to the juliet repository — again, for usage details, please check out the Incorporating Gaussian Processes tutorial:

Multi-dimensional squared-exponential kernel

Hyperparameters Description
GP_sigma Amplitude of the GP (in ppm for the photometry, units of measurements for RVs)
GP_alpha0 Inverse (squared) length-scale/normalized amplitude of the first external parameter
GP_alpha1 Inverse (squared) length-scale/normalized amplitude of the second external parameter
GP_alphan Inverse (squared) length-scale/normalized amplitude of the n+1 external parameter

Exp-sine-squared kernel

Hyperparameters Description
GP_sigma Amplitude of the GP (in ppm for the photometry, units of measurements for RVs)
GP_alpha Inverse (squared) length-scale of the external parameter
GP_Gamma Amplitude of the sine-part of the kernel
GP_Prot Period of the quasi-periodic kernel

celerite quasi-periodic kernel

Hyperparameters Description
GP_B Amplitude of the GP (in ppm for the photometry, units of measurements for RVs)
GP_C Additive factor impacting on the amplitude of the GP
GP_L Length-scale of exponential part of the GP
GP_Prot Period of the quasi-periodic GP

celerite Simple Harmonic Oscillator (SHO) kernel

Hyperparameters Description
GP_S0 Characteristic power of the SHO
GP_omega0 Characteristic frequency of the SHO
GP_Q Quality factor of the SHO

celerite (approximate) Matern kernel

Hyperparameters Description
GP_sigma Amplitude of the GP (in ppm for the photometry, units of measurements for RVs)
GP_rho Time/length-scale of the GP

celerite exponential kernel

Hyperparameters Description
GP_sigma Amplitude of the GP (in ppm for the photometry, units of measurements for RVs)
GP_timescale Time/length-scale of the GP

celerite (approximate) Matern multiplied by exponential kernel

Hyperparameters Description
GP_sigma Amplitude of the GP (in ppm for the photometry, units of measurements for RVs)
GP_rho Time/length-scale of the Matern part of the GP
GP_timescale Time/length-scale of the exponential part of the GP

Priors

As introduced at the beggining, a set of priors can be defined for the parameters under consideration via the priors variable, which can be either a filename containing a file with the priors as was done in the Getting started section, or a dictionary, as was also done in that section. Currently, juliet supports the following prior distributions to be defined for the parameters:

Distribution Description Hyperparameters
Uniform A uniform distribution defined between a lower (a) and upper (b) limit. a,b
Normal A normal distribution defined by its mean mu and standard-deviation sigma. mu,sigma
TruncatedNormal A normal distribution defined by its mean mu and standard-deviation sigma, along with a lower (a) and upper (b) limit defining its support. mu,sigma,a,b
Jeffreys or Loguniform A log-uniform distribution defined between a lower (a) and upper (b) limit. a,b
Beta A beta distribution having support between 0 and 1 defined by its alpha and beta parameters. alpha,beta

Note that the hyperparameters have to be passed on the order defined above in the prior file or dictionary. Further distributions can be made available for juliet upon request, as they are extremely easy to implement. If a parameter wants to be fixed to a known value, then the prior distribution can be set to FIXED.

Outputs

Once a juliet fit is ran (e.g., results = dataset.fit()), this will generate a juliet.fit object which has several features the user can explore. The most important is the juliet.fit.posteriors dictionary, which contains three important keys: posterior_samples, which is a dictionary having the posterior samples for all the fitted parameters, lnZ, which has the log-evidence for the current fit and lnZerr which has the error on the log-evidence. This same dictionary is also automatically saved to the output folder if there was one defined by the user as a .pkl file.

In addition, a file called posteriors.dat file is also printed out if an output folder is given, which is of the form

# Parameter Name                 Median                  Upper 68 CI             Lower 68 CI
q2_TESS                          0.4072409698            0.3509391055            0.2793487941
P_p1                             1.0079166018            0.0000827690            0.0000545234
a_p1                             4.5224665335            0.5972474545            1.3392152148
q1_TESS                          0.2178116586            0.2583946746            0.1424332922
r2_p1                            0.0146632299            0.0008468341            0.0006147659
p_p1                             0.0146632299            0.0008468341            0.0006147659
b_p1                             0.5122384103            0.2961574900            0.3206523210
inc_p1                           83.5179400288           4.3439922509            8.1734713106
mflux_TESS                       -0.0000154812           0.0000021394            0.0000020902
rho                              1722.5385338667         776.2573107345          1121.9672108451
t0_p1                            1325.5386166342         0.0008056050            0.0012949209
r1_p1                            0.6748256069            0.1974383267            0.2137682140
sigma_w_TESS                     127.3813413245          3.6857084428            3.3647860049

This contains on the first column the parameter name, in the second the median, in the third the upper 68% credibility band in the fourth column the 68% lower credibility band of the parameter, as extracted from the posterior distribution. For more output results (e.g., model evaluations, predictions, plots) check out the tutorials!