Class StableSampler

  • All Implemented Interfaces:
    ContinuousSampler, SharedStateContinuousSampler, SharedStateSampler<SharedStateContinuousSampler>
    Direct Known Subclasses:
    StableSampler.BaseStableSampler, StableSampler.GaussianStableSampler, StableSampler.LevyStableSampler, StableSampler.TransformedStableSampler

    public abstract class StableSampler
    extends java.lang.Object
    implements SharedStateContinuousSampler
    Samples from a stable distribution.

    Several different parameterizations exist for the stable distribution. This sampler uses the 0-parameterization distribution described in Nolan (2020) "Univariate Stable Distributions: Models for Heavy Tailed Data". Springer Series in Operations Research and Financial Engineering. Springer. Sections 1.7 and 3.3.3.

    The random variable \( X \) has the stable distribution \( S(\alpha, \beta, \gamma, \delta; 0) \) if its characteristic function is given by:

    \[ E(e^{iuX}) = \begin{cases} \exp \left (- \gamma^\alpha |u|^\alpha \left [1 - i \beta (\tan \frac{\pi \alpha}{2})(\text{sgn}(u)) \right ] + i \delta u \right ) & \alpha \neq 1 \\ \exp \left (- \gamma |u| \left [1 + i \beta \frac{2}{\pi} (\text{sgn}(u)) \log |u| \right ] + i \delta u \right ) & \alpha = 1 \end{cases} \]

    The function is continuous with respect to all the parameters; the parameters \( \alpha \) and \( \beta \) determine the shape and the parameters \( \gamma \) and \( \delta \) determine the scale and location. The support of the distribution is:

    \[ \text{support} f(x|\alpha,\beta,\gamma,\delta; 0) = \begin{cases} [\delta - \gamma \tan \frac{\pi \alpha}{2}, \infty) & \alpha \lt 1\ and\ \beta = 1 \\ (-\infty, \delta + \gamma \tan \frac{\pi \alpha}{2}] & \alpha \lt 1\ and\ \beta = -1 \\ (-\infty, \infty) & otherwise \end{cases} \]

    The implementation uses the Chambers-Mallows-Stuck (CMS) method as described in:

    • Chambers, Mallows & Stuck (1976) "A Method for Simulating Stable Random Variables". Journal of the American Statistical Association. 71 (354): 340–344.
    • Weron (1996) "On the Chambers-Mallows-Stuck method for simulating skewed stable random variables". Statistics & Probability Letters. 28 (2): 165–171.
    Since:
    1.4
    See Also:
    Stable distribution (Wikipedia), Nolan (2020) Univariate Stable Distributions, Chambers et al (1976) JOASA 71: 340-344, Weron (1996). Statistics & Probability Letters. 28 (2): 165–171.
    • Field Detail

      • ALPHA_GAUSSIAN

        private static final double ALPHA_GAUSSIAN
        The alpha value for the Gaussian case.
        See Also:
        Constant Field Values
      • ALPHA_CAUCHY

        private static final double ALPHA_CAUCHY
        The alpha value for the Cauchy case.
        See Also:
        Constant Field Values
      • ALPHA_LEVY

        private static final double ALPHA_LEVY
        The alpha value for the Levy case.
        See Also:
        Constant Field Values
      • ALPHA_SMALL

        private static final double ALPHA_SMALL
        The alpha value for the alpha -> 0 to switch to using the Weron formula. Note that small alpha requires robust correction of infinite samples.
        See Also:
        Constant Field Values
      • BETA_LEVY

        private static final double BETA_LEVY
        The beta value for the Levy case.
        See Also:
        Constant Field Values
      • GAMMA_1

        private static final double GAMMA_1
        The gamma value for the normalized case.
        See Also:
        Constant Field Values
      • DELTA_0

        private static final double DELTA_0
        The delta value for the normalized case.
        See Also:
        Constant Field Values
      • TAU_ZERO

        private static final double TAU_ZERO
        The tau value for zero. When tau is zero, this is effectively beta = 0.
        See Also:
        Constant Field Values
      • LOWER

        private static final double LOWER
        The lower support for the distribution. This is the lower bound of (-inf, +inf) If the sample is not within this bound (lower < x) then it is either infinite or NaN and the result should be checked.
        See Also:
        Constant Field Values
      • UPPER

        private static final double UPPER
        The upper support for the distribution. This is the upper bound of (-inf, +inf). If the sample is not within this bound (x < upper) then it is either infinite or NaN and the result should be checked.
        See Also:
        Constant Field Values
    • Constructor Detail

      • StableSampler

        StableSampler​(UniformRandomProvider rng)
        Parameters:
        rng - Generator of uniformly distributed random numbers.
    • Method Detail

      • sample

        public abstract double sample()
        Generate a sample from a stable distribution.

        The distribution uses the 0-parameterization: S(alpha, beta, gamma, delta; 0).

        Specified by:
        sample in interface ContinuousSampler
        Returns:
        a sample.
      • nextLong

        long nextLong()
        Generates a long value. Used by algorithm implementations without exposing access to the RNG.
        Returns:
        the next random value
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • of

        public static StableSampler of​(UniformRandomProvider rng,
                                       double alpha,
                                       double beta)
        Creates a standardized sampler of a stable distribution with zero location and unit scale.

        Special cases:

        • alpha=2 returns a Gaussian distribution sampler with mean=0 and variance=2 (Note: beta has no effect on the distribution).
        • alpha=1 and beta=0 returns a Cauchy distribution sampler with location=0 and scale=1.
        • alpha=0.5 and beta=1 returns a Levy distribution sampler with location=-1 and scale=1. This location shift is due to the 0-parameterization of the stable distribution.

        Note: To allow the computation of the stable distribution the parameter alpha is validated using 1 - alpha in the interval [-1, 1).

        Parameters:
        rng - Generator of uniformly distributed random numbers.
        alpha - Stability parameter. Must be in the interval (0, 2].
        beta - Skewness parameter. Must be in the interval [-1, 1].
        Returns:
        the sampler
        Throws:
        java.lang.IllegalArgumentException - if 1 - alpha < -1; or 1 - alpha >= 1; or beta < -1; or beta > 1.
      • of

        public static StableSampler of​(UniformRandomProvider rng,
                                       double alpha,
                                       double beta,
                                       double gamma,
                                       double delta)
        Creates a sampler of a stable distribution. This applies a transformation to the standardized sampler.

        The random variable \( X \) has the stable distribution \( S(\alpha, \beta, \gamma, \delta; 0) \) if:

        \[ X = \gamma Z_0 + \delta \]

        where \( Z_0 = S(\alpha, \beta; 0) \) is a standardized stable distribution.

        Note: To allow the computation of the stable distribution the parameter alpha is validated using 1 - alpha in the interval [-1, 1).

        Parameters:
        rng - Generator of uniformly distributed random numbers.
        alpha - Stability parameter. Must be in the interval (0, 2].
        beta - Skewness parameter. Must be in the interval [-1, 1].
        gamma - Scale parameter. Must be strictly positive and finite.
        delta - Location parameter. Must be finite.
        Returns:
        the sampler
        Throws:
        java.lang.IllegalArgumentException - if 1 - alpha < -1; or 1 - alpha >= 1; or beta < -1; or beta > 1; or gamma <= 0; or gamma or delta are not finite.
        See Also:
        of(UniformRandomProvider, double, double)
      • create

        private static StableSampler create​(UniformRandomProvider rng,
                                            double alpha,
                                            double beta)
        Creates a standardized sampler of a stable distribution with zero location and unit scale.
        Parameters:
        rng - Generator of uniformly distributed random numbers.
        alpha - Stability parameter. Must be in the interval (0, 2].
        beta - Skewness parameter. Must be in the interval [-1, 1].
        Returns:
        the sampler
      • validateParameters

        private static void validateParameters​(double alpha,
                                               double beta)
        Validate the parameters are in the correct range.
        Parameters:
        alpha - Stability parameter. Must be in the interval (0, 2].
        beta - Skewness parameter. Must be in the interval [-1, 1].
        Throws:
        java.lang.IllegalArgumentException - if 1 - alpha < -1; or 1 - alpha >= 1; or beta < -1; or beta > 1.
      • validateParameters

        private static void validateParameters​(double alpha,
                                               double beta,
                                               double gamma,
                                               double delta)
        Validate the parameters are in the correct range.
        Parameters:
        alpha - Stability parameter. Must be in the interval (0, 2].
        beta - Skewness parameter. Must be in the interval [-1, 1].
        gamma - Scale parameter. Must be strictly positive and finite.
        delta - Location parameter. Must be finite.
        Throws:
        java.lang.IllegalArgumentException - if 1 - alpha < -1; or 1 - alpha >= 1; or beta < -1; or beta > 1; or gamma <= 0; or gamma or delta are not finite.