TauREx Nest_Out.pickle
Overview
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:
database.keys()
The Dictionary layout
Here we describe the individual arrays of the database and nested sub-dictionaries.
Top Level
database.keys()
| 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
NEST_stats is generated by PyMultiNest and contains a full statistical summary of the retrieval. Some values are repeated in database[‘solutions’].
database['NEST_stats'].keys()
| 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 |
database['NEST_stats']['modes'].keys()
| 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 |
database['NEST_stats']['marginals'].keys()
| 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 |
Solutions
The solutions sub-dictionary contains all retrieval results for each retrieved solution (SIDX).
database['solutions'][SIDX].keys()
| 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:
database['solutions'][SIDX]['log_H2O'].keys()
| 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:
database['solutions'][SIDX]['opacity_contrib'].keys()
| 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