pearsrnd

Pearson system random numbers

Syntax

r = pearsrnd(mu,sigma,skew,kurt)

r = pearsrnd(mu,sigma,skew,kurt,sz1,...,szN)

r = pearsrnd(mu,sigma,skew,kurt,sz)

[r,type] = pearsrnd(___)

[r,type,coefs] = pearsrnd(___)

Description

r = pearsrnd(mu,sigma,skew,kurt) generates a random number drawn from the Pearson distribution with mean mu, standard deviation sigma, skewness skew, and kurtosis kurt.

Note

Because r is a random sample, its sample moments, especially the skewness and kurtosis, typically differ somewhat from the specified distribution moments.

pearsrnd uses the definition of kurtosis for which a normal distribution has a kurtosis of 3. Some definitions of kurtosis subtract 3, so that a normal distribution has a kurtosis of 0. The pearsrnd function does not use this convention.

r = pearsrnd(mu,sigma,skew,kurt,sz1,...,szN) generates an array of random numbers, where sz1,...,szN indicates the size of each dimension.

r = pearsrnd(mu,sigma,skew,kurt,sz) generates an array of random numbers, where vector sz specifies size(r).

[r,type] = pearsrnd(___) returns the type of the specified distribution within the Pearson system using any of the input argument combinations in the previous syntaxes. type is a scalar integer from 0 to 7. Set sz to 0 to identify the distribution type without generating any random values.

[r,type,coefs] = pearsrnd(___) returns the coefficients coefs of the quadratic polynomial that defines the distribution via the differential equation

$$\frac{p\text{'}(x)}{p(x)}=-\frac{a+(x-\mu )}{b_0+b_1(x-\mu )+b_2{(x-\mu )}^2},$$

Examples

Generate Pearson Random Values

Define the variables mu, sigma, skew, and kurt, which contain values for the mean, standard deviation, skewness, and kurtosis of a Pearson distribution, respectively. These parameters correspond to a type 0, standard normal distribution.

mu = 0;
sigma = 1;
skew = 0;
kurt = 3;
rng("twister") % For reproducibility
[r,type,coefs] = pearsrnd(mu,sigma,skew,kurt) % Equivalent to randn(1,1)

r = 
0.5377

type = 
0

coefs = 1×3

     1     0     0

Generate an Array of Random Values from Pearson Distributions

Generate an array of random values from Pearson distributions with varying mean values. The software performs scalar expansion for sigma values implicitly.

mu = [-1,0,1];
sigma = 2;
skew = 1;
kurtosis = 3;
rng("twister") % for reproducibility
r = pearsrnd(mu,sigma,skew,kurtosis)

r = 1×3

   -0.0217   -1.5638    0.3768

The generated array has the same dimensions as mu (1-by-3).

Input Arguments

mu — Mean

scalar | numeric array

Mean of the Pearson distribution, specified as a scalar or a numeric array.

To specify multiple distributions, specify either mu or sigma (or both) using arrays. If either mu or sigma is an array, then the array sizes must be the same. In this case, pearsrnd expands each scalar input into a constant array of the same size as the array inputs.

Example: [0 1 2; 0 1 2]

Data Types: single | double

sigma — Standard deviation

positive scalar | numeric array of positive values

Standard deviation of the Pearson distribution, specified as a positive scalar or a numeric array of positive values.

To specify multiple distributions, specify either mu or sigma (or both) using arrays. If either mu or sigma is an array, then the array sizes must be the same. In this case, pearsrnd expands each scalar input into a constant array of the same size as the array inputs.

Example: [1 1 1; 2 2 2]

Data Types: single | double

skew — Skewness

scalar

Skewness for the Pearson distribution, specified as a scalar. The value of skew must be less than sqrt(kurt - 1). For more information, see Skewness.

Example: 3

Data Types: single | double

kurt — Kurtosis

scalar

Kurtosis for the Pearson distribution, specified as a scalar. The value of kurt must be greater than skew^2 + 1. For more information, see Kurtosis.

Example: 11

Data Types: single | double

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

integers

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

If either mu or sigma is an array, then the specified dimensions sz1,...,szN must match the common dimensions of mu and sigma 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, pearsrnd 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 probability distribution.

If either mu or sigma is an array, then the specified dimensions sz must match the common dimensions of mu and sigma 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, pearsrnd 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 — Normal random numbers

scalar value | array of scalar values

Normal random numbers, returned as a scalar value or an array of scalar values with the dimensions specified by sz1,...,szN or sz. Each element in r is the random number generated from the distribution specified by the corresponding elements in mu and sigma.

type — Type of Pearson distribution

integer from interval [0 7] | NaN

Type of Pearson distribution used to generate random numbers, returned as an integer from the interval [0 7] or NaN. If the distribution parameters are invalid, pearsrnd returns NaN.

This table describes the distribution corresponding to each Pearson distribution type.

Pearson Distribution Type	Description
0	Normal
1	4-parameter beta
2	Symmetric 4-parameter beta
3	3-parameter gamma
4	Distribution specific to the Pearson system
5	Inverse 3-parameter gamma
6	F location-scale
7	Student's t location-scale

coefs — Quadratic polynomial coefficients

numeric 1-by-3 vector

Quadratic polynomial coefficients, returned as a numeric 1-by-3 vector. The ith element of coefs is the coefficient $$b_i$$ in the differential equation

$$\frac{p\text{'}(x)}{p(x)}=-\frac{a+(x-\mu )}{b_0+b_1(x-\mu )+b_2{(x-\mu )}^2},$$

which defines the Pearson distribution probability density function (pdf) $$p(x)$$.

References

[1] Johnson, N.L., S. Kotz, and N. Balakrishnan (1994) Continuous Univariate Distributions, Volume 1, Wiley-Interscience, Pg 15, Eqn 12.33.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• mu and sigma must be scalars.

• The generated code matches MATLAB^® only when generated output r is scalar.

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 in R2006a