Modifier and Type	Class and Description
pack-priv static class	ZipfDistribution.ZipfRejectionInversionSampler Utility class implementing a rejection inversion sampling method for a discrete, bounded Zipf distribution that is based on the method described in Wolfgang Hörmann and Gerhard Derflinger "Rejection-inversion to generate variates from monotone discrete distributions." ACM Transactions on Modeling and Computer Simulation (TOMACS) 6.3 (1996): 169-184.

Access	Constructor and Description
public	ZipfDistribution(final int Number of elements. numberOfElements, final double Exponent. exponent) Create a new Zipf distribution with the given number of elements and exponent.
public	ZipfDistribution(RandomGenerator Random number generator. rng, int Number of elements. numberOfElements, double Exponent. exponent) Creates a Zipf distribution.

Method Summary

Modifier and Type	Method and Description
protected double	Returns: the mean of this distribution calculateNumericalMean() Used by `getNumericalMean()`.
protected double	Returns: the variance of this distribution calculateNumericalVariance() Used by `getNumericalVariance()`.
public double	cumulativeProbability(final int the point at which the CDF is evaluated x) Implements org.apache.commons.math3.distribution.IntegerDistribution.cumulativeProbability. For a random variable `X` whose values are distributed according to this distribution, this method returns `P(X <= x)`.
private double	Returns: the n^th generalized harmonic number. generalizedHarmonic(final int Term in the series to calculate (must be larger than 1) n, final double Exponent (special case `m = 1` is the harmonic series). m) Calculates the Nth generalized harmonic number.
public double	Returns: the exponent getExponent() Get the exponent characterizing the distribution.
public int	Returns: the number of elements getNumberOfElements() Get the number of elements (e.g. corpus size) for the distribution.
public double	getNumericalMean() Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalMean. Use this method to get the numerical value of the mean of this distribution.
public double	getNumericalVariance() Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalVariance. Use this method to get the numerical value of the variance of this distribution.
public int	Returns: lower bound of the support (always 1) getSupportLowerBound() Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportLowerBound. Access the lower bound of the support.
public int	Returns: upper bound of the support getSupportUpperBound() Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportUpperBound. Access the upper bound of the support.
public boolean	Returns: `true` isSupportConnected() Implements org.apache.commons.math3.distribution.IntegerDistribution.isSupportConnected. Use this method to get information about whether the support is connected, i.e. whether all integers between the lower and upper bound of the support are included in the support.
public double	logProbability(int the point at which the PMF is evaluated x) Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.logProbability. For a random variable `X` whose values are distributed according to this distribution, this method returns `log(P(X = x))`, where `log` is the natural logarithm.
public double	probability(final int the point at which the PMF is evaluated x) Implements org.apache.commons.math3.distribution.IntegerDistribution.probability. For a random variable `X` whose values are distributed according to this distribution, this method returns `P(X = x)`.
public int	sample() Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.sample. Implements org.apache.commons.math3.distribution.IntegerDistribution.sample. Generate a random value sampled from this distribution.

Inherited from org.apache.commons.math3.distribution.AbstractIntegerDistribution:: cumulativeProbability inverseCumulativeProbability reseedRandomGenerator sample solveInverseCumulativeProbability

Field Detail

exponent	back to summary
private final double exponent Exponent parameter of the distribution.

numberOfElements	back to summary
private final int numberOfElements Number of elements.

numericalMean	back to summary
private double numericalMean Cached numerical mean

numericalMeanIsCalculated	back to summary
private boolean numericalMeanIsCalculated Whether or not the numerical mean has been calculated

numericalVariance	back to summary
private double numericalVariance Cached numerical variance

numericalVarianceIsCalculated	back to summary
private boolean numericalVarianceIsCalculated Whether or not the numerical variance has been calculated

sampler	back to summary
private transient ZipfDistribution.ZipfRejectionInversionSampler sampler The sampler to be used for the sample() method

serialVersionUID	back to summary
private static final long serialVersionUID Hides org.apache.commons.math3.distribution.AbstractIntegerDistribution.serialVersionUID. Serializable version identifier.

serialVersionUID

back to summary

private static final long serialVersionUID

Hides org.apache.commons.math3.distribution.AbstractIntegerDistribution.serialVersionUID.

Serializable version identifier.

Constructor Detail

ZipfDistribution back to summary

ZipfDistribution	back to summary
public ZipfDistribution(final int numberOfElements, final double exponent) Create a new Zipf distribution with the given number of elements and exponent. Note this constructor will implicitly create an instance of `Well19937c` as random generator to be used for sampling only (see `sample()` and `sample(int)`). In case no sampling is needed for the created distribution, it is advised to pass `null` as random generator via the appropriate constructors to avoid the additional initialisation overhead. Parameters numberOfElements:int Number of elements. exponent:double Exponent. Exceptions NotStrictlyPositiveException: if `numberOfElements <= 0` or `exponent <= 0`.

public ZipfDistribution(final int numberOfElements, final double exponent)

Create a new Zipf distribution with the given number of elements and exponent.

Note

this constructor will implicitly create an instance of Well19937c as random generator to be used for sampling only (see sample() and sample(int)). In case no sampling is needed for the created distribution, it is advised to pass null as random generator via the appropriate constructors to avoid the additional initialisation overhead.

Parameters

numberOfElements:int: Number of elements.
exponent:double: Exponent.

Exceptions

NotStrictlyPositiveException:: if numberOfElements <= 0 or exponent <= 0.

ZipfDistribution back to summary

ZipfDistribution	back to summary
public ZipfDistribution(RandomGenerator rng, int numberOfElements, double exponent) throws NotStrictlyPositiveException Creates a Zipf distribution. Parameters rng:RandomGenerator Random number generator. numberOfElements:int Number of elements. exponent:double Exponent. Exceptions NotStrictlyPositiveException: if `numberOfElements <= 0` or `exponent <= 0`. Since 3.1

public ZipfDistribution(RandomGenerator rng, int numberOfElements, double exponent) throws NotStrictlyPositiveException

Creates a Zipf distribution.

Parameters

rng:RandomGenerator: Random number generator.
numberOfElements:int: Number of elements.
exponent:double: Exponent.

Exceptions

NotStrictlyPositiveException:: if numberOfElements <= 0 or exponent <= 0.

Since

3.1

Method Detail

calculateNumericalMean back to summary

calculateNumericalMean	back to summary
protected double calculateNumericalMean() Used by `getNumericalMean()`. Returns:double the mean of this distribution

protected double calculateNumericalMean()

Used by getNumericalMean().

Returns:double: the mean of this distribution

calculateNumericalVariance back to summary

calculateNumericalVariance	back to summary
protected double calculateNumericalVariance() Used by `getNumericalVariance()`. Returns:double the variance of this distribution

protected double calculateNumericalVariance()

Used by getNumericalVariance().

Returns:double: the variance of this distribution

cumulativeProbability back to summary

cumulativeProbability	back to summary
public double cumulativeProbability(final int x) Implements org.apache.commons.math3.distribution.IntegerDistribution.cumulativeProbability. Doc from org.apache.commons.math3.distribution.IntegerDistribution.cumulativeProbability. For a random variable `X` whose values are distributed according to this distribution, this method returns `P(X <= x)`. In other words, this method represents the (cumulative) distribution function (CDF) for this distribution. Parameters x:int the point at which the CDF is evaluated Returns:double the probability that a random variable with this distribution takes a value less than or equal to `x`

public double cumulativeProbability(final int x)

Implements org.apache.commons.math3.distribution.IntegerDistribution.cumulativeProbability.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.cumulativeProbability.

For a random variable X whose values are distributed according to this distribution, this method returns P(X <= x). In other words, this method represents the (cumulative) distribution function (CDF) for this distribution.

Parameters

x:int: the point at which the CDF is evaluated

Returns:double

the probability that a random variable with this distribution takes a value less than or equal to x

generalizedHarmonic back to summary

generalizedHarmonic	back to summary
private double generalizedHarmonic(final int n, final double m) Calculates the Nth generalized harmonic number. See Harmonic Series. Parameters n:int Term in the series to calculate (must be larger than 1) m:double Exponent (special case `m = 1` is the harmonic series). Returns:double the n^th generalized harmonic number.

private double generalizedHarmonic(final int n, final double m)

Calculates the Nth generalized harmonic number. See Harmonic Series.

Parameters

n:int: Term in the series to calculate (must be larger than 1)
m:double: Exponent (special case m = 1 is the harmonic series).

Returns:double

the n^th generalized harmonic number.

getExponent	back to summary
public double getExponent() Get the exponent characterizing the distribution. Returns:double the exponent

getExponent

back to summary

public double getExponent()

Get the exponent characterizing the distribution.

Returns:double: the exponent

getNumberOfElements	back to summary
public int getNumberOfElements() Get the number of elements (e.g. corpus size) for the distribution. Returns:int the number of elements

getNumberOfElements

back to summary

public int getNumberOfElements()

Get the number of elements (e.g. corpus size) for the distribution.

Returns:int: the number of elements

getNumericalMean back to summary

getNumericalMean	back to summary
public double getNumericalMean() Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalMean. Doc from org.apache.commons.math3.distribution.IntegerDistribution.getNumericalMean. Use this method to get the numerical value of the mean of this distribution. For number of elements `N` and exponent `s`, the mean is `Hs1 / Hs`, where `Hs1 = generalizedHarmonic(N, s - 1)`, `Hs = generalizedHarmonic(N, s)`. Returns:double the mean or `Double.NaN` if it is not defined

public double getNumericalMean()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalMean.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.getNumericalMean.

Use this method to get the numerical value of the mean of this distribution. For number of elements N and exponent s, the mean is Hs1 / Hs, where

Hs1 = generalizedHarmonic(N, s - 1),
Hs = generalizedHarmonic(N, s).

Returns:double: the mean or Double.NaN if it is not defined

getNumericalVariance back to summary

getNumericalVariance	back to summary
public double getNumericalVariance() Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalVariance. Doc from org.apache.commons.math3.distribution.IntegerDistribution.getNumericalVariance. Use this method to get the numerical value of the variance of this distribution. For number of elements `N` and exponent `s`, the mean is `(Hs2 / Hs) - (Hs1^2 / Hs^2)`, where `Hs2 = generalizedHarmonic(N, s - 2)`, `Hs1 = generalizedHarmonic(N, s - 1)`, `Hs = generalizedHarmonic(N, s)`. Returns:double the variance (possibly `Double.POSITIVE_INFINITY` or `Double.NaN` if it is not defined)

public double getNumericalVariance()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getNumericalVariance.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.getNumericalVariance.

Use this method to get the numerical value of the variance of this distribution. For number of elements N and exponent s, the mean is (Hs2 / Hs) - (Hs1^2 / Hs^2), where

Hs2 = generalizedHarmonic(N, s - 2),
Hs1 = generalizedHarmonic(N, s - 1),
Hs = generalizedHarmonic(N, s).

Returns:double: the variance (possibly Double.POSITIVE_INFINITY or Double.NaN if it is not defined)

getSupportLowerBound back to summary

getSupportLowerBound	back to summary
public int getSupportLowerBound() Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportLowerBound. Doc from org.apache.commons.math3.distribution.IntegerDistribution.getSupportLowerBound. Access the lower bound of the support. This method must return the same value as `inverseCumulativeProbability(0)`. In other words, this method must return `inf {x in Z \| P(X <= x) > 0}`. The lower bound of the support is always 1 no matter the parameters. Returns:int lower bound of the support (always 1)

public int getSupportLowerBound()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportLowerBound.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.getSupportLowerBound.

Access the lower bound of the support. This method must return the same value as inverseCumulativeProbability(0). In other words, this method must return

inf {x in Z | P(X <= x) > 0}.

The lower bound of the support is always 1 no matter the parameters.

Returns:int: lower bound of the support (always 1)

getSupportUpperBound back to summary

getSupportUpperBound	back to summary
public int getSupportUpperBound() Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportUpperBound. Doc from org.apache.commons.math3.distribution.IntegerDistribution.getSupportUpperBound. Access the upper bound of the support. This method must return the same value as `inverseCumulativeProbability(1)`. In other words, this method must return `inf {x in R \| P(X <= x) = 1}`. The upper bound of the support is the number of elements. Returns:int upper bound of the support

public int getSupportUpperBound()

Implements org.apache.commons.math3.distribution.IntegerDistribution.getSupportUpperBound.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.getSupportUpperBound.

Access the upper bound of the support. This method must return the same value as inverseCumulativeProbability(1). In other words, this method must return

inf {x in R | P(X <= x) = 1}.

The upper bound of the support is the number of elements.

Returns:int: upper bound of the support

isSupportConnected back to summary

isSupportConnected	back to summary
public boolean isSupportConnected() Implements org.apache.commons.math3.distribution.IntegerDistribution.isSupportConnected. Doc from org.apache.commons.math3.distribution.IntegerDistribution.isSupportConnected. Use this method to get information about whether the support is connected, i.e. whether all integers between the lower and upper bound of the support are included in the support. The support of this distribution is connected. Returns:boolean `true`

public boolean isSupportConnected()

Implements org.apache.commons.math3.distribution.IntegerDistribution.isSupportConnected.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.isSupportConnected.

Use this method to get information about whether the support is connected, i.e. whether all integers between the lower and upper bound of the support are included in the support. The support of this distribution is connected.

Returns:boolean: true

logProbability back to summary

logProbability	back to summary
public double logProbability(int x) Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.logProbability. Doc from org.apache.commons.math3.distribution.AbstractIntegerDistribution.logProbability. For a random variable `X` whose values are distributed according to this distribution, this method returns `log(P(X = x))`, where `log` is the natural logarithm. In other words, this method represents the logarithm of the probability mass function (PMF) for the distribution. Note that due to the floating point precision and under/overflow issues, this method will for some distributions be more precise and faster than computing the logarithm of `probability(int)`. The default implementation simply computes the logarithm of `probability(x)`. Parameters x:int the point at which the PMF is evaluated Returns:double the logarithm of the value of the probability mass function at `x` Annotations @Override

public double logProbability(int x)

Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.logProbability.

Doc from org.apache.commons.math3.distribution.AbstractIntegerDistribution.logProbability.

For a random variable X whose values are distributed according to this distribution, this method returns log(P(X = x)), where log is the natural logarithm. In other words, this method represents the logarithm of the probability mass function (PMF) for the distribution. Note that due to the floating point precision and under/overflow issues, this method will for some distributions be more precise and faster than computing the logarithm of probability(int).

The default implementation simply computes the logarithm of probability(x).

Parameters

x:int: the point at which the PMF is evaluated

Returns:double

the logarithm of the value of the probability mass function at x

Annotations

@Override

probability back to summary

probability	back to summary
public double probability(final int x) Implements org.apache.commons.math3.distribution.IntegerDistribution.probability. Doc from org.apache.commons.math3.distribution.IntegerDistribution.probability. For a random variable `X` whose values are distributed according to this distribution, this method returns `P(X = x)`. In other words, this method represents the probability mass function (PMF) for the distribution. Parameters x:int the point at which the PMF is evaluated Returns:double the value of the probability mass function at `x`

public double probability(final int x)

Implements org.apache.commons.math3.distribution.IntegerDistribution.probability.

Doc from org.apache.commons.math3.distribution.IntegerDistribution.probability.

For a random variable X whose values are distributed according to this distribution, this method returns P(X = x). In other words, this method represents the probability mass function (PMF) for the distribution.

Parameters

x:int: the point at which the PMF is evaluated

Returns:double

the value of the probability mass function at x

sample	back to summary
public int sample() Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.sample. Implements org.apache.commons.math3.distribution.IntegerDistribution.sample. Doc from org.apache.commons.math3.distribution.AbstractIntegerDistribution.sample. Generate a random value sampled from this distribution. The default implementation uses the inversion method. Returns:int Doc from org.apache.commons.math3.distribution.IntegerDistribution.sample. a random value Annotations @Override

sample

back to summary

public int sample()

Overrides org.apache.commons.math3.distribution.AbstractIntegerDistribution.sample.

Implements org.apache.commons.math3.distribution.IntegerDistribution.sample.

Doc from org.apache.commons.math3.distribution.AbstractIntegerDistribution.sample.

Generate a random value sampled from this distribution. The default implementation uses the inversion method.

Returns:int

Doc from org.apache.commons.math3.distribution.IntegerDistribution.sample.

a random value

Annotations

@Override

org.apache.commons.math3.distribution back to summary

pack-priv final Class ZipfDistribution.ZipfRejectionInversionSampler

Class Inheritance

extends Object

java.lang.Object
org.apache.commons.math3.distribution.ZipfDistribution.ZipfRejectionInversionSampler

Utility class implementing a rejection inversion sampling method for a discrete, bounded Zipf distribution that is based on the method described in

Wolfgang Hörmann and Gerhard Derflinger "Rejection-inversion to generate variates from monotone discrete distributions." ACM Transactions on Modeling and Computer Simulation (TOMACS) 6.3 (1996): 169-184.

The paper describes an algorithm for exponents larger than 1 (Algorithm ZRI). The original method uses H(x) := (v + x)^(1 - q) / (1 - q) as the integral of the hat function. This function is undefined for q = 1, which is the reason for the limitation of the exponent. If instead the integral function H(x) := ((v + x)^(1 - q) - 1) / (1 - q) is used, for which a meaningful limit exists for q = 1, the method works for all positive exponents.

The following implementation uses v := 0 and generates integral numbers in the range [1, numberOfElements]. This is different to the original method where v is defined to be positive and numbers are taken from [0, i_max]. This explains why the implementation looks slightly different.

Since: 3.6

Field Summary

Modifier and Type	Field and Description
private final double	exponent Exponent parameter of the distribution.
private final double	hIntegralNumberOfElements Constant equal to `hIntegral(numberOfElements + 0.5)`.
private final double	hIntegralX1 Constant equal to `hIntegral(1.5) - 1`.
private final int	numberOfElements Number of elements.
private final double	s Constant equal to `2 - hIntegralInverse(hIntegral(2.5) - h(2)`.

Constructor Summary

Access	Constructor and Description
pack-priv	ZipfRejectionInversionSampler(final int number of elements numberOfElements, final double exponent parameter of the distribution exponent) Simple constructor.

Method Summary

Modifier and Type	Method and Description
private double	Returns: h(x) h(final double free parameter x) `h(x) := 1/x^exponent`
pack-priv static double	Returns: `log(1+x)/x` helper1(final double a value larger than or equal to -1 x) Helper function that calculates `log(1+x)/x`.
pack-priv static double	Returns: `(exp(x)-1)/x` if x is non-zero, or 1 if x=0 helper2(final double free parameter x) Helper function to calculate `(exp(x)-1)/x`.
private double	Returns: `H(x)` hIntegral(final double free parameter x) `H(x) :=` `(x^(1-exponent) - 1)/(1 - exponent)`, if `exponent != 1` `log(x)`, if `exponent == 1`
private double	Returns: y for which `H(y) = x` hIntegralInverse(final double free parameter x) The inverse function of H(x).
pack-priv int	Returns: generated integral number in the range [1, numberOfElements] sample(final RandomGenerator random generator to use random) Generate one integral number in the range [1, numberOfElements].

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

exponent	back to summary
private final double exponent Exponent parameter of the distribution.

hIntegralNumberOfElements	back to summary
private final double hIntegralNumberOfElements Constant equal to `hIntegral(numberOfElements + 0.5)`.

hIntegralX1	back to summary
private final double hIntegralX1 Constant equal to `hIntegral(1.5) - 1`.

numberOfElements	back to summary
private final int numberOfElements Number of elements.

s	back to summary
private final double s Constant equal to `2 - hIntegralInverse(hIntegral(2.5) - h(2)`.

Constructor Detail

ZipfRejectionInversionSampler	back to summary
pack-priv ZipfRejectionInversionSampler(final int numberOfElements, final double exponent) Simple constructor. Parameters numberOfElements:int number of elements exponent:double exponent parameter of the distribution

ZipfRejectionInversionSampler

back to summary

pack-priv ZipfRejectionInversionSampler(final int numberOfElements, final double exponent)

Simple constructor.

Parameters

numberOfElements:int: number of elements
exponent:double: exponent parameter of the distribution

Method Detail

h back to summary

h	back to summary
private double h(final double x) `h(x) := 1/x^exponent` Parameters x:double free parameter Returns:double h(x)

private double h(final double x)

h(x) := 1/x^exponent

Parameters

x:double: free parameter

Returns:double

h(x)

helper1 back to summary

helper1	back to summary
pack-priv static double helper1(final double x) Helper function that calculates `log(1+x)/x`. A Taylor series expansion is used, if x is close to 0. Parameters x:double a value larger than or equal to -1 Returns:double `log(1+x)/x`

pack-priv static double helper1(final double x)

Helper function that calculates log(1+x)/x.

A Taylor series expansion is used, if x is close to 0.

Parameters

x:double: a value larger than or equal to -1

Returns:double

log(1+x)/x

helper2 back to summary

helper2	back to summary
pack-priv static double helper2(final double x) Helper function to calculate `(exp(x)-1)/x`. A Taylor series expansion is used, if x is close to 0. Parameters x:double free parameter Returns:double `(exp(x)-1)/x` if x is non-zero, or 1 if x=0

pack-priv static double helper2(final double x)

Helper function to calculate (exp(x)-1)/x.

A Taylor series expansion is used, if x is close to 0.

Parameters

x:double: free parameter

Returns:double

(exp(x)-1)/x if x is non-zero, or 1 if x=0

hIntegral back to summary

hIntegral	back to summary
private double hIntegral(final double x) `H(x) :=` `(x^(1-exponent) - 1)/(1 - exponent)`, if `exponent != 1` `log(x)`, if `exponent == 1` H(x) is an integral function of h(x), the derivative of H(x) is h(x). Parameters x:double free parameter Returns:double `H(x)`

private double hIntegral(final double x)

H(x) :=

(x^(1-exponent) - 1)/(1 - exponent), if exponent != 1
log(x), if exponent == 1

H(x) is an integral function of h(x), the derivative of H(x) is h(x).

Parameters

x:double: free parameter

Returns:double

H(x)

hIntegralInverse back to summary

hIntegralInverse	back to summary
private double hIntegralInverse(final double x) The inverse function of H(x). Parameters x:double free parameter Returns:double y for which `H(y) = x`

private double hIntegralInverse(final double x)

The inverse function of H(x).

Parameters

x:double: free parameter

Returns:double

y for which H(y) = x

sample	back to summary
pack-priv int sample(final RandomGenerator random) Generate one integral number in the range [1, numberOfElements]. Parameters random:RandomGenerator random generator to use Returns:int generated integral number in the range [1, numberOfElements]

sample

back to summary

pack-priv int sample(final RandomGenerator random)

Generate one integral number in the range [1, numberOfElements].

Parameters

random:RandomGenerator: random generator to use

Returns:int

generated integral number in the range [1, numberOfElements]

public Class ZipfDistribution

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Class ZipfDistribution.ZipfRejectionInversionSampler

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail