bpp-core3  3.0.0
bpp::RandomTools Class Reference

Utilitary function dealing with random numbers. More...

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

Public Member Functions

 RandomTools ()
 
virtual ~RandomTools ()
 

Static Public Member Functions

static void setSeed (std::mt19937::result_type seed)
 Set the default generator seed. More...
 
static double giveRandomNumberBetweenZeroAndEntry (double entry)
 Get a double random value (between 0 and specified range). More...
 
static bool flipCoin (double prob=0.5)
 Get a boolean random value. More...
 
template<class intType >
static intType giveIntRandomNumberBetweenZeroAndEntry (intType entry)
 Get an integer random value (between 0 and specified range). More...
 
static double randGaussian (double mean, double variance)
 
static double randGamma (double alpha)
 
static double randGamma (double alpha, double beta)
 
static double randBeta (double alpha, double beta)
 
static double randExponential (double mean)
 
template<class T >
static T pickOne (std::vector< T > &v, bool replace=false)
 Pick (and extract) one element randomly in a vector and return it. More...
 
template<class T >
static T pickOne (const std::vector< T > &v)
 Pick one element randomly in a vector and return it. More...
 
template<class T >
static void getSample (const std::vector< T > &vin, std::vector< T > &vout, bool replace=false)
 Sample a vector. More...
 
template<class T >
static T pickOne (std::vector< T > &v, std::vector< double > &w, bool replace=false)
 Pick one element in a vector, with associated probability weights. More...
 
template<class T >
static T pickOne (const std::vector< T > &v, const std::vector< double > &w)
 Pick one element in a vector, with associated probability weights. More...
 
static size_t pickFromCumSum (const std::vector< double > &w)
 Pick one index from a cumsum vector of probabilities. More...
 
template<class T >
static void getSample (const std::vector< T > &vin, const std::vector< double > &w, std::vector< T > &vout, bool replace=false)
 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)
 $\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 std::random_device RANDOM_DEVICE
 
static std::mt19937 DEFAULT_GENERATOR
 

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)
 
static double DblGammaLessThanOne (double dblAlpha)
 

Detailed Description

Utilitary function dealing with random numbers.

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

Most of these function are provided for convenience, directly using the "random" library might prove more efficient.

Definition at line 34 of file RandomTools.h.

Constructor & Destructor Documentation

◆ RandomTools()

bpp::RandomTools::RandomTools ( )
inline

Definition at line 37 of file RandomTools.h.

◆ ~RandomTools()

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

Definition at line 38 of file RandomTools.h.

References incompletebetafe(), incompletebetafe2(), and incompletebetaps().

Member Function Documentation

◆ DblGammaGreaterThanOne()

double RandomTools::DblGammaGreaterThanOne ( double  dblAlpha)
staticprivate

Definition at line 43 of file RandomTools.cpp.

References giveRandomNumberBetweenZeroAndEntry().

Referenced by pBeta().

◆ DblGammaLessThanOne()

double RandomTools::DblGammaLessThanOne ( double  dblAlpha)
staticprivate

Definition at line 87 of file RandomTools.cpp.

Referenced by pBeta().

◆ flipCoin()

static bool bpp::RandomTools::flipCoin ( double  prob = 0.5)
inlinestatic

Get a boolean random value.

Parameters
probProbability of getting 'true'.

Definition at line 89 of file RandomTools.h.

◆ getSample() [1/2]

template<class T >
static void bpp::RandomTools::getSample ( const std::vector< T > &  vin,
std::vector< T > &  vout,
bool  replace = false 
)
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 227 of file RandomTools.h.

References DEFAULT_GENERATOR, and 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 
)
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
vin[in] The vector to sample.
w[in] The vector of weights.
vout[out] The output vector to fill, with the appropriate size already set.
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 383 of file RandomTools.h.

References pickOne(), qNorm(), and randMultinomial().

◆ giveIntRandomNumberBetweenZeroAndEntry()

template<class intType >
static intType bpp::RandomTools::giveIntRandomNumberBetweenZeroAndEntry ( intType  entry)
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.

Definition at line 103 of file RandomTools.h.

◆ giveRandomNumberBetweenZeroAndEntry()

static double bpp::RandomTools::giveRandomNumberBetweenZeroAndEntry ( double  entry)
inlinestatic

◆ 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 549 of file RandomTools.cpp.

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

Referenced by pBeta(), and pGamma().

◆ incompletebetafe()

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

functions for the computation of incompleteBeta

Definition at line 660 of file RandomTools.cpp.

References bpp::NumConstants::VERY_TINY().

Referenced by ~RandomTools().

◆ incompletebetafe2()

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

Definition at line 771 of file RandomTools.cpp.

References bpp::NumConstants::VERY_TINY().

Referenced by ~RandomTools().

◆ incompletebetaps()

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

Definition at line 887 of file RandomTools.cpp.

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

Referenced by ~RandomTools().

◆ 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 143 of file RandomTools.cpp.

Referenced by lnGamma(), and 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 405 of file RandomTools.cpp.

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

◆ lnGamma()

static double bpp::RandomTools::lnGamma ( double  alpha)
inlinestatic

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

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

Definition at line 472 of file RandomTools.h.

References incompleteGamma(), and qChisq().

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 516 of file RandomTools.h.

References pGamma().

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

◆ pGamma()

static double bpp::RandomTools::pGamma ( double  x,
double  alpha,
double  beta 
)
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 545 of file RandomTools.h.

References incompleteBeta(), incompleteGamma(), lnBeta(), lnGamma(), and pNorm().

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

◆ pickFromCumSum()

static size_t bpp::RandomTools::pickFromCumSum ( const std::vector< double > &  w)
inlinestatic

Pick one index from a cumsum vector of probabilities.

Last probability of the vector is assumed to be one.

Parameters
wThe vector of cumsumed weights.
Returns
An index from the vector.
Exceptions
EmptyVectorExceptionif the vector is empty.
Author
Laurent Guéguen

Definition at line 345 of file RandomTools.h.

References giveRandomNumberBetweenZeroAndEntry().

◆ pickOne() [1/4]

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

Pick (and extract) 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, in which case the vector will lost one element).
Returns
One element of the vector.
Exceptions
EmptyVectorExceptionif the vector is empty.
Author
Sylvain Gaillard

Definition at line 175 of file RandomTools.h.

Referenced by getSample().

◆ pickOne() [2/4]

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

Pick one element randomly in a vector and return it.

Parameters
vThe vector of elements.
Returns
One element of the vector.
Exceptions
EmptyVectorExceptionif the vector is empty.
Author
Sylvain Gaillard

Definition at line 201 of file RandomTools.h.

◆ pickOne() [3/4]

template<class T >
static T bpp::RandomTools::pickOne ( std::vector< T > &  v,
std::vector< double > &  w,
bool  replace = false 
)
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
One element of the vector.
Exceptions
EmptyVectorExceptionif the vector is empty.
Author
Julien Dutheil

Definition at line 266 of file RandomTools.h.

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

◆ pickOne() [4/4]

template<class T >
static T bpp::RandomTools::pickOne ( const std::vector< T > &  v,
const std::vector< double > &  w 
)
inlinestatic

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

Pick one element randomly in a vector and return it, with no change in the original vector.

Parameters
vThe vector of elements.
wThe vector of weight associated to the v elements.
Returns
One element of the vector.
Exceptions
EmptyVectorExceptionif the vector is empty.
Author
Julien Dutheil

Definition at line 312 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 276 of file RandomTools.cpp.

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

◆ pNorm() [2/2]

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

Definition at line 270 of file RandomTools.cpp.

References pNorm().

◆ qBeta()

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

The Beta quantile function.

Code adapted from Ziheng Yang's PAML. Original comment from the PAML package: Cran, G. W., K. J. Martin and G. E. Thomas (1977). Remark AS R19 and Algorithm AS 109, Applied Statistics, 26(1), 111-114. Remark AS R83 (v.39, 309-310) and correction (v.40(1) p.236).

My own implementation of the algorithm did not bracket the variable well. This version is Adpated from the pbeta and qbeta routines from "R : A Computer Language for Statistical Data Analysis". It fails for extreme values of p and q as well, although it seems better than my previous version. Ziheng Yang, May 2001

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

Definition at line 416 of file RandomTools.cpp.

Referenced by pBeta(), 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 210 of file RandomTools.cpp.

Referenced by lnGamma(), and 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 530 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 122 of file RandomTools.cpp.

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

◆ 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 138 of file RandomTools.cpp.

References qNorm().

◆ randBeta()

double RandomTools::randBeta ( double  alpha,
double  beta 
)
static
Returns
A random number drawn from a beta distribution.
Parameters
alphaThe alpha parameter.
betaThe beta parameter.

Definition at line 410 of file RandomTools.cpp.

References qBeta().

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

◆ randExponential()

static double bpp::RandomTools::randExponential ( double  mean)
inlinestatic
Returns
A random number drawn from an exponential distribution.
Parameters
meanThe mean of the distribution.

Definition at line 154 of file RandomTools.h.

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

◆ randGamma() [1/2]

static double bpp::RandomTools::randGamma ( double  alpha)
inlinestatic
Returns
A random number drawn from a gamma distribution with unit scale (beta=1).
Parameters
alphaThe alpha parameter.

Definition at line 126 of file RandomTools.h.

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

◆ randGamma() [2/2]

static double bpp::RandomTools::randGamma ( double  alpha,
double  beta 
)
inlinestatic
Returns
A random number drawn from a gamma distribution.
Parameters
alphaThe alpha parameter.
betaThe beta parameter.

Definition at line 137 of file RandomTools.h.

References randBeta().

◆ randGaussian()

static double bpp::RandomTools::randGaussian ( double  mean,
double  variance 
)
inlinestatic
Returns
A random number drawn from a normal distribution.
Parameters
meanThe mean of the law.
varianceThe variance of the law.

Definition at line 116 of file RandomTools.h.

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 13 of file RandomTools.cpp.

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

Referenced by getSample().

◆ setSeed()

static void bpp::RandomTools::setSeed ( std::mt19937::result_type  seed)
inlinestatic

Set the default generator seed.

Parameters
seedNew seed.

Definition at line 68 of file RandomTools.h.

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

Member Data Documentation

◆ DEFAULT_GENERATOR

std::mt19937 RandomTools::DEFAULT_GENERATOR
static

Definition at line 61 of file RandomTools.h.

Referenced by getSample().

◆ RANDOM_DEVICE

std::random_device RandomTools::RANDOM_DEVICE
static

Definition at line 60 of file RandomTools.h.


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