Package org.apache.commons.statistics.distribution

Class FoldedNormalDistribution

java.lang.Object
org.apache.commons.statistics.distribution.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:

  • Method Details

    • 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.