Package org.apache.commons.statistics.distribution

Class FoldedNormalDistribution

  • All Implemented Interfaces:
    ContinuousDistribution
    public abstract class FoldedNormalDistribution
extends Object
    Implementation of the folded normal distribution.

    Given a normally distributed random variable \( X \) with mean \( \mu \) and variance \( \sigma^2 \), the random variable \( Y = |X| \) has a folded normal distribution. This is equivalent to not recording the sign from a normally distributed random variable.

    The probability density function of \( X \) is:

    \[ f(x; \mu, \sigma) = \frac 1 {\sigma\sqrt{2\pi}} e^{-{\frac 1 2}\left( \frac{x-\mu}{\sigma} \right)^2 } + \frac 1 {\sigma\sqrt{2\pi}} e^{-{\frac 1 2}\left( \frac{x+\mu}{\sigma} \right)^2 }\]

    for \( \mu \) the location, \( \sigma > 0 \) the scale, and \( x \in [0, \infty) \).

    If the location \( \mu \) is 0 this reduces to the half-normal distribution.

    Since:
    1.1
    See Also:
    Folded normal distribution (Wikipedia), Half-normal distribution (Wikipedia)

    • Method Detail

      • of

        public static FoldedNormalDistribution of​(double mu,
                                          double sigma)
        Creates a folded normal distribution. If the location mu is zero this is the half-normal distribution.
        Parameters:
        mu - Location parameter.
        sigma - Scale parameter.
        Returns:
        the distribution
        Throws:
        IllegalArgumentException - if sigma <= 0.

      • getMu

        public abstract double getMu()
        Gets the location parameter \( \mu \) of this distribution.
        Returns:
        the mu parameter.

      • getSigma

        public double getSigma()
        Gets the scale parameter \( \sigma \) of this distribution.
        Returns:
        the sigma parameter.

      • getMean

        public abstract double getMean()
        Gets the mean of this distribution.

        For location parameter \( \mu \) and scale parameter \( \sigma \), the mean is:

        \[ \sigma \sqrt{ \frac 2 \pi } \exp \left( \frac{-\mu^2}{2\sigma^2} \right) + \mu \operatorname{erf} \left( \frac \mu {\sqrt{2\sigma^2}} \right) \]

        where \( \operatorname{erf} \) is the error function.

        Returns:
        the mean.

      • getVariance

        public abstract double getVariance()
        Gets the variance of this distribution.

        For location parameter \( \mu \), scale parameter \( \sigma \) and a distribution mean \( \mu_Y \), the variance is:

        \[ \mu^2 + \sigma^2 - \mu_{Y}^2 \]

        Returns:
        the variance.

      • getSupportLowerBound

        public double getSupportLowerBound()
        Gets the lower bound of the support. It must return the same value as inverseCumulativeProbability(0), i.e. \( \inf \{ x \in \mathbb R : P(X \le x) \gt 0 \} \).

        The lower bound of the support is always 0.

        Returns:
        0.

      • getSupportUpperBound

        public double getSupportUpperBound()
        Gets the upper bound of the support. It must return the same value as inverseCumulativeProbability(1), i.e. \( \inf \{ x \in \mathbb R : P(X \le x) = 1 \} \).

        The upper bound of the support is always positive infinity.

        Returns:
        positive infinity.

      • probability

        public double probability​(double x0,
                          double 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)
        Specified by:
        probability in interface ContinuousDistribution
        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 double 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 R : P(X \le x) \ge p\} & \text{for } 0 \lt p \le 1 \\ \inf \{ x \in \mathbb R : P(X \le x) \gt 0 \} & \text{for } p = 0 \end{cases} \]

        The default implementation returns:

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

      • inverseSurvivalProbability

        public double 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 R : P(X \gt x) \le p\} & \text{for } 0 \le p \lt 1 \\ \inf \{ x \in \mathbb R : P(X \gt x) \lt 1 \} & \text{for } p = 1 \end{cases} \]

        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 ContinuousDistribution
        Parameters:
        p - Survival probability.
        Returns:
        the smallest (1-p)-quantile of this distribution (largest 0-quantile for p = 1).
        Throws:
        IllegalArgumentException - if p < 0 or p > 1

      • createSampler

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