Package 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
Description
`protected final RandomGenerator`
`random`
RNG instance used to generate samples from the distribution.
`protected final RandomDataImpl`
`randomData`
Deprecated.
As of 3.1, to be removed in 4.0.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`AbstractIntegerDistribution()`
Deprecated.
As of 3.1, to be removed in 4.0.
`protected`
`AbstractIntegerDistribution(RandomGenerator rng)`

## Method Summary

Modifier and Type
Method
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 Details

### 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 Details

### 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 Details

### 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(Xinvalid input: '<'=x) >= p}` for `0 < p <= 1`,
- `inf{x in Z | P(Xinvalid input: '<'=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(Xinvalid input: '<'=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`