Probability distributions
-------------------------

Probability distributions are classes.
Their parameters do not normally change.
A prototype for a probability distribution looks like

.. class:: ProbabilityDistribution

    .. method:: density (x)
    
        (For continuous distributions.)

        :return: the value of the probability density function at the point ``x``\ .
    
    .. method:: mass (x)
    
        (For discrete distributions.)

        :return: the value of the probability mass function at the point ``x``\ .
    
    
    .. method:: sampler()
    
        :return: a sampler for this distribution.
            See :ref:`samplers`.

Conditional distributions return a distribution when the values for the
variables behind the bar are given.

.. class:: ConditionalDistribution
    
    .. method:: given(y)
        
        :return: the distribution given the parameters.

Log-float
^^^^^^^^^

..  autoclass:: probability.log_float.LogFloat
    :members:
    :undoc-members:

..  autofunction:: probability.log_float.log
..  autofunction:: probability.log_float.makeStandardNumeric

Distributions
^^^^^^^^^^^^^

The following are implementations of probability distributions.

..  autoclass:: probability.uniform.Uniform
    :members:
    :undoc-members:


..  autoclass:: probability.categorical.Categorical
    :members: deltas, mass, unitWeightSamples
    
    .. method:: sampler(uniformUnitSampler = sampler.UniformUnitSampler())


..  autoclass:: probability.gaussian.Gaussian
    :members: density, unnormalisedDensity, getCovariance, getPrecision

    .. method:: sampler(uniformUnitSampler = sampler.UniformUnitSampler())

..  autofunction:: probability.gaussian.joinGaussians

..  autofunction:: probability.gaussian.splitGaussian

..  autofunction:: probability.gaussian.factoriseGaussian

..  autofunction:: probability.gaussian.factoriseGaussianCompletely

..  autoclass:: probability.gaussian.GaussianAccumulator
    :members:
    :undoc-members:



Mixtures
""""""""

..  autoclass:: probability.mixture.Mixture
    :members: density, mass, factorise, unnormalisedComponents

    .. method:: sampler(uniformUnitSampler = sampler.UniformUnitSampler())

Training mixtures normally uses expectation–maximisation.

..  autofunction:: probability.mix_up.trainMixture

..  autofunction:: probability.mix_up.trainGaussianMixtureFromScratch


.. _samplers:

Samplers
^^^^^^^^

Samplers are unary functions (or classes with a ``__call__`` method) that return a new sample from a distribution each time.
:class:`probability.sampler.UniformUnitSampler` is the base sampler that other samplers wrap.

Making the sampler a separate object allows

#. different base samplers to be specified;

#. computations that speed up sampling to be done when the sampler is constructed
    (for example, Cholesky decomposition for a Gaussian; computing the cdf for a discrete distribution).

..  autoclass:: probability.sampler.UniformUnitSampler
    :members:
    :undoc-members:

..  autoclass:: probability.sampler.AlwaysSampler
    :members:
    :undoc-members:

..  autoclass:: probability.sampler.IncrementalSystematicSampler(unbiased=False, uniformUnitSample=UniformUnitSampler())

..  autoclass:: probability.sampler.UnitGaussianSampler(uniformUnitSample=UniformUnitSampler())