Class StableSampler
- All Implemented Interfaces:
ContinuousSampler
,SharedStateContinuousSampler
,SharedStateSampler<SharedStateContinuousSampler>
- Direct Known Subclasses:
StableSampler.BaseStableSampler
,StableSampler.GaussianStableSampler
,StableSampler.LevyStableSampler
,StableSampler.TransformedStableSampler
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:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static class
Implement the stable distribution case:alpha == 1
andbeta != 0
.private static class
Base class for implementations of a stable distribution that requires an exponential random deviate.(package private) static class
Implement the generic stable distribution case:alpha < 2
andbeta == 0
.(package private) static class
Implement the generic stable distribution case:alpha < 2
andbeta == 0
.private static class
Implement thealpha = 1
andbeta = 0
stable distribution case (Cauchy distribution).(package private) static class
Implement the generic stable distribution case:alpha < 2
andbeta != 0
.private static class
Implement thealpha = 2
stable distribution case (Gaussian distribution).private static class
Implement thealpha = 0.5
andbeta = 1
stable distribution case (Levy distribution).(package private) static final class
Implement special math functions required by the CMS algorithm.private static class
Class for implementations of a stable distribution transformed by scale and location.(package private) static class
Implement the generic stable distribution case:alpha < 2
andbeta != 0
. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final double
The alpha value for the Cauchy case.private static final double
The alpha value for the Gaussian case.private static final double
The alpha value for the Levy case.private static final double
The alpha value for thealpha -> 0
to switch to using the Weron formula.private static final double
The beta value for the Levy case.private static final double
The delta value for the normalized case.private static final double
The gamma value for the normalized case.private static final double
The lower support for the distribution.private static final double
pi / 2.private final UniformRandomProvider
Underlying source of randomness.private static final double
The tau value for zero.private static final double
The upper support for the distribution. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate 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.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
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 Details
-
PI_2
private static final double PI_2pi / 2.- See Also:
-
ALPHA_GAUSSIAN
private static final double ALPHA_GAUSSIANThe alpha value for the Gaussian case.- See Also:
-
ALPHA_CAUCHY
private static final double ALPHA_CAUCHYThe alpha value for the Cauchy case.- See Also:
-
ALPHA_LEVY
private static final double ALPHA_LEVYThe alpha value for the Levy case.- See Also:
-
ALPHA_SMALL
private static final double ALPHA_SMALLThe alpha value for thealpha -> 0
to switch to using the Weron formula. Note that small alpha requires robust correction of infinite samples.- See Also:
-
BETA_LEVY
private static final double BETA_LEVYThe beta value for the Levy case.- See Also:
-
GAMMA_1
private static final double GAMMA_1The gamma value for the normalized case.- See Also:
-
DELTA_0
private static final double DELTA_0The delta value for the normalized case.- See Also:
-
TAU_ZERO
private static final double TAU_ZEROThe tau value for zero. When tau is zero, this is effectivelybeta = 0
.- See Also:
-
LOWER
private static final double LOWERThe 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:
-
UPPER
private static final double UPPERThe 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:
-
rng
Underlying source of randomness.
-
-
Constructor Details
-
StableSampler
StableSampler(UniformRandomProvider rng) - Parameters:
rng
- Generator of uniformly distributed random numbers.
-
-
Method Details
-
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
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
-
of
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:
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:
IllegalArgumentException
- if1 - alpha < -1
; or1 - alpha >= 1
; orbeta < -1
; orbeta > 1
; orgamma <= 0
; orgamma
ordelta
are not finite.- See Also:
-
create
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:
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:
IllegalArgumentException
- if1 - alpha < -1
; or1 - alpha >= 1
; orbeta < -1
; orbeta > 1
; orgamma <= 0
; orgamma
ordelta
are not finite.
-