POSEIDON.retrieval
==================

.. py:module:: POSEIDON.retrieval

.. autoapi-nested-parse::

   Functions related to atmospheric retrieval.



Attributes
----------

.. autoapisummary::

   POSEIDON.retrieval.comm
   POSEIDON.retrieval.rank
   POSEIDON.retrieval.allowed_simplex
   POSEIDON.retrieval.allowed_simplex_surfaces


Functions
---------

.. autoapisummary::

   POSEIDON.retrieval.run_retrieval
   POSEIDON.retrieval.forward_model
   POSEIDON.retrieval.CLR_Prior
   POSEIDON.retrieval.PyMultiNest_retrieval
   POSEIDON.retrieval.retrieved_samples
   POSEIDON.retrieval.get_retrieved_atmosphere
   POSEIDON.retrieval.Z_to_sigma
   POSEIDON.retrieval.Bayesian_model_comparison


Module Contents
---------------

.. py:data:: comm

.. py:data:: rank

.. py:data:: allowed_simplex
   :value: 1


.. py:data:: allowed_simplex_surfaces
   :value: 1


.. py:function:: run_retrieval(planet, star, model, opac, data, priors, wl, P, P_ref=None, R_p_ref=None, P_param_set=0.01, R=None, retrieval_name=None, He_fraction=0.17, N_slice_EM=2, N_slice_DN=4, constant_gravity=False, spectrum_type='transmission', y_p=np.array([0.0]), stellar_T_step=20, stellar_log_g_step=0.1, N_live=400, ev_tol=0.5, sampling_algorithm='MultiNest', resume=False, verbose=True, sampling_target='parameter', chem_grid='fastchem', N_output_samples=1000, save_ymodel=False)

   ADD DOCSTRING (will hopefully be done before the heat death of the Universe)


.. py:function:: forward_model(param_vector, planet, star, model, opac, data, wl, P, P_ref_set, R_p_ref_set, P_param_set, He_fraction, N_slice_EM, N_slice_DN, spectrum_type, T_phot_grid, T_het_grid, log_g_phot_grid, log_g_het_grid, I_phot_grid, I_het_grid, y_p, F_s_obs, constant_gravity, chemistry_grid)

   ADD DOCSTRING


.. py:function:: CLR_Prior(chem_params_drawn, limit=-12.0)

   Implements the centred-log-ratio (CLR) prior for chemical mixing ratios.

   CLR[i] here is the centred log-ratio transform of the mixing ratio, X[i]



.. py:function:: PyMultiNest_retrieval(planet, star, model, opac, data, prior_types, prior_ranges, spectrum_type, wl, P, P_ref_set, R_p_ref_set, P_param_set, He_fraction, N_slice_EM, N_slice_DN, N_params, T_phot_grid, T_het_grid, log_g_phot_grid, log_g_het_grid, I_phot_grid, I_het_grid, y_p, F_s_obs, constant_gravity, chemistry_grid, **kwargs)

   Main function for conducting atmospheric retrievals with PyMultiNest.



.. py:function:: retrieved_samples(planet, star, model, opac, data, retrieval_name, wl, P, P_ref_set, R_p_ref_set, P_param_set, He_fraction, N_slice_EM, N_slice_DN, spectrum_type, T_phot_grid, T_het_grid, log_g_phot_grid, log_g_het_grid, I_phot_grid, I_het_grid, y_p, F_s_obs, constant_gravity, chemistry_grid, N_output_samples, comm=None)

   ADD DOCSTRING


.. py:function:: get_retrieved_atmosphere(planet, model, P, P_ref_set=10, R_p_ref_set=None, median=False, best_fit=True, P_param_set=0.01, He_fraction=0.17, N_slice_EM=2, N_slice_DN=4, constant_gravity=False, chemistry_grid=None, specific_param_values=[], verbose=False)

   Creates the atmosphere dictionary for the median or best fit spectrum of a retrieval.

   :param planet: Collection of planetary properties used POSEIDON.
   :type planet: dict
   :param model: A specific description of a given POSEIDON model.
   :type model: dict
   :param P: Model pressure grid (bar).
   :type P: np.array of float
   :param P_ref: Reference pressure (bar).
   :type P_ref: float
   :param R_p_ref: Planet radius corresponding to reference pressure (m).
   :type R_p_ref: float
   :param median: Option to create an atmosphere from the median retrieved spectrum.
   :type median: optional, bool
   :param best_fit:
                    Option to create an atmosphere from the best fit retrieved spectrum
                        He_fraction (float):
                    Assumed H2/He ratio (0.17 default corresponds to the solar ratio).
   :type best_fit: optional, bool
   :param N_slice_EM: Number of azimuthal slices in the evening-morning transition region.
   :type N_slice_EM: even int
   :param N_slice_DN: Number of zenith slices in the day-night transition region.
   :type N_slice_DN: even int
   :param constant_gravity: If True, disable inverse square law gravity (only for testing).
   :type constant_gravity: bool
   :param chemistry_grid: For models with a pre-computed chemistry grid only, this dictionary
                          is produced in chemistry.py.
   :type chemistry_grid: dict
   :param specific_param_values: If a specific parameter combination is provided, this will be used
                                 instead of the median or best fit parameters.
   :type specific_param_values: list

   :returns:         Collection of atmospheric properties required to compute the
                     resultant spectrum of the planet.
   :rtype: atmosphere (dict)


.. py:function:: Z_to_sigma(ln_Z1, ln_Z2)

   Convert the log-evidences of two models to a sigma confidence level.



.. py:function:: Bayesian_model_comparison(planet_name, model_1, model_2, ln_Z_format='{:.2f}', B_format='{:.2e}', ln_B_format='{:.2f}', sigma_format='{:.1f}')

   Conduct Bayesian model comparison between the outputs of two retrievals.
   This function outputs the Bayes factor and equivalent sigma significance
   comparing the two models.