randsample

Random sample

Syntax

y = randsample(n,k)

y = randsample(population,k)

y = randsample(___,replacement)

y = randsample(n,k,true,w)

y = randsample(population,k,true,w)

y = randsample(s,___)

Description

y = randsample(n,k) returns k values sampled uniformly at random, without replacement, from the integers 1 to n.

y = randsample(population,k) returns a vector of k values sampled uniformly at random, without replacement, from the values in the vector population.

y = randsample(___,replacement) returns a sample taken with replacement if replacement is true, or without replacement if replacement is false. Specify replacement following any of the input argument combinations in the previous syntaxes.

y = randsample(n,k,true,w) uses a vector of non-negative weights, w, whose length is n, to determine the probability that an integer i is selected as an entry for y.

y = randsample(population,k,true,w) uses a vector of nonnegative weights, w, of the same length as the vector population, to determine the probability that a value population(i) is selected as an entry for y.

y = randsample(s,___) uses the stream s for random number generation. The option s can precede any of the input arguments in the previous syntaxes. s is a member of the RandStream class.

Examples

Sample Unique Value from Range

Draw a single value from the integers 1 through 10.

n = 10;
x = randsample(n,1)

x = 
9

Sample from Population Vector

Create the random seed for reproducibility of the results.

s = RandStream('mlfg6331_64'); 

Draw a single value from the vector [10:20].

population = 10:20;
y = randsample(s,population,1)

y = 
17

Generate Random Sequence for Specified Probabilities

Create the random number stream for reproducibility.

s = RandStream('mlfg6331_64');

Choose 48 characters randomly and with replacement from the sequence ACGT, according to the specified probabilities.

R = randsample(s,'ACGT',48,true,[0.15 0.35 0.35 0.15])

R = 
'GGCGGCGCAAGGCGCCGGACCTGGCTGCACGCCGTTCCCTGCTACTCG'

Set Random Number Stream

Create the random number stream for reproducibility.

s = RandStream('mlfg6331_64'); 

Draw five values with replacement from the integers 1:10.

y = randsample(s,10,5,true)

y = 5×1

     7
     8
     5
     7
     8

Input Arguments

n — Upper limit of range

positive integer

Upper limit of the range (1 to n) from which to sample, specified as a positive integer. By default, randsample samples uniformly at random, without replacement, from the values in the range 1 to n.

Data Types: single | double

population — Input data

vector

Input data from which to sample, specified as a vector. By default, randsample samples uniformly at random, without replacement, from the values in population. The orientation of y (row or column) is the same as that of population.

If population is a numeric vector containing only nonnegative integer values, and population can have the length 1, then use y = population(randsample(length(population),k)) or y = datasample(population,k,'Replace',false) instead of y = randsample(population,k).

Example: y = randsample([50:100],20) returns a vector of 20 values sampled uniformly at random, without replacement, from the population vector consisting of integers from 50 to 100.

Data Types: single | double | logical | char | string | categorical

k — Number of samples

positive integer

Number of samples, specified as a positive integer.

Example: randsample(20,10) returns a vector of 10 values sampled uniformly at random, without replacement, from the integers 1 to 20.

Data Types: single | double

replacement — Indicator for sampling with replacement

false (default) | true

Indicator for sampling with replacement, specified as either false or true.

Example: randsample(10,2,true) returns two values with replacement from the integers 1 to 10.

Data Types: logical

w — Sampling weights

ones(n,1) (default) | vector of nonnegative scalar values

Sampling weights, specified as a vector of nonnegative scalar values. The length of w must be equal to the range of integers to sample or the length of population. The vector w must have at least one positive value. If w contains negative values or NaN values, randsample displays an error message. The randsample function samples with probability proportional to w(i)/sum(w). Usually, w is a vector of probabilities. The randsample function supports specifying weights only for sampling with replacement.

Example: [0.1 0.5 0.35 0.46]

Data Types: single | double

s — Random number stream

MATLAB^® default random number stream (default) | RandStream

Random number stream, specified as the MATLAB default random number stream or RandStream. For details, see Creating and Controlling a Random Number Stream.

Example: s = RandStream('mlfg6331_64') creates a random number stream that uses the multiplicative lagged Fibonacci generator algorithm.

Output Arguments

y — Sample

vector | scalar

Sample, returned as a vector or scalar.

• If k = 1, then y is a scalar.

• If k > 1, then y is a k-by-1 vector.

Alternative Functionality

To sample data randomly, with or without replacement, use datasample.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• When you sample without replacement, the order of the output values might not match the order in MATLAB.

• Code generation does not support the random number stream input argument s.

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