%feature("docstring") OT::MCMC
"Monte-Carlo Markov Chain.

Available constructor:
    MCMC(*prior, conditional, observations, initialState*)

    MCMC(*prior, conditional, model, parameters, observations, initialState*)

Parameters
----------
prior : :class:`~openturns.Distribution`
    Prior distribution of the parameters of the underlying Bayesian statistical
    model.
conditional : :class:`~openturns.Distribution`
    Required distribution to define the likelihood of the underlying Bayesian
    statistical model.
model : :class:`~openturns.Function`
    Function required to define the likelihood.
observations : 2-d sequence of float
    Observations required to define the likelihood.
initialState : sequence of float
    Initial state of the Monte-Carlo Markov chain on which the Sampler is
    based.
parameters : 2-d sequence of float
    Parameters of the model to be fixed.

Notes
-----
MCMC provides a implementation of the concept of sampler, using a Monte-Carlo
Markov Chain (MCMC) algorithm starting from *initialState*. More precisely,
let :math:`t(.)` be the PDF of its target distribution and :math:`d_{\theta}`
its dimension, :math:`\pi(.)` be the PDF of the *prior* distribution,
:math:`f(.|\vect{w})` be the PDF of the *conditional* distribution
when its parameters are set to :math:`\vect{w}`, :math:`d_w` be the number of
scalar parameters of *conditional* distribution (which corresponds to the
dimension of the above :math:`\vect{w}`), :math:`g(.)` be the function
corresponding to model and :math:`(\vect{y}^1, \dots, \vect{y}^n)` be the
sample *observations* (of size :math:`n`):

In the first usage, it creates a sampler based on a MCMC algorithm whose target
distribution is defined by:

.. _PDF_target_formula:

.. math::

    t(\vect{\theta})
    \quad \propto \quad
    \underbrace{~\pi(\vect{\theta})~}_{\mbox{prior}} \quad
    \underbrace{~\prod_{i=1}^n f(\vect{y}^i|\vect{\theta})~}_{\mbox{likelihood}}


In the first usage, it creates a sampler based on a MCMC algorithm whose target
distribution is defined by:

.. _second_PDF_target_formula:

.. math::

    t(\vect{\theta})
    \quad \propto \quad
    \underbrace{~\pi(\vect{\theta})~}_{\mbox{prior}} \quad
    \underbrace{~\prod_{i=1}^n f(\vect{y}^i|g^i(\vect{\theta}))~}_{\mbox{likelihood}}

where the :math:`g^i: \Rset^{d_{\theta}} \rightarrow\Rset^{d_w}`
(:math:`1\leq{}i\leq{}n`) are such that:

.. math::

    \begin{array}{rcl}
        g:\Rset^{d_\theta} & \longrightarrow & \Rset^{n\,d_w}\\
        \vect{\theta} & \longmapsto &
        g(\vect{\theta}) = \Tr{(\Tr{g^1(\vect{\theta})}, \cdots, \Tr{g^n(\vect{\theta})})}
        \end{array}

In fact, the first usage is a particular case of the second.


The MCMC method implemented in OpenTURNS is the Random Walk Metropolis-Hastings
algorithm. A sample can be generated only through the MCMC's derived class:
:class:`~openturns.RandomWalkMetropolisHastings`."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::computeLogLikelihood
"Compute the logarithm of the likelihood w.r.t. observations.

Parameters
----------
currentState : sequence of float
    Current state.

Returns
-------
logLikelihood : float
    Logarithm of the likelihood w.r.t. observations
    :math:`(\vect{y}^1, \dots, \vect{y}^n)`."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getBurnIn
"Get the length of the burn-in period.

Returns
-------
lenght : int
    Length of the burn-in period, that is the number of first iterates of the
    MCMC chain which will be thrown away when generating the sample."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::setBurnIn
"Set the length of the burn-in period.

Parameters
----------
lenght : int
    Length of the burn-in period, that is the number of first iterates of the
    MCMC chain which will be thrown away when generating the sample."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getConditional
"Get the *conditional* distribution.

Returns
-------
conditional : :class:`~openturns.Distribution`
    Distribution taken into account in the definition of the likelihood, whose
    PDF with parameters :math:`\vect{w}` corresponds to :math:`f(.|\vect{w})`
    in the equations of the
    :ref:`target distribution's PDF <PDF_target_formula>`."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getModel
"Get the model.

Returns
-------
model : :class:`~openturns.Function`
    Model take into account in the definition of the likelihood, which
    corresponds to :math:`g`, that is the functions :math:`g^i`
    (:math:`1\leq i \leq n`) in the equation of the
    :ref:`target distribution's PDF <second_PDF_target_formula>`."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getObservations
"Get the observations.

Returns
-------
observations : :class:`~openturns.Sample`
    Sample taken into account in the definition of the likelihood, which
    corresponds to the :math:`n`-tuple of the :math:`\vect{y}^i`
    (:math:`1\leq i \leq n`) in equations of the
    :ref:`target distribution's PDF <PDF_target_formula>`."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::setObservations
"Set the observations.

Parameters
----------
observations : 2-d sequence of float
    Sample taken into account in the definition of the likelihood, which
    corresponds to the :math:`n`-tuple of the :math:`\vect{y}^i`
    (:math:`1\leq i \leq n`) in the equations of the
    :ref:`target distribution's PDF <PDF_target_formula>`."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getParameters
"Get the parameters.

Returns
-------
parameters : :class:`~openturns.Point`
    Fixed parameters of the model :math:`g` required to define the likelihood."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::setParameters
"Set the parameters.

Parameters
----------
parameters : sequence of float
    Fixed parameters of the model :math:`g` required to define the likelihood."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getPrior
"Get the *prior* distribution.

Returns
-------
prior : :class:`~openturns.Distribution`
    The prior distribution of the parameter of the underlying Bayesian
    statistical model, whose PDF corresponds to :math:`\pi` in the equations of
    the :ref:`target distribution's PDF <PDF_target_formula>`."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::setPrior
"Set the *prior* distribution.

Parameters
----------
prior : :class:`~openturns.Distribution`
    The prior distribution of the parameter of the underlying Bayesian
    statistical model, whose PDF corresponds to :math:`\pi` in the equations of
    the :ref:`target distribution's PDF <PDF_target_formula>`."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getThinning
"Get the thinning parameter.

Returns
-------
thinning : int
    Thinning parameter: storing only every :math:`k^{th}` point after the
    burn-in period.

Notes
-----
When generating a sample of size :math:`q`, the number of MCMC iterations
performed is :math:`l+1+(q-1)k` where :math:`l` is the burn-in period length
and :math:`k` the thinning parameter."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::setThinning
"Set the thinning parameter.

Parameters
----------
thinning : int, :math:`k \geq 0`
    Thinning parameter: storing only every :math:`k^{th}` point after the
    burn-in period.

Notes
-----
When generating a sample of size :math:`q`, the number of MCMC iterations
performed is :math:`l+1+(q-1)k` where :math:`l` is the burn-in period length
and :math:`k` the thinning parameter."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getHistory
"Get the history storage.

Returns
-------
history : :class:`~openturns.HistoryStrategy`
    Used to record the chain."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::setHistory
"Set the history storage.

Parameters
----------
history : :class:`~openturns.HistoryStrategy`
    Used to record the chain."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getNonRejectedComponents
"Get the components to be always accepted.

Returns
-------
nonRejectedComponents : :class:`~openturns.Indices`
    The indices of the components that are not tuned, and sampled according to
    the prior distribution in order to take into account the intrinsic
    uncertainty, as opposed to the epistemic uncertainty corresponding to the
    tuned variables."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::setNonRejectedComponents
"Set the components to be always accepted.

Parameters
----------
nonRejectedComponents : sequence of int 
    The indices of the components that are not tuned, and sampled according to
    the prior distribution in order to take into account the intrinsic
    uncertainty, as opposed to the epistemic uncertainty corresponding to the
    tuned variables."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::getVerbose
"Tell whether the verbose mode is activated or not.

Returns
-------
isVerbose : bool
    The verbose mode is activated if it is *True*, desactivated otherwise."

// ---------------------------------------------------------------------

%feature("docstring") OT::MCMC::setVerbose
"Set the verbose mode.

Parameters
----------
isVerbose : bool
    The verbose mode is activated if it is *True*, desactivated otherwise."
