  ### B.12 Random-number generators

Random-numbers are generated using a common general seed number. The seed is set to 42 every time BayES starts and is advanced appropriately every time a random-number generator is called. The seed can be set at any point in a script ﬁle using the statement:

seed(<positive integer>);

Note that when a model function is called, another seed is used, which is internal to the particular model and does not advance the general seed. This allows reproducibility of results irrespective of how many random numbers, if any, have been generated in statements before the call to the model function. The model’s internal seed is also set to 42 and this value can be altered by passing an optional argument of the form:

... , "seed"=<positive integer>, ...

to the model function.

#### B.12.1 Univariate distributions

The generic syntax for calling a random-number generator for a univariate distribution is:

W = distributionName( <parameters> $\left[$, M, N$\right]$);

where distributionName is the name of a distribution for which BayES provides random numbers (see table below), and <parameters> is a list of the distribution’s parameters, as described in section B.11. These parameters must be separated by commas if more than one parameter needs to be supplied. The size of the return matrix, W, depends on the size of the parameters passed as arguments to the function and on whether the optional arguments, M and N, are supplied:

• if the distribution’s parameters are scalars and no optional arguments are supplied then W is an $1\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}1$ matrix which contains a random draw from the respective distribution.
• if the distribution’s parameters are scalars then M and N can be used to request multiple random numbers. W in this case will be an $M\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}N$ matrix which contains random draws from the distribution. If M is supplied then N must be supplied as well.
• if the distribution’s parameters are matrices and their dimensions match (if more than one parameter needs to be supplied) then W will have the same size as the parameters and it will contain random draws from the distribution, generated by combining parameters in an element-wise fashion. Since the dimensions of W are determined by the dimensions of the distribution’s parameters, M and N must not be supplied.
• for distributions which require specifying more than one parameter, if one of the parameters supplied is a scalar and another a matrix, then the scalar parameter is expanded to match the dimensions of the matrix parameter. In this case W has the same size as the matrix parameter. Again, M and N must not be supplied because the dimensions of W are determined by the dimensions of the distribution’s parameters.

The following two tables document the random-number generating functions for continuous and discrete random variables, respectively.

 Syntax Arguments and performed function W = betarnd(alpha, beta $\left[$, M, N $\right]$); W is a matrix of random numbers from a beta distribution with shape parameters alpha and beta. alpha must be a matrix with positive entries beta must be a matrix with positive entries M must be a positive integer N must be a positive integer see also betapdf, betacdf W = chi2rnd(p $\left[$, M, N $\right]$); W is a matrix of random numbers from a chi-squared distribution with p degrees of freedom. p must be a matrix with positive entries M must be a positive integer N must be a positive integer see also chi2pdf, chi2cdf W = exprnd(lambda $\left[$, M, N $\right]$); W is a matrix of random numbers from an exponential distribution with rate parameter lambda. lambda must be a matrix with positive entries M must be a positive integer N must be a positive integer see also exppdf, expcdf W = evrnd(mu, sigma $\left[$, M, N $\right]$); W is a matrix of random numbers from a type-I extreme-value distribution with location parameter mu and scale parameter sigma mu must be a matrix sigma must be a matrix with positive entries M must be a positive integer N must be a positive integer see also evpdf, evcdf W = frnd(p1, p2 $\left[$, M, N $\right]$); W is a matrix of random numbers from Fisher’s F distribution with numerator degrees of freedom p1 and denominator degrees of freedom p2. p1 must be a matrix with positive entries p2 must be a matrix with positive entries M must be a positive integer N must be a positive integer see also fpdf, fcdf W = gamrnd(alpha, beta $\left[$, M, N $\right]$); W is a matrix of random numbers from a gamma distribution with shape parameter alpha and rate parameter beta. alpha must be a matrix with positive entries beta must be a matrix with positive entries M must be a positive integer N must be a positive integer see also gampdf, gamcdf W = logisticrnd(mu, s $\left[$, M, N $\right]$); W is a matrix of random numbers from a logistic distribution with mean mu and scale parameter s (variance equal to $\frac{{\mathtt{s}}^{2}{\pi }^{2}}{3}$). mu must be a matrix s must be a matrix with positive entries M must be a positive integer N must be a positive integer see also logisticpdf, logisticcdf W = logitnrnd(mu, sigma $\left[$, M, N $\right]$); W is a matrix of random numbers from a logit-normal distribution with location parameter mu and scale parameter sigma. mu must be a matrix sigma must be a matrix with positive entries M must be a positive integer N must be a positive integer see also logitnpdf, logitncdf W = lognrnd(mu, sigma $\left[$, M, N $\right]$); W is a matrix of random numbers from a log-normal distribution with location parameter mu and scale parameter sigma. mu must be a matrix sigma must be a matrix with positive entries M must be a positive integer N must be a positive integer see also lognpdf, logncdf W = normrnd(mu, sigma $\left[$, M, N $\right]$); W is a matrix of random numbers from a normal distribution with mean mu and standard deviation sigma. mu must be a matrix sigma must be a matrix with positive entries M must be a positive integer N must be a positive integer see also normpdf, normcdf W = trnd(p $\left[$, M, N $\right]$); W is a matrix of random numbers from a t distribution with p degrees of freedom. p must be a matrix M must be a positive integer N must be a positive integer see also tpdf, tcdf W = truncnrnd(mu, sigma $\left[$, M, N $\right]$); W is a matrix of random numbers from a normal distribution with location parameter mu and scale parameter sigma, truncated from below at zero. mu must be a matrix sigma must be a matrix with positive entries M must be a positive integer N must be a positive integer see also truncnpdf, truncncdf W = unifrnd($\left[$ M, N $\right]$); W is a matrix of random numbers from a uniform distribution on the interval $\left[0,1\right]$. M must be a positive integer N must be a positive integer W = wblrnd(alpha, beta $\left[$, M, N $\right]$); W is a matrix of random numbers from a Weibull distribution with shape parameter alpha and scale parameter beta. alpha must be a matrix with positive entries beta must be a matrix with positive entries M must be a positive integer N must be a positive integer see also wblpdf, wblcdf
 Syntax Arguments and performed function W = catrnd(p $\left[$, M, N $\right]$); W is a matrix of random numbers from a categorical distribution with probability vector speciﬁed in each row of p. The number of outcomes is deduced from the number of columns of p and numbering starts at 0. That is, if p is a $1\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$ vector, the possible values of the random variable are $\left\{0,1,\dots ,k-1\right\}$ and the probability of obtaining outcome $j$ is equal to the ${\left(j+1\right)}^{\text{th}}$ element of p. p must be a matrix with non-negative entries and values such that each row sums to unity M must be a positive integer N must be a positive integer W = binomrnd(n, p $\left[$, M, N $\right]$); W is a matrix of random numbers from a binomial distribution with n trials and probability of success in each trial p. n must be a matrix with non-negative entries p must be a matrix with entries between zero and one M must be a positive integer N must be a positive integer Note that the function allows for non-integer values of n by replacing the factorials in the expressions for the probability mass and cumulative density functions by the Gamma function.see also binompdf, binomcdf W = nbinomrnd(n, p $\left[$, M, N $\right]$); W is a matrix of random numbers from a negative binomial distribution with n failures before stopping and probability of success in each trial p. n must be a matrix with positive entries p must be a matrix with entries between zero and one M must be a positive integer N must be a positive integer Note that the function allows for non-integer values of n by replacing the factorials in the expressions for the probability mass and cumulative density functions by the Gamma function.see also nbinompdf, nbinomcdf W = poissonrnd(lambda $\left[$, M, N $\right]$); W is a matrix of random numbers from a Poisson distribution with rate parameter lambda. lambda must be a matrix with positive entries M must be a positive integer N must be a positive integer see also poissonpdf, poissoncdf

#### B.12.2 Multivariate distributions

The following table describes statements that are used to generate random numbers from multivariate distributions. The general format of these statements is similar to random-number generators for univariate distributions, but, because multivariate random-number generators return vectors or matrices, the optional dimension arguments do not have the usual meaning: these generators can generate $M$ or one random draw per call.

 Syntax Mathematical expression Arguments and return values W = mvnrnd(mu, V $\left[$, M $\right]$); $f\left(\mathbf{x}\right)=\frac{|\mathbf{V}{|}^{-\frac{1}{2}}{e}^{{\left(\mathbf{x}\phantom{\rule{0.3em}{0ex}}-\phantom{\rule{0.3em}{0ex}}\mu \right)}^{\prime }{\mathbf{V}}^{-1}\left(\mathbf{x}\phantom{\rule{0.3em}{0ex}}-\phantom{\rule{0.3em}{0ex}}\mu \right)}}{{\left(2\pi \right)}^{\frac{k}{2}}}$ W is an $M\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$ matrix of random numbers from a $k$-variate normal distribution with mean mu (either $k\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}1$ or $1\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$) and variance matrix V ($k\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$). mu must be a matrix with at least one dimension equal to 1 V must be a square and positive-deﬁnite matrix the dimensions of mu and V must match: if V is $k\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$ then mu must be either $k\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}1$ or $1\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$ M must be a positive integer W = wishrnd(V, p); $f\left(\mathbf{X}\right)=\frac{|\mathbf{X}{|}^{\frac{p-k-1}{2}}{e}^{-\frac{1}{2}\mathrm{tr}\left({\mathbf{V}}^{-1}\mathbf{X}\right)}}{{2}^{\frac{pk}{2}}|\mathbf{V}{|}^{\frac{p}{2}}{\Gamma }_{k}\left(\frac{p}{2}\right)}$ W is a $k\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$ matrix of random numbers from a $k$-dimensional Wishart distribution with scale matrix V ($k\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$) and p degrees of freedom. V must be a square and positive-deﬁnite matrix p must be a positive number W = iwishrnd(V, p); $f\left(\mathbf{X}\right)=\frac{|\mathbf{X}{|}^{-\frac{p+k+1}{2}}{e}^{-\frac{1}{2}\mathrm{tr}\left(\mathbf{V}{\mathbf{X}}^{-1}\right)}}{{2}^{\frac{pk}{2}}|\mathbf{V}{|}^{-\frac{p}{2}}{\Gamma }_{k}\left(\frac{p}{2}\right)}$ W is a $k\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$ matrix of random numbers from a $k$-dimensional inverse-Wishart distribution with scale matrix V ($k\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$) and p degrees of freedom. V must be a square and positive-deﬁnite matrix p must be a positive number W = drchrnd(alpha $\left[$, M $\right]$); $f\left(\mathbf{x}\right)=\frac{1}{B\left(\alpha \right)}\prod _{j=1}^{k}{x}_{j}^{{\alpha }_{j}-1}$ W is an $M\phantom{\rule{0.3em}{0ex}}×\phantom{\rule{0.3em}{0ex}}k$ matrix of random numbers from a $k$-dimensional Dirichlet distribution with concentration parameters speciﬁed in each row of alpha. The dimension of the distribution, $k\ge 2$, is inferred by the number of columns of alpha. alpha must be a matrix of positive numbers with at least 2 columns M must be a positive integer    