ncfrnd

R2026b

Noncentral F random numbers

Syntax

r = ncfrnd(nu1,nu2,delta)

r = ncfrnd(nu1,nu2,delta,sz1,...,szN)

r = ncfrnd(nu1,nu2,delta,sz)

Description

r = ncfrnd(nu1,nu2,delta) generates a random number drawn from the noncentral F distribution with nu1 numerator degrees of freedom, nu2 denominator degrees of freedom, and the noncentrality parameter delta.

r = ncfrnd(nu1,nu2,delta,sz1,...,szN) generates an array of random numbers, where sz1,...,szN indicates the size of each dimension.

r = ncfrnd(nu1,nu2,delta,sz) generates an array of random numbers, where the vector sz specifies size(r).

Examples

Generate Random Numbers from Noncentral F Distribution

Generate 5000 random numbers from a noncentral F distribution with nu1 numerator degrees of freedom, nu2 denominator degrees of freedom, and the noncentrality parameter delta.

rng(0,"twister") % For reproducibility
nu1 = 50;
nu2 = 30;
delta = 5;
r = ncfrnd(nu1,nu2,delta,[5000 1]);

Plot a histogram of the numbers.

histogram(r)

Input Arguments

nu1 — Numerator degrees of freedom

positive scalar | array of positive scalars

Numerator degrees of freedom, specified as a positive scalar or an array of positive scalars.

To generate random numbers from multiple distributions, specify one or more of the following input arguments using arrays: nu1, nu2, or delta. If one or more of the input arguments nu1, nu2, and delta are arrays, then the array sizes must be the same. In this case, ncfrnd expands each scalar input into a constant array of the same size as the array inputs.

Data Types: single | double

nu2 — Denominator degrees of freedom

positive scalar | array of positive scalars

Denominator degrees of freedom, specified as a positive scalar or an array of positive scalars.

To generate random numbers from multiple distributions, specify one or more of the following input arguments using arrays: nu1, nu2, or delta. If one or more of the input arguments nu1, nu2, and delta are arrays, then the array sizes must be the same. In this case, ncfrnd expands each scalar input into a constant array of the same size as the array inputs.

Data Types: single | double

delta — Noncentrality parameter

nonnegative scalar | array of nonnegative scalars

Noncentrality parameter, specified as a nonnegative scalar or an array of nonnegative scalars. When delta=0, the noncentral F distribution is equivalent to the F distribution.

To generate random numbers from multiple distributions, specify one or more of the following input arguments using arrays: nu1, nu2, or delta. If one or more of the input arguments nu1, nu2, and delta are arrays, then the array sizes must be the same. In this case, ncfrnd expands each scalar input into a constant array of the same size as the array inputs.

Data Types: single | double

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

integers

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

If one or more of the input arguments nu1, nu2, and delta are arrays, then the specified dimensions sz1,...,szN must match the common dimensions of nu1, nu2, and delta 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, ncfrnd ignores trailing dimensions with a size of 1. For example, specifying 3,1,1,1 produces a 3-by-1 vector of random numbers.

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 one or more of the input arguments nu1, nu2, and delta are arrays, then the specified dimensions sz must match the common dimensions of nu1, nu2, and delta 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, ncfrnd ignores trailing dimensions with a size of 1. For example, specifying [3,1,1,1] produces a 3-by-1 vector of random numbers.

Data Types: single | double

Output Arguments

r — Random numbers

scalar value | array of scalar values

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 nu1, nu2, and delta.

Alternative Functionality

• ncfrnd is a function specific to the noncentral F distribution. Statistics and Machine Learning Toolbox™ also offers the generic function random, which supports various probability distributions. To use random, specify the probability distribution name and its parameters. Note that the distribution-specific function ncfrnd is faster than the generic function random.

• To generate random numbers interactively, use the Random Number Generation Tool.

References

[1] Johnson, N., and S. Kotz. Distributions in Statistics: Continuous Univariate Distributions-2. Hoboken, NJ: John Wiley & Sons, Inc., 1970, pp. 189–200.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

The generated code can return a different sequence of numbers than MATLAB^® if either of the following is true:

• The output is nonscalar.

• An input parameter is invalid for the distribution.

For more information on code generation, see Introduction to Code Generation for Statistics and Machine Learning Functions and Overview of Code Generation Using MATLAB Coder (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

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