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

example

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

example

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

example

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

example

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

collapse all

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

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

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

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

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')` 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

collapse all

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

`name`DistributionInput Parameter `A`Input Parameter `B`Input Parameter `C`Input Parameter `D`
`'Beta'`Beta Distributiona first shape parameterb second shape parameter
`'Binomial'`Binomial Distributionn number of trialsp probability of success for each trial
`'BirnbaumSaunders'`Birnbaum-Saunders Distributionβ scale parameterγ shape parameter
`'Burr'`Burr Type XII Distributionα scale parameterc first shape parameterk 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 Distributiona shape parameterb scale parameter
`'Generalized Extreme Value'` or `'gev'`Generalized Extreme Value Distributionk shape parameterσ scale parameterμ location parameter
`'Generalized Pareto'` or `'gp'`Generalized Pareto Distributionk tail index (shape) parameterσ scale parameterμ threshold (location) parameter
`'Geometric'`Geometric Distributionp probability parameter
`'Half Normal'` or `'hn'`Half-Normal Distributionμ location parameterσ scale parameter
`'Hypergeometric'` or `'hyge'`Hypergeometric Distributionm size of the populationk number of items with the desired characteristic in the populationn 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
`'Nakagami'`Nakagami Distributionμ shape parameterω scale parameter
`'Negative Binomial'` or `'nbin'`Negative Binomial Distributionr number of successesp 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 Distributionb scale parameter
`'Rician'`Rician Distributions 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 Distributiona scale parameterb shape parameter

Example: `'Normal'`

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`

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`

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`

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`

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

Distribution ObjectFunction 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

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`

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

collapse all

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.