TauREx Nest_Out.pickle


The nest_out.pickle file is generated whenever a retrieval is run. It contains the following:

  • all state parameters,
  • all user defined input data (e.g. the observed spectrum),
  • the best fit model/s (inc. confidence bounds),
  • the temperature-pressure profile (inc. confidence bounds),
  • vertical abundance profiles,
  • transmissivity / emissivity as function of pressure,
  • the best fit model/s relative opacity contributions,
  • the full MultiNest trace,
  • all MultiNest statistics,
  • the full PolyChord trace (if run),
  • the full PolyChord statistics (if run),

How to load it for inspection

To open the pickle file you will need python installed in your computer and the packages pickle and numpy.

When in a python terminal, the command to load a pickle file is:

database = pickle.load(open(database_file.pickle))

to list the content of a dictionary:


The Dictionary layout

Here we describe the individual arrays of the database and nested sub-dictionaries.

Top Level

keyword Description Type
global_logE global log-evidence as returned by MultiNest float
fit_params_texlabels fitted parameters, formatted to be rendered in TeX by python plotting routines list
NEST_stats MultiNest statistics Dictionary
fit_params_bounds upper and lower bounds of fitted parameters tuples
obs_spectrum input spectrum array
solutions retrieved solution(s) list of dictionaries
params all input parameters used to run TauREx dictionary
type type of retrieval. Either ‘transmission’ or ‘emission’ ascii
fit_params_names fitted parameters list of ascii


NEST_stats is generated by PyMultiNest and contains a full statistical summary of the retrieval. Some values are repeated in database[‘solutions’].

keyword Description Type
global evidence global log-evidence of final retrieval float
global evidence error global log-evidence error float
nested sampling global log-evidence global log-evidence provided by the nested sampling. This differs from ‘global evidence’ if importance sampling is switched on. float
nested sampling global evidence error nested sampling global log-evidence error float
marginals marginals for each retrieved parameter provided by PyMultiNest. list
modes sub-dictionary summarising statistics for each retrieved solution list of dictionaries
keyword Description Type
index index of solution int
local log-evidence local log-evidence of solution float
local log-evidence error local log-evidence error float
strictly local log-evidence strictly local logE float
strictly local log-evidence error strictly local logE error float
maximum maximum likelihood values of fitted parameters list
maximum a posteriori maximum a posteriori values for fitted parameters list
sigma 1 sigma errors on fitted parameters list
mean mean values of fitted parameters list
keyword Description Type  
marginals marginals for parameter index PIDX list  
marginals[PIDX] 1sigma 1 sigma asymmetric error bounds array
marginals[PIDX] 2sigma 2 sigma asymmetric error bounds array
marginals[PIDX] 3sigma 3 sigma asymmetric error bounds array
marginals[PIDX] 5sigma 5 sigma asymmetric error bounds array
marginals[PIDX] median solution median array
marginals[PIDX] q01% 1 percent quantile array
marginals[PIDX] q10% 10 percent quantile array
marginals[PIDX] q25% 25 percent quantile array
marginals[PIDX] q75% 75 percent quantile array
marginals[PIDX] q90% 90 percent quantile array
marginals[PIDX] q99% 99 percent quantile array
marginals[PIDX] sigma 1 sigma symmetric error bounds array


The solutions sub-dictionary contains all retrieval results for each retrieved solution (SIDX).

keyword Description Type
local_logE local log-evidence of the solution float
type type of sampling used: ‘nest’ (multinest), ‘mcmc’ or ‘downhill’ (optimal estimation) ascii
fit_params sub-dictionary of fitting statistics for each free parameter list of dictionaries
tp_profile temperature – pressure profile of atmosphere. Format: pressure (Pa), temperature (K), sigma(temperature) (K) array
obs_spectrum best fitting forward model binned to the resolution of the input spectrum. Format: wavelength (microns), (Rp/Rs)2 or Fp/Fs array
opacity_contrib sub-dictionary of forward models containing individual opacities only, e.g.: [‘CO’] contains the best fitting forward model but with all other contributions but CO switched off. dictionary
active_mixratio_profile array of mixing ratios of spectroscopically active gases as function of atmospheric pressure. These profiles are constant for ‘free’ retrievals but vary for chemically consistent retrievals. The pressure grid is identical to [‘tp_profile’] array
inactive_mixratio_profile same as [‘active_mixratio_profile’] but for spectroscopic inactive species such as H2, He, N2 array
weights statistical weights from the nested_sampling. To be multiplied with tracedata to obtain the correct normalised posterior probabilities array
tracedata parameter traces to be weighted with [‘weights’]. array
contrib_func 2D array of atmospheric opacity contribution as function of wavelength (row) and pressure (column). array
fit_spectrum_xsecres best fitting forward model at the native resolution of the used cross sections or ktables. Format: wavelength (microns), signal, sigma(signal). Here signal is (Rp/Rs)2 or Fp/Fs depending on transmission or emission. array

For individual fitted paramters, e.g. H2O:

keyword Description Type
nest_map maximum a posteriori value float
nest_mean mean posterior value float
nest_sigma 1 sigma error float
sigma_m q50% - q16% (lower error bound based on quantiles) array
sigma_p q84% - q50% (upper error bound based on quantiles) array
trace nested sampling trace of parameter (unweighted) array
value q50% mid quantile float

For individual contribution functions, e.g. CO:

keyword Description Type
CO data format: wavelength (microns), (Rp/Rs)2 or Fp/Fs array

Create Spectrum Instance

When running the forward model only mode create_spectrum.py with the additional flag --save_instance, a similar pickle file is generated in the chosen output folder, SPECTRUM_INSTANCE_out.pickle. This one will contain all elements that went into the creation of the forward model but obviously does not contain fitted parameters.

python create_spectrum.py -p [PARAMETER FILE] --save_instance

The following additional flags can be set:

--instance_filename   #changes the instance name
--transmittance       #saves transmittance for transmission to instance object
--contrib_func        #saves the contribution function for emission to instance object

For more information

python create_spectrum.py --help