Class StableSampler
- java.lang.Object
-
- org.apache.commons.rng.sampling.distribution.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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
StableSampler.Alpha1CMSStableSampler
Implement the stable distribution case:alpha == 1
andbeta != 0
.private static class
StableSampler.BaseStableSampler
Base class for implementations of a stable distribution that requires an exponential random deviate.(package private) static class
StableSampler.Beta0CMSStableSampler
Implement the generic stable distribution case:alpha < 2
andbeta == 0
.(package private) static class
StableSampler.Beta0WeronStableSampler
Implement the generic stable distribution case:alpha < 2
andbeta == 0
.private static class
StableSampler.CauchyStableSampler
Implement thealpha = 1
andbeta = 0
stable distribution case (Cauchy distribution).(package private) static class
StableSampler.CMSStableSampler
Implement the generic stable distribution case:alpha < 2
andbeta != 0
.private static class
StableSampler.GaussianStableSampler
Implement thealpha = 2
stable distribution case (Gaussian distribution).private static class
StableSampler.LevyStableSampler
Implement thealpha = 0.5
andbeta = 1
stable distribution case (Levy distribution).(package private) static class
StableSampler.SpecialMath
Implement special math functions required by the CMS algorithm.private static class
StableSampler.TransformedStableSampler
Class for implementations of a stable distribution transformed by scale and location.(package private) static class
StableSampler.WeronStableSampler
Implement the generic stable distribution case:alpha < 2
andbeta != 0
.
-
Field Summary
Fields Modifier and Type Field Description private static double
ALPHA_CAUCHY
The alpha value for the Cauchy case.private static double
ALPHA_GAUSSIAN
The alpha value for the Gaussian case.private static double
ALPHA_LEVY
The alpha value for the Levy case.private static double
ALPHA_SMALL
The alpha value for thealpha -> 0
to switch to using the Weron formula.private static double
BETA_LEVY
The beta value for the Levy case.private static double
DELTA_0
The delta value for the normalized case.private static double
GAMMA_1
The gamma value for the normalized case.private static double
LOWER
The lower support for the distribution.private static double
PI_2
pi / 2.private UniformRandomProvider
rng
Underlying source of randomness.private static double
TAU_ZERO
The tau value for zero.private static double
UPPER
The upper support for the distribution.
-
Constructor Summary
Constructors Constructor Description StableSampler(UniformRandomProvider rng)
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description private static StableSampler
create(UniformRandomProvider rng, double alpha, double beta)
Creates a standardized sampler of a stable distribution with zero location and unit scale.(package private) long
nextLong()
Generates along
value.static StableSampler
of(UniformRandomProvider rng, double alpha, double beta)
Creates a standardized sampler of a stable distribution with zero location and unit scale.static StableSampler
of(UniformRandomProvider rng, double alpha, double beta, double gamma, double delta)
Creates a sampler of a stable distribution.abstract double
sample()
Generate a sample from a stable distribution.java.lang.String
toString()
private static void
validateParameters(double alpha, double beta)
Validate the parameters are in the correct range.private static void
validateParameters(double alpha, double beta, double gamma, double delta)
Validate the parameters are in the correct range.abstract StableSampler
withUniformRandomProvider(UniformRandomProvider rng)
Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface org.apache.commons.rng.sampling.distribution.ContinuousSampler
samples, samples
-
-
-
-
Field Detail
-
PI_2
private static final double PI_2
pi / 2.- See Also:
- Constant Field Values
-
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 thealpha -> 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 effectivelybeta = 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
-
rng
private final UniformRandomProvider rng
Underlying source of randomness.
-
-
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 interfaceContinuousSampler
- Returns:
- a sample.
-
withUniformRandomProvider
public abstract StableSampler withUniformRandomProvider(UniformRandomProvider rng)
Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.- Specified by:
withUniformRandomProvider
in interfaceSharedStateSampler<SharedStateContinuousSampler>
- Parameters:
rng
- Generator of uniformly distributed random numbers.- Returns:
- the sampler
-
nextLong
long nextLong()
Generates along
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 classjava.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 withmean=0
andvariance=2
(Note:beta
has no effect on the distribution).alpha=1
andbeta=0
returns a Cauchy distribution sampler withlocation=0
andscale=1
.alpha=0.5
andbeta=1
returns a Levy distribution sampler withlocation=-1
andscale=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
- if1 - alpha < -1
; or1 - alpha >= 1
; orbeta < -1
; orbeta > 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
- if1 - alpha < -1
; or1 - alpha >= 1
; orbeta < -1
; orbeta > 1
; orgamma <= 0
; orgamma
ordelta
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
- if1 - alpha < -1
; or1 - alpha >= 1
; orbeta < -1
; orbeta > 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
- if1 - alpha < -1
; or1 - alpha >= 1
; orbeta < -1
; orbeta > 1
; orgamma <= 0
; orgamma
ordelta
are not finite.
-
-