.. _physics-distributionFunctionDiscrete1D:

One-dimensional Discrete Distribution Functions
===============================================

Class providing discrete probability distribution functions of a single integer variable---the probability mass function :math:`p(x)` (and its logarithm), the cumulative distribution function :math:`P(x) = \sum_{x' \le x} p(x')`, and the quantile function :math:`x(P)`. These distributions model count data such as the number of galaxies in a halo or the number of star formation events, and are used for drawing random variates and computing Poisson or binomial likelihoods in galaxy statistics and N-body halo occupation analyses.

**Default implementation:** ``distributionFunctionDiscrete1DBinomial``

Methods
-------

``mass`` → ``double precision``
   Return the probability mass function :math:`p(x)`, giving the probability that the discrete random variable takes the integer value ``x``.

   * ``integer, intent(in ) :: x``

``massLogarithmic`` → ``double precision``
   Return the natural logarithm of the probability mass function :math:`\ln p(x)` evaluated at integer ``x``, which is more numerically stable for extremely small probabilities than computing :math:`p(x)` directly.

   * ``integer, intent(in ) :: x``

``cumulative`` → ``double precision``
   Return the cumulative distribution function :math:`P(x) = \sum_{x' \le x} p(x')`, giving the probability that the discrete random variable takes a value less than or equal to integer ``x``.

   * ``integer, intent(in ) :: x``

   * ``integer, intent( out), optional :: status``

``cumulativeComplementary`` → ``double precision``
   Return the complementary cumulative probability at ``x``.

   * ``integer, intent(in ) :: x``

   * ``integer, intent( out), optional :: status``

``inverse`` → ``integer``
   Return the value of the independent variable corresponding to cumulative probability ``p``.

   * ``double precision, intent(in ) :: p``

``sample`` → ``integer``
   Return a random integer deviate drawn from this discrete probability distribution, using the inverse CDF method by default (drawing a uniform random number and applying the quantile function).

   * ``class(randomNumberGeneratorClass), intent(inout), optional :: randomNumberGenerator_``

``minimum`` → ``integer``
   Returns the minimum possible integer value in the support of this discrete distribution, i.e., the smallest integer :math:`x` for which the probability mass is non-zero.

``maximum`` → ``integer``
   Returns the maximum possible integer value in the support of this discrete distribution, i.e., the largest integer :math:`x` for which the probability mass is non-zero.

.. _physics-distributionFunctionDiscrete1DBinomial:

``distributionFunctionDiscrete1DBinomial``
------------------------------------------

A 1D binomial discrete distribution function class, modeling the number of successes :math:`k` in :math:`n` independent Bernoulli trials each with success probability :math:`p`, with probability mass function :math:`P(k) = \binom{n}{k} p^k (1-p)^{n-k}`.

**(Default implementation)**

**Parameters**

* ``[probabilitySuccess]`` — The probability :math:`p \in [0,1]` of success on a single Bernoulli trial, which determines the mean (:math:`np`) and variance (:math:`np(1-p)`) of the resulting binomial distribution.
* ``[countTrials]`` — The total number of independent Bernoulli trials :math:`n`, which sets the range of the distribution from 0 to :math:`n` and controls the overall scale of the mean and variance.

.. _physics-distributionFunctionDiscrete1DNegativeBinomial:

``distributionFunctionDiscrete1DNegativeBinomial``
--------------------------------------------------

A negative binomial 1D discrete distribution function class, modeling the number of successes :math:`k` observed before a fixed number of failures :math:`r` in a sequence of independent Bernoulli trials each with success probability :math:`p`, with probability mass function :math:`P(k) = \binom{k+r-1}{k} p^r (1-p)^k`. Note that the cumulative and inverse CDF methods are not currently implemented; only the probability mass function and its logarithm are available.

**Parameters**

* ``[probabilitySuccess]`` — The probability :math:`p \in (0,1]` of success on a single Bernoulli trial; the distribution models the number of successes before :math:`r` failures occur, with mean :math:`pr/(1-p)`.
* ``[countFailures]`` — The target number of failures :math:`r` before the experiment stops; the distribution gives the number of successes :math:`k` observed before the :math:`r`-th failure, with variance :math:`pr/(1-p)^2`.

.. _physics-distributionFunctionDiscrete1DPoisson:

``distributionFunctionDiscrete1DPoisson``
-----------------------------------------

A Poisson 1D discrete distribution function class.

**Parameters**

* ``[mean]`` — The mean of the distribution.