AbstractIntegerDistribution (Apache Commons Math 3.6.1 API)

org.apache.commons.math3.distribution

## Class AbstractIntegerDistribution

- java.lang.Object
- - org.apache.commons.math3.distribution.AbstractIntegerDistribution

- All Implemented Interfaces:
    Serializable, IntegerDistribution
  Direct Known Subclasses:
    BinomialDistribution, EnumeratedIntegerDistribution, GeometricDistribution, HypergeometricDistribution, PascalDistribution, PoissonDistribution, UniformIntegerDistribution, ZipfDistribution

      public abstract class AbstractIntegerDistribution
      extends Object
      implements IntegerDistribution, Serializable

  Base class for integer-valued discrete distributions. Default implementations are provided for some of the methods that do not vary from distribution to distribution.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected RandomGenerator` | `random` RNG instance used to generate samples from the distribution.
    `protected RandomDataImpl` | `randomData` Deprecated. As of 3.1, to be removed in 4.0. Please use the `random` instance variable instead.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractIntegerDistribution()` Deprecated. As of 3.1, to be removed in 4.0. Please use `AbstractIntegerDistribution(RandomGenerator)` instead.
    `protected` | `AbstractIntegerDistribution(RandomGenerator rng)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `cumulativeProbability(int x0, int x1)` For a random variable `X` whose values are distributed according to this distribution, this method returns `P(x0 < X <= x1)`.
    `int` | `inverseCumulativeProbability(double p)` Computes the quantile function of this distribution.
    `double` | `logProbability(int x)` For a random variable `X` whose values are distributed according to this distribution, this method returns `log(P(X = x))`, where `log` is the natural logarithm.
    `void` | `reseedRandomGenerator(long seed)` Reseed the random generator used to generate samples.
    `int` | `sample()` Generate a random value sampled from this distribution.
    `int[]` | `sample(int sampleSize)` Generate a random sample from the distribution.
    `protected int` | `solveInverseCumulativeProbability(double p, int lower, int upper)` This is a utility function used by `inverseCumulativeProbability(double)`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.apache.commons.math3.distribution.IntegerDistribution

      `cumulativeProbability, getNumericalMean, getNumericalVariance, getSupportLowerBound, getSupportUpperBound, isSupportConnected, probability`

- - ### Field Detail

    - #### randomData

          @Deprecated
          protected final RandomDataImpl randomData

      Deprecated. As of 3.1, to be removed in 4.0. Please use the `random` instance variable instead.
      RandomData instance used to generate samples from the distribution.

    - #### random

          protected final RandomGenerator random

      RNG instance used to generate samples from the distribution.
      Since:
        3.1

  - ### Constructor Detail

    - #### AbstractIntegerDistribution

          @Deprecated
          protected AbstractIntegerDistribution()

      Deprecated. As of 3.1, to be removed in 4.0. Please use `AbstractIntegerDistribution(RandomGenerator)` instead.

    - #### AbstractIntegerDistribution

          protected AbstractIntegerDistribution(RandomGenerator rng)

      Parameters:
        `rng` - Random number generator.
      Since:
        3.1

  - ### Method Detail

    - #### cumulativeProbability

          public double cumulativeProbability(int x0,
                                     int x1)
                                       throws NumberIsTooLargeException

      For a random variable `X` whose values are distributed according to this distribution, this method returns `P(x0 < X <= x1)`. The default implementation uses the identity

      `P(x0 < X <= x1) = P(X <= x1) - P(X <= x0)`

      Specified by:
        `cumulativeProbability` in interface `IntegerDistribution`
      Parameters:
        `x0` - the exclusive lower bound
        `x1` - the inclusive upper bound
      Returns:
        the probability that a random variable with this distribution will take a value between `x0` and `x1`, excluding the lower and including the upper endpoint
      Throws:
        `NumberIsTooLargeException` - if `x0 > x1`

    - #### inverseCumulativeProbability

          public int inverseCumulativeProbability(double p)
                                           throws OutOfRangeException

      Computes the quantile function of this distribution. For a random variable `X` distributed according to this distribution, the returned value is
      - `inf{x in Z | P(X<=x) >= p}` for `0 < p <= 1`,
      - `inf{x in Z | P(X<=x) > 0}` for `p = 0`.
      If the result exceeds the range of the data type `int`, then `Integer.MIN_VALUE` or `Integer.MAX_VALUE` is returned. The default implementation returns
      - `IntegerDistribution.getSupportLowerBound()` for `p = 0`,
      - `IntegerDistribution.getSupportUpperBound()` for `p = 1`, and
      - `solveInverseCumulativeProbability(double, int, int)` for `0 < p < 1`.
      Specified by:
        `inverseCumulativeProbability` in interface `IntegerDistribution`
      Parameters:
        `p` - the cumulative probability
      Returns:
        the smallest `p`-quantile of this distribution (largest 0-quantile for `p = 0`)
      Throws:
        `OutOfRangeException` - if `p < 0` or `p > 1`

    - #### solveInverseCumulativeProbability

          protected int solveInverseCumulativeProbability(double p,
                                              int lower,
                                              int upper)

      This is a utility function used by `inverseCumulativeProbability(double)`. It assumes `0 < p < 1` and that the inverse cumulative probability lies in the bracket `(lower, upper]`. The implementation does simple bisection to find the smallest `p`-quantile `inf{x in Z | P(X<=x) >= p}`.
      Parameters:
        `p` - the cumulative probability
        `lower` - a value satisfying `cumulativeProbability(lower) < p`
        `upper` - a value satisfying `p <= cumulativeProbability(upper)`
      Returns:
        the smallest `p`-quantile of this distribution

    - #### reseedRandomGenerator

          public void reseedRandomGenerator(long seed)

      Reseed the random generator used to generate samples.
      Specified by:
        `reseedRandomGenerator` in interface `IntegerDistribution`
      Parameters:
        `seed` - the new seed

    - #### sample

          public int sample()

      Generate a random value sampled from this distribution. The default implementation uses the inversion method.
      Specified by:
        `sample` in interface `IntegerDistribution`
      Returns:
        a random value

    - #### sample

          public int[] sample(int sampleSize)

      Generate a random sample from the distribution. The default implementation generates the sample by calling `sample()` in a loop.
      Specified by:
        `sample` in interface `IntegerDistribution`
      Parameters:
        `sampleSize` - the number of random values to generate
      Returns:
        an array representing the random sample

    - #### logProbability

          public double logProbability(int x)

      For a random variable `X` whose values are distributed according to this distribution, this method returns `log(P(X = x))`, where `log` is the natural logarithm. In other words, this method represents the logarithm of the probability mass function (PMF) for the distribution. Note that due to the floating point precision and under/overflow issues, this method will for some distributions be more precise and faster than computing the logarithm of `IntegerDistribution.probability(int)`.

      The default implementation simply computes the logarithm of `probability(x)`.

      Parameters:
        `x` - the point at which the PMF is evaluated
      Returns:
        the logarithm of the value of the probability mass function at `x`

Copyright © 2003–2016 The Apache Software Foundation. All rights reserved.