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...

static int	giveIntRandomNumberBetweenZeroAndEntry (int 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 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 RandomFactory *	DEFAULT_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

bpp::RandomTools::RandomTools ( )

inline

Definition at line 72 of file RandomTools.h.

virtual bpp::RandomTools::~RandomTools ( )

inlinevirtual

Definition at line 73 of file RandomTools.h.

Member Function Documentation

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

staticprivate

Definition at line 138 of file RandomTools.cpp.

References giveRandomNumberBetweenZeroAndEntry(), and giveRandomNumberBetweenZeroAndEntry().

Referenced by randGamma().

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

staticprivate

Definition at line 182 of file RandomTools.cpp.

Referenced by randGamma().

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

static

Get a boolean random value.

Parameters

generator Random number generator to use.

Definition at line 70 of file RandomTools.cpp.

References giveRandomNumberBetweenZeroAndEntry().

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

vin	The vector to sample.
vout	[out] The output vector to fill, with the appropriate size.
replace	Should sampling be with replacement?

Returns: A vector which is a sample of v.

Exceptions

IndexOutOfBoundException	if the sample size exceeds the original size when sampling without replacement.
EmptyVectorException	if the vector is empty.

Author: Sylvain Gaillard

Definition at line 213 of file RandomTools.h.

References pickOne().

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 lower as the sampe size becomes close to the population size. In case the two are equal (pure permutations), the weigths have no effect at all.

Parameters

vin	The vector to sample.
w	The vector of weights.
vout	[out] The output vector to fill, with the appropriate size.
replace	Should sampling be with replacement?

Returns: A vector which is a sample of v.

Exceptions

IndexOutOfBoundException	if the sample size exceeds the original size when sampling without replacement.
EmptyVectorException	if the vector is empty.

Author: Julien Dutheil

Definition at line 292 of file RandomTools.h.

References pickOne().

int RandomTools::giveIntRandomNumberBetweenZeroAndEntry	(	int	entry,
		const RandomFactory &	generator = `*DEFAULT_GENERATOR`
	)

static

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

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

Parameters

entry	Max number to reach.
generator	Random number generator to use.

Definition at line 77 of file RandomTools.cpp.

Referenced by pickOne().

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

entry	Max number to reach.
generator	Random number generator to use.

Definition at line 62 of file RandomTools.cpp.

References bpp::RandomFactory::drawNumber().

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

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

x	the upper limit of the integration.
alpha,beta	the shape parameters.

Definition at line 666 of file RandomTools.cpp.

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

Referenced by pBeta().

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

staticprivate

functions for the computation of incompleteBeta

Definition at line 777 of file RandomTools.cpp.

References bpp::NumConstants::VERY_TINY().

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

staticprivate

Definition at line 891 of file RandomTools.cpp.

References bpp::NumConstants::VERY_TINY().

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

staticprivate

Definition at line 1007 of file RandomTools.cpp.

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

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

x	the upper limit of the integration.
alpha	the shape parameter.
ln_gamma_alpha	ln(Gamma(alpha)).

Definition at line 257 of file RandomTools.cpp.

Referenced by pGamma().

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,beta Alpha and Beta parameters.

Returns: $ln\left(Beta\left(\alpha,\beta\right)\right)$

Definition at line 519 of file RandomTools.cpp.

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

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

alpha Alpha parameter.

Returns: $ln\left(\Gamma\left(\alpha\right)\right)$

Definition at line 239 of file RandomTools.cpp.

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

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

inlinestatic

Definition at line 518 of file RandomTools.h.

References incompleteBeta().

Referenced by bpp::BetaDiscreteDistribution::Expectation(), and bpp::BetaDiscreteDistribution::pProb().

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

inlinestatic

$\chi^2$ cumulative probability function.

Parameters

x	The quantile for which the probability should be computed.
v	number of degree of freedom.

Returns: The corresponding probability of the quantile.

Definition at line 419 of file RandomTools.h.

References pGamma().

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

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

inlinestatic

$\Gamma$ cumulative probability function.

Parameters

x	The quantile for which the probability should be computed.
alpha	Alpha parameter.
beta	Beta parameter.

Returns: The corresponding probability of the quantile.

Exceptions

Exception If alpha or beta is invalid (<0).

Definition at line 448 of file RandomTools.h.

References incompleteGamma(), and lnGamma().

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

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

v	The vector of elements.
replace	If 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

EmptyVectorException if the vector is empty.

Author: Sylvain Gaillard

Definition at line 181 of file RandomTools.h.

References giveIntRandomNumberBetweenZeroAndEntry().

Referenced by getSample(), and getSample().

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

v	The vector of elements.
w	The vector of weight associated to the v elements.
replace	Should pick with replacement? (default: false)

Returns: On element of the vector.

Exceptions

EmptyVectorException if the vector is empty.

Author: Julien Dutheil

Definition at line 240 of file RandomTools.h.

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

double RandomTools::pNorm ( double z )

static

Normal cumulative function.

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

Parameters

z	the value.

Returns: The corresponding probability.

Definition at line 390 of file RandomTools.cpp.

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

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

static

Definition at line 384 of file RandomTools.cpp.

References pNorm().

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

prob	The probability.
alpha	Alpha parameter.
beta	Beta parameter.

Returns: The quantile corresponding to prob.

Definition at line 530 of file RandomTools.cpp.

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

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

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

prob	The probability.
v	number of degree of freedom.

Returns: The quantile corresponding to prob.

Definition at line 324 of file RandomTools.cpp.

Referenced by qGamma().

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

inlinestatic

The Gamma quantile function.

Parameters

prob	The probability.
alpha	Alpha parameter.
beta	Beta parameter.

Returns: The quantile corresponding to prob.

Definition at line 433 of file RandomTools.h.

References qChisq().

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

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

prob	The probability.

Returns: The quantile corresponding to prob.

Definition at line 217 of file RandomTools.cpp.

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

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

prob	The probability.
mu	The mean of the distribution
sigma	The standard deviation of the distribution

Returns: The quantile corresponding to prob.

Definition at line 233 of file RandomTools.cpp.

References qNorm().

double RandomTools::randBeta	(	double	alpha,
		double	beta,
		const RandomFactory &	generator = `*DEFAULT_GENERATOR`
	)

static

Returns: A random number drawn from a beta distribution.

Parameters

alpha	The alpha parameter.
beta	The beta parameter.
generator	The uniform generator to use.

Definition at line 524 of file RandomTools.cpp.

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

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

double RandomTools::randExponential	(	double	mean,
		const RandomFactory &	generator = `*DEFAULT_GENERATOR`
	)

static

Returns: A random number drawn from an exponential distribution.

Parameters

mean	The mean of the distribution.
generator	The uniform generator to use.

Definition at line 103 of file RandomTools.cpp.

References giveRandomNumberBetweenZeroAndEntry().

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

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

dblAlpha	The alpha parameter.
generator	The uniform generator to use.

Definition at line 87 of file RandomTools.cpp.

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

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

double RandomTools::randGamma	(	double	alpha,
		double	beta,
		const RandomFactory &	generator = `*DEFAULT_GENERATOR`
	)

static

Returns: A random number drawn from a gamma distribution.

Parameters

alpha	The alpha parameter.
beta	The beta parameter.
generator	The uniform generator to use.

Definition at line 97 of file RandomTools.cpp.

References randGamma().

double RandomTools::randGaussian	(	double	mean,
		double	variance,
		const RandomFactory &	generator = `*DEFAULT_GENERATOR`
	)

static

Returns: A random number drawn from a normal distribution.

Parameters

mean	The mean of the law.
variance	The variance of the law.
generator	The uniform generator to use.

Definition at line 82 of file RandomTools.cpp.

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

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

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

n	The sample size.
probs	The 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 108 of file RandomTools.cpp.

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

void RandomTools::setSeed ( long seed )

static

Set the default generator seed.

Parameters

seed New seed.

Definition at line 55 of file RandomTools.cpp.

Member Data Documentation

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:

Bpp/Numeric/Random/RandomTools.h
Bpp/Numeric/Random/RandomTools.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Static Private Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation