# API¶

The core classes within juliet are the load and fit classes. When creating a juliet.load object, the returned object will be able to call a fit function which in turn returns a juliet.fit object, which saves all the information about the fit (results statistics, posteriors, model evaluations, etc.) — these classes are explained in detail below:

class juliet.load(priors=None, input_folder=None, t_lc=None, y_lc=None, yerr_lc=None, t_rv=None, y_rv=None, yerr_rv=None, GP_regressors_lc=None, linear_regressors_lc=None, GP_regressors_rv=None, linear_regressors_rv=None, out_folder=None, lcfilename=None, rvfilename=None, GPlceparamfile=None, GPrveparamfile=None, LMlceparamfile=None, LMrveparamfile=None, lctimedef='TDB', rvtimedef='UTC', ld_laws='quadratic', priorfile=None, lc_n_supersamp=None, lc_exptime_supersamp=None, lc_instrument_supersamp=None, mag_to_flux=True, verbose=False, matern_eps=0.01, pickle_encoding=None)

Given a dictionary with priors (or a filename pointing to a prior file) and data either given through arrays or through files containing the data, this class loads data into a juliet object which holds all the information about the dataset. Example usage:

>>> data = juliet.load(priors=priors,t_lc=times,y_lc=fluxes,yerr_lc=fluxes_errors)


Or, also,

>>> data = juliet.load(input_folder = folder)

Parameters: priors – (optional, dict or string) This can be either a python string or a python dict. If a dict, this has to contain each of the parameters to be fit, along with their respective prior distributions and hyperparameters. Each key of this dictionary has to have a parameter name (e.g., r1_p1, sigma_w_TESS), and each of those elements are, in turn, dictionaries as well containing two keys: a distribution key which defines the prior distribution of the parameter and a hyperparameters key, which contains the hyperparameters of that distribution. Example setup of the priors dictionary: >> priors = {} >> priors[‘r1_p1’] = {} >> priors[‘r1_p1’][‘distribution’] = ‘Uniform’ >> priors[‘r1_p1’][‘hyperparameters’] = [0.,1.] If a string, this has to contain the filename to a proper juliet prior file; the prior dict will then be generated from there. A proper prior file has in the first column the name of the parameter, in the second the name of the distribution, and in the third the hyperparameters of that distribution for the parameter. Note that this along with either lightcurve or RV data or a input_folder has to be given in order to properly load a juliet data object. input_folder – (optional, string) Python string containing the path to a folder containing all the input data — this will thus be load into a juliet data object. This input folder has to contain at least a priors.dat file with the priors and either a lc.dat file containing lightcurve data or a rvs.dat file containing radial-velocity data. If in this folder a GP_lc_regressors.dat file or a GP_rv_regressors.dat file is found, data will be loaded into the juliet object as well. Note that at least this or a priors string or dictionary, along with either lightcurve or RV data has to be given in order to properly load a juliet data object. t_lc – (optional, dictionary) Dictionary whose keys are instrument names; each of those keys is expected to have arrays with the times corresponding to those instruments. For example, >>> t_lc = {} >>> t_lc['TESS'] = np.linspace(0,100,100)  Is a valid input dictionary for t_lc. y_lc – (optional, dictionary) Similarly to t_lc, dictionary whose keys are instrument names; each of those keys is expected to have arrays with the fluxes corresponding to those instruments. These are expected to be consistent with the t_lc dictionaries. yerr_lc – (optional, dictionary) Similarly to t_lc, dictionary whose keys are instrument names; each of those keys is expected to have arrays with the errors on the fluxes corresponding to those instruments. These are expected to be consistent with the t_lc dictionaries. GP_regressors_lc – (optional, dictionary) Dictionary whose keys are names of instruments where a GP is to be fit. On each name/element, an array of regressors of shape (m,n) containing in each column the n GP regressors to be used for m photometric measurements has to be given. Note that m for a given instrument has to be of the same length as the corresponding t_lc for that instrument. Also, note the order of each regressor of each instrument has to match the corresponding order in the t_lc array. For example, >>> GP_regressors_lc = {} >>> GP_regressors_lc['TESS'] = np.linspace(-1,1,100)  If a global model wants to be used, then the instrument should be rv, and each of the m rows should correspond to the m times. linear_regressors_lc – (optional, dictionary) Similarly as for GP_regressors_lc, this is a dictionary whose keys are names of instruments where a linear regression is to be fit. On each name/element, an array of shape (q,p) containing in each column the p linear regressors to be used for the q photometric measurements. Again, note the order of each regressor of each instrument has to match the corresponding order in the t_lc array. GP_regressors_rv – (optional, dictionary) Same as GP_regressors_lc but for the radial-velocity data. If a global model wants to be used, then the instrument should be lc, and each of the m rows should correspond to the m times. linear_regressors_rv – (optional, dictionary) Same as linear_regressors_lc, but for the radial-velocities. t_rv – (optional, dictionary) Same as t_lc, but for the radial-velocities. y_rv – (optional, dictionary) Same as y_lc, but for the radial-velocities. yerr_rv – (optional, dictionary) Same as yerr_lc, but for the radial-velocities. out_folder – (optional, string) If a path is given, results will be saved to that path as a pickle file, along with all inputs in the standard juliet format. lcfilename – (optional, string) If a path to a lightcurve file is given, t_lc, y_lc, yerr_lc and instruments_lc will be read from there. The basic file format is a pure ascii file where times are in the first column, relative fluxes in the second, errors in the third and instrument names in the fourth. If more columns are given for a given instrument, those will be identified as linear regressors for those instruments. rvfilename – (optional, string) Same as lcfilename, but for the radial-velocities. GPlceparamfile – (optional, string) If a path to a file is given, the columns of that file will be used as GP regressors for the lightcurve fit. The file format is a pure ascii file where regressors are given in different columns, and the last column holds the instrument name. The order of this file has to be consistent with t_lc and/or the lcfilename file. If a global model wants to be used, set the instrument names of all regressors to lc. GPrveparamfile – (optional, string) Same as GPlceparamfile but for the radial-velocities. If a global model wants to be used, set the instrument names of all regressors to rv. LMlceparamfile – (optional, string) If a path to a file is given, the columns of that file will be used as linear regressors for the lightcurve fit. The file format is a pure ascii file where regressors are given in different columns, and the last column holds the instrument name. The order of this file has to be consistent with t_lc and/or the lcfilename file. If a global model wants to be used, set the instrument names of all regressors to lc. LMrveparamfile – (optional, string) Same as LMlceparamfile but for the radial-velocities. If a global model wants to be used, set the instrument names of all regressors to rv. lctimedef – (optional, string) Time definitions for each of the lightcurve instruments. Default is to assume all instruments (in lcs and rvs) have the same time definitions. If more than one instrument is given, this string should have instruments and time-definitions separated by commas, e.g., TESS-TDB, LCOGT-UTC, etc. rvtimedef – (optional, string) Time definitions for each of the radial-velocity instruments. Default is to assume all instruments (in lcs and rvs) have the same time definitions. If more than one instrument is given, this string should have instruments and time-definitions separated by commas, e.g., FEROS-TDB, HARPS-UTC, etc. ld_laws – (optional, string) Limb-darkening law to be used for each instrument. Default is quadratic for all instruments. If more than one instrument is given, this string should have instruments and limb-darkening laws separated by commas, e.g., TESS-quadratic, LCOGT-linear. priorfile – (optional, string) If a path to a file is given, it will be assumed this is a prior file. The priors dictionary will be overwritten by the data in this file. The file structure is a plain ascii file, with the name of the parameters in the first column, name of the prior distribution in the second column and hyperparameters in the third column. lc_instrument_supersamp – (optional, array of strings) Define for which lightcurve instruments super-sampling will be applied (e.g., in the case of long-cadence integrations). e.g., lc_instrument_supersamp = ['TESS','K2'] lc_n_supersamp – (optional, array of ints) Define the number of datapoints to supersample. Order should be consistent with order in lc_instrument_supersamp. e.g., lc_n_supersamp = [20,30]. lc_exptime_supersamp – (optional, array of floats) Define the exposure-time of the observations for the supersampling. Order should be consistent with order in lc_instrument_supersamp. e.g., lc_exptime_supersamp = [0.020434,0.020434] verbose – (optional, boolean) If True, all outputs of the code are printed to terminal. Default is False. matern_eps – (optional, float) Epsilon parameter for the Matern approximation (see celerite documentation). pickle_encoding – (optional, string) Define pickle encoding in case fit was done with Python 2.7 and results are read with Python 3.
append_GP(ndata, instrument_indexes, GP_arguments, inames)

This function appends all the GP regressors into one — useful for the global models.

convert_input_data(t, y, yerr)

This converts the input dictionaries to arrays (this is easier to handle internally within juliet; input dictionaries are just asked because it is easier for the user to pass them).

convert_to_dictionary(t, y, yerr, instrument_indexes)

Convert data given in arrays to dictionaries for easier user usage

data_preparation(times, instruments, linear_regressors)

This function generates f useful internal arrays for this class: inames which saves the instrument names, global_times which is a “flattened” array of the times dictionary where all the times for all instruments are stacked, instrument_indexes, which is a dictionary that has, for each instrument the indexes of the global_times corresponding to each instrument, lm_boolean which saves booleans for each instrument to indicate if there are linear regressors and lm_arguments which are the linear-regressors for each instrument.

fit(use_dynesty=False, dynamic=False, dynesty_bound='multi', dynesty_sample='rwalk', dynesty_nthreads=None, n_live_points=1000, ecclim=1.0, delta_z_lim=0.5, pl=0.0, pu=1.0)

Perhaps the most important function of the juliet data object. This function fits your data using the nested sampler of choice. This returns a results object which contains all the posteriors information.

generate_datadict(dictype)

This generates the options dictionary for lightcurves, RVs, and everything else you want to fit. Useful for the fit, as it separaters options per instrument.

Parameters: dictype – (string) Defines the type of dictionary type. It can either be ‘lc’ (for the lightcurve dictionary) or ‘rv’ (for the radial-velocity one).
save_data(fname, t, y, yerr, instruments, lm_boolean, lm_arguments)

This function saves t,y,yerr,instruments,lm_boolean and lm_arguments data to fname.

save_priorfile(fname)

This function saves a priorfile file out to fname

save_regressors(fname, GP_arguments)

This function saves the GP regressors to fname.

class juliet.fit(data, use_dynesty=False, dynamic=False, dynesty_bound='multi', dynesty_sample='rwalk', dynesty_nthreads=None, n_live_points=1000, ecclim=1.0, delta_z_lim=0.5, pl=0.0, pu=1.0, ta=2458460.0)

Given a juliet data object, this class performs a fit to the data and returns a results object to explore the results. Example usage:

>>> results = juliet.fit(data)

Params data: (juliet object) An object containing all the information regarding the data to be fitted, including options of the fit. Generated via juliet.load(). use_dynesty – (optional, boolean) If True, use dynesty instead of MultiNest for posterior sampling and evidence evaluation. Default is False, unless MultiNest via pymultinest is not working on the system. dynamic – (optional, boolean) If True, use dynamic Nested Sampling with dynesty. Default is False. dynesty_bound – (optional, string) Define the dynesty bound method to use (currently either single or multi, to use either single ellipsoids or multiple ellipsoids). Default is multi (for details, see the dynesty API). dynesty_sample – (optional, string) Define the sampling method for dynesty to use. Default is rwalk. Accorfing to the dynesty API, this should be changed depending on the number of parameters being fitted. If smaller than about 20, rwalk is optimal. For larger dimensions, slice or rslice should be used. dynesty_nthreads – (optional, int) Define the number of threads to use within dynesty. Default is to use just 1. n_live_points – (optional, int) Number of live-points to be sampled. Default is 500. ecclim – (optional, float) Upper limit on the maximum eccentricity to sample. Default is 1. delta_z_lim – (optional, double) Define the convergence delta_z limit for the nested samplers. Default is 0.5. pl – (optional, float) If the (r1,r2) parametrization for (b,p) is used, this defines the lower limit of the planet-to-star radius ratio to be sampled. Default is 0. pu – (optional, float) Same as pl, but for the upper limit. Default is 1. ta – (optional, float) Time to be substracted to the input times in order to generate the linear and/or quadratic trend to be added to the model. Default is 2458460.

The returned fit object, in turn, also has other objects inherted in it. In particular, if results is a juliet.fit object, results.lc and results.rv are juliet.model objects that host all the details about the dataset being modelled. This follows the model definition outlined in Section 2 of the juliet paper:

class juliet.model(data, modeltype, pl=0.0, pu=1.0, ecclim=1.0, ta=2458460.0, log_like_calc=False)

Given a juliet data object, this kernel generates either a lightcurve or a radial-velocity object. Example usage:

>>> model = juliet.model(data, modeltype = 'lc')

Parameters: data – (juliet.load object) An object containing all the information about the current dataset. modeltype – (optional, string) String indicating whether the model to generate should be a lightcurve (‘lc’) or a radial-velocity (‘rv’) model. pl – (optional, float) If the (r1,r2) parametrization for (b,p) is used, this defines the lower limit of the planet-to-star radius ratio to be sampled. Default is 0. pu – (optional, float) Same as pl, but for the upper limit. Default is 1. ecclim – (optional, float) This parameter sets the maximum eccentricity allowed such that a model is actually evaluated. Default is 1. log_like_calc – (optional, boolean) If True, it is assumed the model is generated to generate likelihoods values, and thus this skips the saving/calculation of the individual models per planet (i.e., self.model['p1'], self.model['p2'], etc. will not exist). Default is False.
evaluate_model(instrument=None, parameter_values=None, resampling=None, nresampling=None, etresampling=None, all_samples=False, nsamples=1000, return_samples=False, t=None, GPregressors=None, LMregressors=None, return_err=False, alpha=0.68, return_components=False)

This function evaluates the current lc or rv model given a set of parameter values. Resampling options can be changed if resampling is a boolean, but the object is at the end rolled-back to the default resampling definitions the user defined in the juliet.load object. For now, resampling only is available for lightcurve models. TODO: add resampling for RVs.

Params instrument:
(optional, string)

Instrument the user wants to evaluate the model on. It is expected to be given for non-global models, not necessary for global models.

Params parameter_values:
(optional, dict)

Dictionary containing samples of the parameter values in it. Each key is a parameter name (e.g. ‘p_p1’, ‘q1_TESS’, etc.), and inside each of those keys an array of N samples is expected (i.e., parameter_values[‘p_p1’] is an array of length N). The indexes have to be consistent between different parameters.

Params resampling:
(optional, boolean)

Boolean indicating if the model needs to be resampled or not

Params etresampling:
(optional, double)

Exposure time of the resampling

Params all_samples:
(optional, boolean)

Boolean indicating if all the posterior samples should be used or only a pre-defined number of samples. Default is 1000.

Params return_samples:
(optional, boolean)

Boolean indicating whether the user wants the posterior samples of the model to be returned.

Params t: (optional, numpy array)

Array with the times at which the model wants to be evaluated

Params GPRegressors:
(optional, numpy array)

Array containing the GP Regressors onto which evaluate the models (same length as t)

Params LMRegressors:
(optional, numpy array or dictionary)

If the model is not global, this is an array containing the Linear Regressors onto which evaulate the model for the input instrument. Has to have the same dimension as t. If model is global, this needs to be a dictionary, of the same length as input t.

Params return_err:
(optional, boolean)

If True, this returns the n-sigma error on the evaluated model.

Params alpha: (optional, double)

Credibility band for return_err. Default is 1-sigma (68%).

Params return_components:
(optional, boolean)

If True, components of the model are returned

Finally, the juliet.load object also contains a dictionary (juliet.load.lc_options for lightcurves and juliet.load.rv_options for radial-velocities) which holds, if a gaussian-process is being used to model the noise, a juliet.gaussian_process object. This class handles everything related to the gaussian-processes, from model and parameter names/values, to log-likelihood evaluations. This class is defined below:

class juliet.gaussian_process(data, model_type, instrument, george_hodlr=True, matern_eps=0.01)

Given a juliet data object (created via juliet.load), a model type (i.e., is this a GP for a RV or lightcurve dataset) and an instrument name, this object generates a Gaussian Process (GP) object to use within the juliet library. Example usage:

>>> GPmodel = juliet.gaussian_process(data, model_type = 'lc', instrument = 'TESS')

Parameters: model_type – (string) A string defining the type of data the GP will be modelling. Can be either lc (for photometry) or rv (for radial-velocities). instrument – (string) A string indicating the name of the instrument the GP is being applied to. This string simplifies cross-talk with juliet’s posteriors dictionary. george_hodlr – (optional, boolean) If True, this uses George’s HODLR solver (faster).