Class AbstractDiscreteDistribution

    • Field Detail

      • NO_MEDIAN

        private static final long NO_MEDIAN
        Marker value for no median. This is a long to be outside the value of any possible int valued median.
        See Also:
        Constant Field Values
      • median

        private long median
        Cached value of the median.
    • Constructor Detail

      • AbstractDiscreteDistribution

        AbstractDiscreteDistribution()
    • Method Detail

      • probability

        public double probability​(int x0,
                                  int x1)
        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)

        Special cases:

        • returns 0.0 if x0 == x1;
        • returns probability(x1) if x0 + 1 == x1;
        Specified by:
        probability in interface DiscreteDistribution
        Parameters:
        x0 - Lower bound (exclusive).
        x1 - Upper bound (inclusive).
        Returns:
        the probability that a random variable with this distribution takes a value between x0 and x1, excluding the lower and including the upper endpoint.
      • inverseCumulativeProbability

        public int inverseCumulativeProbability​(double p)
        Computes the quantile function of this distribution. For a random variable X distributed according to this distribution, the returned value is:

        \[ x = \begin{cases} \inf \{ x \in \mathbb Z : P(X \le x) \ge p\} & \text{for } 0 \lt p \le 1 \\ \inf \{ x \in \mathbb Z : P(X \le x) \gt 0 \} & \text{for } p = 0 \end{cases} \]

        If the result exceeds the range of the data type int, then Integer.MIN_VALUE or Integer.MAX_VALUE is returned. In this case the result of cumulativeProbability(x) called using the returned p-quantile may not compute the original p.

        The default implementation returns:

        Specified by:
        inverseCumulativeProbability in interface DiscreteDistribution
        Parameters:
        p - Cumulative probability.
        Returns:
        the smallest p-quantile of this distribution (largest 0-quantile for p = 0).
        Throws:
        java.lang.IllegalArgumentException - if p < 0 or p > 1
      • inverseSurvivalProbability

        public int inverseSurvivalProbability​(double p)
        Computes the inverse survival probability function of this distribution. For a random variable X distributed according to this distribution, the returned value is:

        \[ x = \begin{cases} \inf \{ x \in \mathbb Z : P(X \gt x) \le p\} & \text{for } 0 \le p \lt 1 \\ \inf \{ x \in \mathbb Z : P(X \gt x) \lt 1 \} & \text{for } p = 1 \end{cases} \]

        If the result exceeds the range of the data type int, then Integer.MIN_VALUE or Integer.MAX_VALUE is returned. In this case the result of survivalProbability(x) called using the returned (1-p)-quantile may not compute the original p.

        By default, this is defined as inverseCumulativeProbability(1 - p), but the specific implementation may be more accurate.

        The default implementation returns:

        Specified by:
        inverseSurvivalProbability in interface DiscreteDistribution
        Parameters:
        p - Cumulative probability.
        Returns:
        the smallest (1-p)-quantile of this distribution (largest 0-quantile for p = 1).
        Throws:
        java.lang.IllegalArgumentException - if p < 0 or p > 1
      • inverseProbability

        private int inverseProbability​(double p,
                                       double q,
                                       boolean complement)
        Implementation for the inverse cumulative or survival probability.
        Parameters:
        p - Cumulative probability.
        q - Survival probability.
        complement - Set to true to compute the inverse survival probability
        Returns:
        the value
      • solveInverseProbability

        private static int solveInverseProbability​(java.util.function.IntUnaryOperator fun,
                                                   int lowerBound,
                                                   int upperBound)
        This is a utility function used by inverseProbability(double, double, boolean). It assumes that the inverse probability lies in the bracket (lower, upper]. The implementation does simple bisection to find the smallest x such that fun(x) >= 0.
        Parameters:
        fun - Probability function.
        lowerBound - Value satisfying fun(lower) < 0.
        upperBound - Value satisfying fun(upper) >= 0.
        Returns:
        the smallest x
      • createSampler

        public DiscreteDistribution.Sampler createSampler​(org.apache.commons.rng.UniformRandomProvider rng)
        Creates a sampler.
        Specified by:
        createSampler in interface DiscreteDistribution
        Parameters:
        rng - Generator of uniformly distributed numbers.
        Returns:
        a sampler that produces random numbers according this distribution.