random

Random numbers

Syntax

R = random(name,A)

R = random(name,A,B)

R = random(name,A,B,C)

R = random(name,A,B,C,D)

R = random(pd)

R = random(___,sz1,...,szN)

R = random(___,sz)

Description

R = random(name,A) returns a random number from the one-parameter distribution family specified by name and the distribution parameter A.

R = random(name,A,B) returns a random number from the two-parameter distribution family specified by name and the distribution parameters A and B.

R = random(name,A,B,C) returns a random number from the three-parameter distribution family specified by name and the distribution parameters A, B, and C.

R = random(name,A,B,C,D) returns a random number from the four-parameter distribution family specified by name and the distribution parameters A, B, C, and D.

R = random(pd) returns a random number from the probability distribution object pd.

R = random(___,sz1,...,szN) generates an array of random numbers from the specified probability distribution using input arguments from any of the previous syntaxes, where sz1,...,szN indicates the size of each dimension.

R = random(___,sz) generates an array of random numbers from the specified probability distribution using input arguments from any of the previous syntaxes, where vector sz specifies size(r).

Examples

Generate One Random Number by Specifying Distribution Name and Parameters

Generate one random number from the normal distribution with the mean $$\mu$$ equal to 1 and the standard deviation $$\sigma$$ equal to 5. Specify the distribution name 'Normal' and the distribution parameters.

rng('default') % For reproducibility
mu = 1;
sigma = 5;
r = random('Normal',mu,sigma)

r = 3.6883

Generate One Random Number Using Distribution Object

Create a normal distribution object and generate one random number using the object.

Create a normal distribution object with the mean $$\mu$$ equal to 1 and the standard deviation $$\sigma$$ equal to 5.

mu = 1;
sigma = 5;
pd = makedist('Normal','mu',mu,'sigma',sigma);

Generate one random number from the distribution.

rng('default') % For reproducibility
r = random(pd)

r = 3.6883

Reset Random Number Generator

Save the current state of the random number generator. Then generate a random number from the Poisson distribution with rate parameter 5.

s = rng;
r = random('Poisson',5)

r = 5

Restore the state of the random number generator to s, and then create a new random number. The value is the same as before.

rng(s);
r1 = random('Poisson',5)

r1 = 5

Clone Size from Existing Array

Create a matrix of random numbers with the same size as an existing array. Use the stable distribution with shape parameters 2 and 0, scale parameter 1, and location parameter 0.

A = [3 2; -2 1];
sz = size(A);
R = random('Stable',2,0,1,0,sz)

R = 2×2

    0.7604   -3.1945
    2.5935    1.2193

You can combine the previous two lines of code into a single line.

R = random('Stable',2,0,1,0,size(A))

R = 2×2

    0.4508   -0.6132
   -1.8494    0.4845

Generate Multiple Random Numbers

Create a Weibull probability distribution object using the default parameter values.

pd = makedist('Weibull')

pd = 
  WeibullDistribution

  Weibull distribution
    A = 1
    B = 1

Generate random numbers from the distribution.

rng('default')  % For reproducibility
r = random(pd,10000,1);

Construct a histogram using 100 bins with a Weibull distribution fit.

histfit(r,100,'weibull')

Generate Multidimensional Array of Random Numbers

Create a standard normal probability distribution object.

pd = makedist('Normal')

pd = 
  NormalDistribution

  Normal distribution
       mu = 0
    sigma = 1

Generate a 2-by-3-by-2 array of random numbers from the distribution.

r = random(pd,[2,3,2])

r = 
r(:,:,1) =

    0.5377   -2.2588    0.3188
    1.8339    0.8622   -1.3077


r(:,:,2) =

   -0.4336    3.5784   -1.3499
    0.3426    2.7694    3.0349

Input Arguments

name — Probability distribution name

character vector or string scalar of probability distribution name

Probability distribution name, specified as one of the probability distribution names in this table.

name	Distribution	Input Parameter A	Input Parameter B	Input Parameter C	Input Parameter D
'Beta'	Beta Distribution	a first shape parameter	b second shape parameter	—	—
'Binomial'	Binomial Distribution	n number of trials	p probability of success for each trial	—	—
'BirnbaumSaunders'	Birnbaum-Saunders Distribution	β scale parameter	γ shape parameter	—	—
'Burr'	Burr Type XII Distribution	α scale parameter	c first shape parameter	k second shape parameter	—
'Chisquare' or 'chi2'	Chi-Square Distribution	ν degrees of freedom	—	—	—
'Exponential'	Exponential Distribution	μ mean	—	—	—
'Extreme Value' or 'ev'	Extreme Value Distribution	μ location parameter	σ scale parameter	—	—
'F'	F Distribution	ν1 numerator degrees of freedom	ν2 denominator degrees of freedom	—	—
'Gamma'	Gamma Distribution	a shape parameter	b scale parameter	—	—
'Generalized Extreme Value' or 'gev'	Generalized Extreme Value Distribution	k shape parameter	σ scale parameter	μ location parameter	—
'Generalized Pareto' or 'gp'	Generalized Pareto Distribution	k tail index (shape) parameter	σ scale parameter	μ threshold (location) parameter	—
'Geometric'	Geometric Distribution	p probability parameter	—	—	—
'Half Normal' or 'hn'	Half-Normal Distribution	μ location parameter	σ scale parameter	—	—
'Hypergeometric' or 'hyge'	Hypergeometric Distribution	m size of the population	k number of items with the desired characteristic in the population	n number of samples drawn	—
'InverseGaussian'	Inverse Gaussian Distribution	μ scale parameter	λ shape parameter	—	—
'Logistic'	Logistic Distribution	μ mean	σ scale parameter	—	—
'LogLogistic'	Loglogistic Distribution	μ mean of logarithmic values	σ scale parameter of logarithmic values	—	—
'LogNormal'	Lognormal Distribution	μ mean of logarithmic values	σ standard deviation of logarithmic values	—	—
'Pearson'	Pearson Distribution	μ mean	σ standard deviation	γ skewness	κ kurtosis
'Nakagami'	Nakagami Distribution	μ shape parameter	ω scale parameter	—	—
'Negative Binomial' or 'nbin'	Negative Binomial Distribution	r number of successes	p probability of success in a single trial	—	—
'Noncentral F' or 'ncf'	Noncentral F Distribution	ν1 numerator degrees of freedom	ν2 denominator degrees of freedom	δ noncentrality parameter	—
'Noncentral t' or 'nct'	Noncentral t Distribution	ν degrees of freedom	δ noncentrality parameter	—	—
'Noncentral Chi-square' or 'ncx2'	Noncentral Chi-Square Distribution	ν degrees of freedom	δ noncentrality parameter	—	—
'Normal'	Normal Distribution	μ mean	σ standard deviation	—	—
'Poisson'	Poisson Distribution	λ mean	—	—	—
'Rayleigh'	Rayleigh Distribution	b scale parameter	—	—	—
'Rician'	Rician Distribution	s noncentrality parameter	σ scale parameter	—	—
'Stable'	Stable Distribution	α first shape parameter	β second shape parameter	γ scale parameter	δ location parameter
'T'	Student's t Distribution	ν degrees of freedom	—	—	—
'tLocationScale'	t Location-Scale Distribution	μ location parameter	σ scale parameter	ν shape parameter	—
'Uniform'	Uniform Distribution (Continuous)	a lower endpoint (minimum)	b upper endpoint (maximum)	—	—
'Discrete Uniform' or 'unid'	Uniform Distribution (Discrete)	n maximum observable value	—	—	—
'Weibull' or 'wbl'	Weibull Distribution	a scale parameter	b shape parameter	—	—

Example: 'Normal'

A — First probability distribution parameter

scalar value | array of scalar values

First probability distribution parameter, specified as a scalar value or an array of scalar values.

If one or more of the input arguments A, B, C, and D are arrays, then the array sizes must be the same. In this case, random expands each scalar input into a constant array of the same size as the array inputs. See name for the definitions of A, B, C, and D for each distribution.

Data Types: single | double

B — Second probability distribution parameter

scalar value | array of scalar values

Second probability distribution parameter, specified as a scalar value or an array of scalar values.

If one or more of the input arguments A, B, C, and D are arrays, then the array sizes must be the same. In this case, random expands each scalar input into a constant array of the same size as the array inputs. See name for the definitions of A, B, C, and D for each distribution.

Data Types: single | double

C — Third probability distribution parameter

scalar value | array of scalar values

Third probability distribution parameter, specified as a scalar value or an array of scalar values.

If one or more of the input arguments A, B, C, and D are arrays, then the array sizes must be the same. In this case, random expands each scalar input into a constant array of the same size as the array inputs. See name for the definitions of A, B, C, and D for each distribution.

Data Types: single | double

D — Fourth probability distribution parameter

scalar value | array of scalar values

Fourth probability distribution parameter, specified as a scalar value or an array of scalar values.

If one or more of the input arguments A, B, C, and D are arrays, then the array sizes must be the same. In this case, random expands each scalar input into a constant array of the same size as the array inputs. See name for the definitions of A, B, C, and D for each distribution.

Data Types: single | double

pd — Probability distribution

probability distribution object

Probability distribution, specified as one of the probability distribution objects in this table.

Distribution Object	Function or App to Create Probability Distribution Object
BetaDistribution	makedist, fitdist, Distribution Fitter
BinomialDistribution	makedist, fitdist, Distribution Fitter
BirnbaumSaundersDistribution	makedist, fitdist, Distribution Fitter
BurrDistribution	makedist, fitdist, Distribution Fitter
ExponentialDistribution	makedist, fitdist, Distribution Fitter
ExtremeValueDistribution	makedist, fitdist, Distribution Fitter
GammaDistribution	makedist, fitdist, Distribution Fitter
GeneralizedExtremeValueDistribution	makedist, fitdist, Distribution Fitter
GeneralizedParetoDistribution	makedist, fitdist, Distribution Fitter
HalfNormalDistribution	makedist, fitdist, Distribution Fitter
InverseGaussianDistribution	makedist, fitdist, Distribution Fitter
KernelDistribution	fitdist, Distribution Fitter
LogisticDistribution	makedist, fitdist, Distribution Fitter
LoglogisticDistribution	makedist, fitdist, Distribution Fitter
LognormalDistribution	makedist, fitdist, Distribution Fitter
LoguniformDistribution	makedist
MultinomialDistribution	makedist
NakagamiDistribution	makedist, fitdist, Distribution Fitter
NegativeBinomialDistribution	makedist, fitdist, Distribution Fitter
NormalDistribution	makedist, fitdist, Distribution Fitter
Piecewise distribution with generalized Pareto distributions in the tails	paretotails
PiecewiseLinearDistribution	makedist
PoissonDistribution	makedist, fitdist, Distribution Fitter
RayleighDistribution	makedist, fitdist, Distribution Fitter
RicianDistribution	makedist, fitdist, Distribution Fitter
StableDistribution	makedist, fitdist, Distribution Fitter
tLocationScaleDistribution	makedist, fitdist, Distribution Fitter
TriangularDistribution	makedist
UniformDistribution	makedist
WeibullDistribution	makedist, fitdist, Distribution Fitter

sz1,...,szN — Size of each dimension (as separate arguments)

integer values

Size of each dimension, specified as integer values. For example, specifying 5,3,2 generates a 5-by-3-by-2 array of random numbers from the specified probability distribution.

If one or more of the input arguments A, B, C, and D are arrays, then the specified dimensions sz1,...,szN must match the common dimensions of A, B, C, and D after any necessary scalar expansion. The default values of sz1,...,szN are the common dimensions.

• If you specify a single value sz1, then R is a square matrix of size sz1-by-sz1.

• If the size of any dimension is 0 or negative, then R is an empty array.

• Beyond the second dimension, random ignores trailing dimensions with a size of 1. For example, specifying 3,1,1,1 produces a 3-by-1 vector of random numbers.

Example: 5,3,2

Data Types: single | double

sz — Size of each dimension (as a row vector)

row vector of integers

Size of each dimension, specified as a row vector of integers. For example, specifying [5 3 2] generates a 5-by-3-by-2 array of random numbers from the specified probability distribution.

If one or more of the input arguments A, B, C, and D are arrays, then the specified dimensions sz must match the common dimensions of A, B, C, and D after any necessary scalar expansion. The default values of sz are the common dimensions.

• If you specify a single value [sz1], then R is a square matrix of size sz1-by-sz1.

• If the size of any dimension is 0 or negative, then R is an empty array.

• Beyond the second dimension, random ignores trailing dimensions with a size of 1. For example, specifying [3 1 1 1] produces a 3-by-1 vector of random numbers.

Example: [5 3 2]

Data Types: single | double

Output Arguments

R — Random number

scalar value | array of scalar values

Random number generated from the specified probability distribution, returned as a scalar value or an array of scalar values with the dimensions specified by sz1,...,szN or sz.

If you specify distribution parameters A, B, C, or D, then each element in R is the random number generated from the distribution specified by the corresponding elements in A, B, C, and D.

Alternative Functionality

• random is a generic function that accepts either a distribution by its name name or a probability distribution object pd. It is faster to use a distribution-specific function, such as randn and normrnd for the normal distribution and binornd for the binomial distribution. For a list of distribution-specific functions, see Supported Distributions.

• To generate random numbers interactively, use randtool, a user interface for random number generation.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The input argument name must be a compile-time constant. For example, to use the normal distribution, include coder.Constant('Normal') in the -args value of codegen (MATLAB Coder).

• Code generation does not support the probability distribution object (pd) input argument.

For more information on code generation, see Introduction to Code Generation and General Code Generation Workflow.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2023b: Support for Pearson distributions

Starting in R2023b, random supports Pearson distributions.