bpp-core  2.2.0
bpp::RandomTools Class Reference

Utilitary function dealing with random numbers. More...

#include <Bpp/Numeric/Random/RandomTools.h>

+ Collaboration diagram for bpp::RandomTools:

Public Member Functions

 RandomTools ()
 
virtual ~RandomTools ()
 

Static Public Member Functions

static double giveRandomNumberBetweenZeroAndEntry (double entry, const RandomFactory &generator= *DEFAULT_GENERATOR)
 Get a double random value (between 0 and specified range). More...
 
static bool flipCoin (const RandomFactory &generator= *DEFAULT_GENERATOR)
 Get a boolean random value. More...
 
template<class intType >
static intType giveIntRandomNumberBetweenZeroAndEntry (intType entry, const RandomFactory &generator= *DEFAULT_GENERATOR)
 Get an integer random value (between 0 and specified range). More...
 
static void setSeed (long seed)
 Set the default generator seed. More...
 
static double randGaussian (double mean, double variance, const RandomFactory &generator= *DEFAULT_GENERATOR)
 
static double randGamma (double dblAlpha, const RandomFactory &generator= *DEFAULT_GENERATOR)
 
static double randGamma (double alpha, double beta, const RandomFactory &generator= *DEFAULT_GENERATOR)
 
static double randBeta (double alpha, double beta, const RandomFactory &generator= *DEFAULT_GENERATOR)
 
static double randExponential (double mean, const RandomFactory &generator= *DEFAULT_GENERATOR)
 
template<class T >
static T pickOne (std::vector< T > &v, bool replace=false) throw (EmptyVectorException<T>)
 Pick one element in a vector. More...
 
template<class T >
static T pickOne (const std::vector< T > &v) throw (EmptyVectorException<T>)
 
template<class T >
static void getSample (const std::vector< T > &vin, std::vector< T > &vout, bool replace=false) throw (EmptyVectorException<T>, IndexOutOfBoundsException)
 Sample a vector. More...
 
template<class T >
static T pickOne (std::vector< T > &v, std::vector< double > &w, bool replace=false) throw (EmptyVectorException<T>)
 Pick one element in a vector, with associated probability weights. More...
 
template<class T >
static void getSample (const std::vector< T > &vin, const std::vector< double > &w, std::vector< T > &vout, bool replace=false) throw (EmptyVectorException<T>, IndexOutOfBoundsException)
 Sample a vector, with associated probability weights. More...
 
static std::vector< size_t > randMultinomial (size_t n, const std::vector< double > &probs)
 Get a random state from a set of probabilities/scores. More...
 
Probability functions.

Adapted from Yang's PAML package.

static double qNorm (double prob)
 Normal quantile function. More...
 
static double qNorm (double prob, double mu, double sigma)
 Normal quantile function. More...
 
static double lnGamma (double alpha)
 Computes $ln\left(\Gamma\left(\alpha\right)\right)$ given $\alpha$. More...
 
static double incompleteGamma (double x, double alpha, double ln_gamma_alpha)
 Returns the incomplete gamma ratio I(x,alpha). More...
 
static double qChisq (double prob, double v)
 $\chi^2$ quantile function. More...
 
static double pChisq (double x, double v)
 $\chi^2$ cumulative probability function. More...
 
static double qGamma (double prob, double alpha, double beta)
 The Gamma quantile function. More...
 
static double pGamma (double x, double alpha, double beta) throw (Exception)
 $\Gamma$ cumulative probability function. More...
 
Other probability functions.

Adapted from C routines for R programming langague Copyright (C) 1995, 1996 Robert Gentleman and Ross Ihaka Copyright (C) 1998 Ross Ihaka Copyright (C) 2000-2002 The R Development Core Team Copyright (C) 2003 The R Foundation

static double pNorm (double z)
 Normal cumulative function. More...
 
static double pNorm (double z, double mu, double sigma)
 
static double lnBeta (double alpha, double beta)
 Computes $ln\left(Beta\left(\alpha,\beta\right)\right)$ given $\alpha$ and $b\eta$. More...
 
static double incompleteBeta (double x, double alpha, double beta)
 Returns the regularized incomplete beta function $I_x(\alpha,\beta) = pbeta(x,\alpha,\beta$. More...
 
static double pBeta (double x, double alpha, double beta)
 
static double qBeta (double prob, double alpha, double beta)
 The Beta quantile function. More...
 

Static Public Attributes

static RandomFactoryDEFAULT_GENERATOR = new Uniform01K(time(NULL))
 

Static Private Member Functions

static double incompletebetafe (double a, double b, double x, double big, double biginv)
 functions for the computation of incompleteBeta More...
 
static double incompletebetafe2 (double a, double b, double x, double big, double biginv)
 
static double incompletebetaps (double a, double b, double x, double maxgam)
 
static double DblGammaGreaterThanOne (double dblAlpha, const RandomFactory &generator)
 
static double DblGammaLessThanOne (double dblAlpha, const RandomFactory &generator)
 

Detailed Description

Utilitary function dealing with random numbers.

This class uses Uniform01K generator by default. It is possible to change this by setting the DEFAULT_GENERATOR variable.

This class is adapted from Pupko's SEMPHY library. It also borrow some code from Yang's PAML package.

See also
RandomFactory

Definition at line 69 of file RandomTools.h.

Constructor & Destructor Documentation

◆ RandomTools()

bpp::RandomTools::RandomTools ( )
inline

Definition at line 72 of file RandomTools.h.

◆ ~RandomTools()

virtual bpp::RandomTools::~RandomTools ( )
inlinevirtual

Definition at line 73 of file RandomTools.h.

Member Function Documentation

◆ DblGammaGreaterThanOne()

double RandomTools::DblGammaGreaterThanOne ( double  dblAlpha,
const RandomFactory generator 
)
staticprivate

Definition at line 131 of file RandomTools.cpp.

References giveRandomNumberBetweenZeroAndEntry().

Referenced by randGamma().

◆ DblGammaLessThanOne()

double RandomTools::DblGammaLessThanOne ( double  dblAlpha,
const RandomFactory generator 
)
staticprivate

Definition at line 175 of file RandomTools.cpp.

Referenced by randGamma().

◆ flipCoin()

bool RandomTools::flipCoin ( const RandomFactory generator = *DEFAULT_GENERATOR)
static

Get a boolean random value.

Parameters
generatorRandom number generator to use.

Definition at line 70 of file RandomTools.cpp.

References giveRandomNumberBetweenZeroAndEntry().

◆ getSample() [1/2]

template<class T >
static void bpp::RandomTools::getSample ( const std::vector< T > &  vin,
std::vector< T > &  vout,
bool  replace = false 
)
throw (EmptyVectorException<T>,
IndexOutOfBoundsException
)
inlinestatic

Sample a vector.

The sample is a new vector of the specified size. If the size of the sample is identical to the original vector, the result is a shuffle of the original vector.

Parameters
vinThe vector to sample.
vout[out] The output vector to fill, with the appropriate size.
replaceShould sampling be with replacement?
Returns
A vector which is a sample of v.
Exceptions
IndexOutOfBoundExceptionif the sample size exceeds the original size when sampling without replacement.
EmptyVectorExceptionif the vector is empty.
Author
Sylvain Gaillard

Definition at line 223 of file RandomTools.h.

References pickOne().

◆ getSample() [2/2]

template<class T >
static void bpp::RandomTools::getSample ( const std::vector< T > &  vin,
const std::vector< double > &  w,
std::vector< T > &  vout,
bool  replace = false 
)
throw (EmptyVectorException<T>,
IndexOutOfBoundsException
)
inlinestatic

Sample a vector, with associated probability weights.

The sample is a new vector of the specified size. If the size of the sample is identical to the original vector, the result is a shuffle of the original vector.

It has to be noted that in case of sampling without replacement, the effect of the weighting scheme will be weaker as the sample size becomes close to the population size. In case the two are equal (pure permutations), the weigths have no effect at all.

Parameters
vinThe vector to sample.
wThe vector of weights.
vout[out] The output vector to fill, with the appropriate size.
replaceShould sampling be with replacement?
Returns
A vector which is a sample of v.
Exceptions
IndexOutOfBoundExceptionif the sample size exceeds the original size when sampling without replacement.
EmptyVectorExceptionif the vector is empty.
Warning
: For large sampling with replacement, the function is not efficient, as it recomputes the some of weights for each element picked.
Author
Julien Dutheil

Definition at line 303 of file RandomTools.h.

References pickOne().

◆ giveIntRandomNumberBetweenZeroAndEntry()

template<class intType >
static intType bpp::RandomTools::giveIntRandomNumberBetweenZeroAndEntry ( intType  entry,
const RandomFactory generator = *DEFAULT_GENERATOR 
)
inlinestatic

Get an integer random value (between 0 and specified range).

Note : the number you get is between 0 and entry not including entry !

Parameters
entryMax number to reach.
generatorRandom number generator to use.

Definition at line 121 of file RandomTools.h.

References giveRandomNumberBetweenZeroAndEntry().

◆ giveRandomNumberBetweenZeroAndEntry()

double RandomTools::giveRandomNumberBetweenZeroAndEntry ( double  entry,
const RandomFactory generator = *DEFAULT_GENERATOR 
)
static

Get a double random value (between 0 and specified range).

Note : the number you get is between 0 and entry not including entry !

Parameters
entryMax number to reach.
generatorRandom number generator to use.

Definition at line 62 of file RandomTools.cpp.

References bpp::RandomFactory::drawNumber().

Referenced by DblGammaGreaterThanOne(), flipCoin(), giveIntRandomNumberBetweenZeroAndEntry(), pickOne(), bpp::AbstractDiscreteDistribution::rand(), bpp::UniformDiscreteDistribution::randC(), randExponential(), randGamma(), and randMultinomial().

◆ incompleteBeta()

double RandomTools::incompleteBeta ( double  x,
double  alpha,
double  beta 
)
static

Returns the regularized incomplete beta function $I_x(\alpha,\beta) = pbeta(x,\alpha,\beta$.

alpha and beta are the parameters of the function.

Adapted From Cephes Math Library Release 2.8: June, 2000 Copyright by Stephen L. Moshier Under GPL License

Parameters
xthe upper limit of the integration.
alpha,betathe shape parameters.

Definition at line 659 of file RandomTools.cpp.

References bpp::NumConstants::VERY_BIG(), and bpp::NumConstants::VERY_TINY().

Referenced by pBeta().

◆ incompletebetafe()

double RandomTools::incompletebetafe ( double  a,
double  b,
double  x,
double  big,
double  biginv 
)
staticprivate

functions for the computation of incompleteBeta

Definition at line 770 of file RandomTools.cpp.

References bpp::NumConstants::VERY_TINY().

◆ incompletebetafe2()

double RandomTools::incompletebetafe2 ( double  a,
double  b,
double  x,
double  big,
double  biginv 
)
staticprivate

Definition at line 884 of file RandomTools.cpp.

References bpp::NumConstants::VERY_TINY().

◆ incompletebetaps()

double RandomTools::incompletebetaps ( double  a,
double  b,
double  x,
double  maxgam 
)
staticprivate

◆ incompleteGamma()

double RandomTools::incompleteGamma ( double  x,
double  alpha,
double  ln_gamma_alpha 
)
static

Returns the incomplete gamma ratio I(x,alpha).

X is the upper limit of the integration and alpha is the shape parameter. returns (-1) if in error ln_gamma_alpha = ln(Gamma(alpha)), is almost redundant. (1) series expansion if (alpha>x || x<=1) (2) continued fraction otherwise RATNEST FORTRAN by Bhattacharjee GP (1970) The incomplete gamma integral. Applied Statistics, 19: 285-287 (AS32)

Parameters
xthe upper limit of the integration.
alphathe shape parameter.
ln_gamma_alphaln(Gamma(alpha)).

Definition at line 250 of file RandomTools.cpp.

Referenced by pGamma().

◆ lnBeta()

double RandomTools::lnBeta ( double  alpha,
double  beta 
)
static

Computes $ln\left(Beta\left(\alpha,\beta\right)\right)$ given $\alpha$ and $b\eta$.

Returns ln(beta(alpha,beta)) for alpha>0 and beta>0.

Parameters
alpha,betaAlpha and Beta parameters.
Returns
$ln\left(Beta\left(\alpha,\beta\right)\right)$

Definition at line 512 of file RandomTools.cpp.

Referenced by bpp::BetaDiscreteDistribution::BetaDiscreteDistribution(), and bpp::BetaDiscreteDistribution::fireParameterChanged().

◆ lnGamma()

double RandomTools::lnGamma ( double  alpha)
static

Computes $ln\left(\Gamma\left(\alpha\right)\right)$ given $\alpha$.

Returns ln(gamma(alpha)) for alpha>0, accurate to 10 decimal places.
Stirling's formula is used for the central polynomial part of the procedure. Pike MC & Hill ID (1966) Algorithm 291: Logarithm of the gamma function. Communications of the Association for Computing Machinery, 9:684

Parameters
alphaAlpha parameter.
Returns
$ln\left(\Gamma\left(\alpha\right)\right)$

Definition at line 232 of file RandomTools.cpp.

Referenced by bpp::GammaDiscreteDistribution::fireParameterChanged(), bpp::GammaDiscreteDistribution::GammaDiscreteDistribution(), and pGamma().

◆ pBeta()

static double bpp::RandomTools::pBeta ( double  x,
double  alpha,
double  beta 
)
inlinestatic

◆ pChisq()

static double bpp::RandomTools::pChisq ( double  x,
double  v 
)
inlinestatic

$\chi^2$ cumulative probability function.

Parameters
xThe quantile for which the probability should be computed.
vnumber of degree of freedom.
Returns
The corresponding probability of the quantile.

Definition at line 430 of file RandomTools.h.

References pGamma().

Referenced by bpp::ContingencyTableTest::ContingencyTableTest().

◆ pGamma()

static double bpp::RandomTools::pGamma ( double  x,
double  alpha,
double  beta 
)
throw (Exception
)
inlinestatic

$\Gamma$ cumulative probability function.

Parameters
xThe quantile for which the probability should be computed.
alphaAlpha parameter.
betaBeta parameter.
Returns
The corresponding probability of the quantile.
Exceptions
ExceptionIf alpha or beta is invalid (<0).

Definition at line 459 of file RandomTools.h.

References incompleteGamma(), and lnGamma().

Referenced by bpp::GammaDiscreteDistribution::Expectation(), pChisq(), and bpp::GammaDiscreteDistribution::pProb().

◆ pickOne() [1/3]

template<class T >
static T bpp::RandomTools::pickOne ( std::vector< T > &  v,
bool  replace = false 
)
throw (EmptyVectorException< T >
)
inlinestatic

Pick one element in a vector.

Pick one element randomly in a vector and return it.

Parameters
vThe vector of elements.
replaceIf set to yes, then elements are allowed to be picked more than once, and therefore can be re-"placed" in the final sample.(default: false)
Returns
On element of the vector.
Exceptions
EmptyVectorExceptionif the vector is empty.
Author
Sylvain Gaillard

Definition at line 183 of file RandomTools.h.

Referenced by getSample().

◆ pickOne() [2/3]

template<class T >
static T bpp::RandomTools::pickOne ( const std::vector< T > &  v)
throw (EmptyVectorException< T >
)
inlinestatic

Definition at line 198 of file RandomTools.h.

◆ pickOne() [3/3]

template<class T >
static T bpp::RandomTools::pickOne ( std::vector< T > &  v,
std::vector< double > &  w,
bool  replace = false 
)
throw (EmptyVectorException< T >
)
inlinestatic

Pick one element in a vector, with associated probability weights.

Pick one element randomly in a vector and return it. If you choose to make the picking without replacement the element is removed from the vector, and so is the corresponding weight

Parameters
vThe vector of elements.
wThe vector of weight associated to the v elements.
replaceShould pick with replacement? (default: false)
Returns
On element of the vector.
Exceptions
EmptyVectorExceptionif the vector is empty.
Author
Julien Dutheil

Definition at line 250 of file RandomTools.h.

References bpp::VectorTools::cumSum(), and giveRandomNumberBetweenZeroAndEntry().

◆ pNorm() [1/2]

double RandomTools::pNorm ( double  z)
static

Normal cumulative function.

Returns Prob{x<=z} where x ~ N(0,1)

Parameters
zthe value.
Returns
The corresponding probability.

Definition at line 383 of file RandomTools.cpp.

Referenced by bpp::GaussianDiscreteDistribution::Expectation(), pNorm(), and bpp::GaussianDiscreteDistribution::pProb().

◆ pNorm() [2/2]

double RandomTools::pNorm ( double  z,
double  mu,
double  sigma 
)
static

Definition at line 377 of file RandomTools.cpp.

References pNorm().

◆ qBeta()

double RandomTools::qBeta ( double  prob,
double  alpha,
double  beta 
)
static

The Beta quantile function.

An adaptation from the C code of R Copyright (C) 1995, 1996 Robert Gentleman and Ross Ihaka Copyright (C) 1998–2007 The R Development Core Team based on code (C) 1979 and later Royal Statistical Society

Parameters
probThe probability.
alphaAlpha parameter.
betaBeta parameter.
Returns
The quantile corresponding to prob.

Definition at line 523 of file RandomTools.cpp.

References bpp::NumConstants::VERY_TINY().

Referenced by bpp::BetaDiscreteDistribution::qProb(), and randBeta().

◆ qChisq()

double RandomTools::qChisq ( double  prob,
double  v 
)
static

$\chi^2$ quantile function.

returns z so that Prob{x<z}=prob where x is Chi2 distributed with df=v returns -1 if in error. 0.000002<prob<0.999998 RATNEST FORTRAN by Best DJ & Roberts DE (1975) The percentage points of the Chi2 distribution. Applied Statistics 24: 385-388. (AS91) Converted into C by Ziheng Yang, Oct. 1993.

Parameters
probThe probability.
vnumber of degree of freedom.
Returns
The quantile corresponding to prob.

Definition at line 317 of file RandomTools.cpp.

Referenced by qGamma().

◆ qGamma()

static double bpp::RandomTools::qGamma ( double  prob,
double  alpha,
double  beta 
)
inlinestatic

The Gamma quantile function.

Parameters
probThe probability.
alphaAlpha parameter.
betaBeta parameter.
Returns
The quantile corresponding to prob.

Definition at line 444 of file RandomTools.h.

References qChisq().

Referenced by bpp::GammaDiscreteDistribution::qProb().

◆ qNorm() [1/2]

double RandomTools::qNorm ( double  prob)
static

Normal quantile function.

Returns z so that Prob{x<z}=prob where x ~ N(0,1) and (1e-12)<prob<1-(1e-12) returns (-9999) if in error Odeh RE & Evans JO (1974) The percentage points of the normal distribution. Applied Statistics 22: 96-97 (AS70)

Newer methods: Wichura MJ (1988) Algorithm AS 241: the percentage points of the normal distribution. 37: 477-484. Beasley JD & Springer SG (1977). Algorithm AS 111: the percentage points of the normal distribution. 26: 118-121.

Parameters
probThe probability.
Returns
The quantile corresponding to prob.

Definition at line 210 of file RandomTools.cpp.

Referenced by qNorm(), bpp::GaussianDiscreteDistribution::qProb(), and randGaussian().

◆ qNorm() [2/2]

double RandomTools::qNorm ( double  prob,
double  mu,
double  sigma 
)
static

Normal quantile function.

Returns z so that Prob{x<z}=prob where x ~ N(mu,sigma^2) and (1e-12)<prob<1-(1e-12) returns (-9999) if in error Odeh RE & Evans JO (1974) The percentage points of the normal distribution. Applied Statistics 22: 96-97 (AS70)

Newer methods: Wichura MJ (1988) Algorithm AS 241: the percentage points of the normal distribution. 37: 477-484. Beasley JD & Springer SG (1977). Algorithm AS 111: the percentage points of the normal distribution. 26: 118-121.

Parameters
probThe probability.
muThe mean of the distribution
sigmaThe standard deviation of the distribution
Returns
The quantile corresponding to prob.

Definition at line 226 of file RandomTools.cpp.

References qNorm().

◆ randBeta()

double RandomTools::randBeta ( double  alpha,
double  beta,
const RandomFactory generator = *DEFAULT_GENERATOR 
)
static
Returns
A random number drawn from a beta distribution.
Parameters
alphaThe alpha parameter.
betaThe beta parameter.
generatorThe uniform generator to use.

Definition at line 517 of file RandomTools.cpp.

References bpp::RandomFactory::drawNumber(), and qBeta().

Referenced by bpp::BetaDiscreteDistribution::randC().

◆ randExponential()

double RandomTools::randExponential ( double  mean,
const RandomFactory generator = *DEFAULT_GENERATOR 
)
static
Returns
A random number drawn from an exponential distribution.
Parameters
meanThe mean of the distribution.
generatorThe uniform generator to use.

Definition at line 96 of file RandomTools.cpp.

References giveRandomNumberBetweenZeroAndEntry().

Referenced by bpp::ExponentialDiscreteDistribution::randC(), and bpp::TruncatedExponentialDiscreteDistribution::randC().

◆ randGamma() [1/2]

double RandomTools::randGamma ( double  dblAlpha,
const RandomFactory generator = *DEFAULT_GENERATOR 
)
static
Returns
A random number drawn from a gamma distribution with unit scale (beta=1).
Parameters
dblAlphaThe alpha parameter.
generatorThe uniform generator to use.

Definition at line 80 of file RandomTools.cpp.

References DblGammaGreaterThanOne(), DblGammaLessThanOne(), and giveRandomNumberBetweenZeroAndEntry().

Referenced by bpp::GammaDiscreteDistribution::randC(), and randGamma().

◆ randGamma() [2/2]

double RandomTools::randGamma ( double  alpha,
double  beta,
const RandomFactory generator = *DEFAULT_GENERATOR 
)
static
Returns
A random number drawn from a gamma distribution.
Parameters
alphaThe alpha parameter.
betaThe beta parameter.
generatorThe uniform generator to use.

Definition at line 90 of file RandomTools.cpp.

References randGamma().

◆ randGaussian()

double RandomTools::randGaussian ( double  mean,
double  variance,
const RandomFactory generator = *DEFAULT_GENERATOR 
)
static
Returns
A random number drawn from a normal distribution.
Parameters
meanThe mean of the law.
varianceThe variance of the law.
generatorThe uniform generator to use.

Definition at line 75 of file RandomTools.cpp.

References bpp::RandomFactory::drawNumber(), and qNorm().

Referenced by bpp::GaussianDiscreteDistribution::randC().

◆ randMultinomial()

std::vector< size_t > RandomTools::randMultinomial ( size_t  n,
const std::vector< double > &  probs 
)
static

Get a random state from a set of probabilities/scores.

The input probabilities are scaled so that they sum to one. If 'x' probabilities are provided as input, the output vector will contain values between 0 and 'x-1'.

Parameters
nThe sample size.
probsThe set of intput probabilities.
Returns
A vector of int values corresponding to the output states. States are supposed to be in the same order as the input probabilities, the first state being '0'.

Definition at line 101 of file RandomTools.cpp.

References giveRandomNumberBetweenZeroAndEntry(), and bpp::VectorTools::sum().

◆ setSeed()

void RandomTools::setSeed ( long  seed)
static

Set the default generator seed.

Parameters
seedNew seed.

Definition at line 55 of file RandomTools.cpp.

Referenced by bpp::BppApplication::BppApplication().

Member Data Documentation

◆ DEFAULT_GENERATOR

RandomFactory * RandomTools::DEFAULT_GENERATOR = new Uniform01K(time(NULL))
static

Definition at line 95 of file RandomTools.h.


The documentation for this class was generated from the following files: