npm install @stdlib/random-sample

Alternatively,

• To load the package in a website via a script tag without installation and bundlers, use the ES Module available on the esm branch (see README).
• If you are using Deno, visit the deno branch (see README for usage intructions).
• For use in Observable, or in browser/node environments, use the Universal Module Definition (UMD) build available on the umd branch (see README).

The branches.md file summarizes the available branches and displays a diagram illustrating their relationships.

To view installation and usage instructions specific to each branch build, be sure to explicitly navigate to the respective README files on each branch, as linked to above.

var sample = require( '@stdlib/random-sample' );

Samples elements from an array-like object. By default, elements are drawn with replacement from x to create an output array having the same length as x.

var out = sample( [ 'a', 'b', 'c' ] );
// e.g., returns [ 'a', 'a', 'b' ]

out = sample( [ 3, 6, 9 ] );
// e.g., returns [ 3, 9, 6 ]

var bool = ( out.length === 3 );
// returns true

The function accepts the following options:

• size: sample size. Default: N = x.length.
• probs: a probability array. Default: [1/N,...,1/N].
• replace: boolean indicating whether to sample from x with replacement. Default: true.

By default, the function returns an array having the same length as x. To generate a sample of a different size, set the size option.

var out = sample( [ 3, 6, 9 ], {
    'size': 10
});
// e.g., returns [ 6, 3, 9, 9, 9, 6, 9, 6, 9, 3 ]

out = sample( [ 0, 1 ], {
    'size': 20
});
// e.g., returns [ 0, 0, 0, 1, 1, 0, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 0 ]

To draw a sample without replacement, set the replace option to false. In this case, the size option cannot be an integer larger than the number of elements in x.

var out = sample( [ 1, 2, 3, 4, 5, 6 ], {
    'replace': false,
    'size': 3
});
// e.g., returns [ 6, 1, 5 ]

out = sample( [ 0, 1 ], {
    'replace': false
});
// e.g., returns [ 0, 1 ]

By default, the probability of sampling an element is the same for all elements. To assign elements different probabilities, set the probs option.

var x = [ 1, 2, 3, 4, 5, 6 ];
var out = sample( x, {
    'probs': [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.5 ]
});
// e.g., returns [ 5, 6, 6, 5, 6, 4 ]

x = [ 1, 2, 3, 4, 5, 6 ];
out = sample( x, {
    'probs': [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.5 ],
    'size': 3,
    'replace': false
});
// e.g., returns [ 6, 4, 1 ]

The probs option must be a numeric array consisting of nonnegative values which sum to one. When sampling without replacement, note that the probs option denotes the initial element probabilities which are then updated after each draw.

Returns a function to sample elements from an array-like object.

var mysample = sample.factory();

var out = mysample( [ 0, 1, 2, 3, 4 ] );
// e.g., returns [ 4, 3, 4, 4 ]

If provided an array-like object pool, the returned function will always sample from the supplied object.

var mysample = sample.factory( [ 1, 2, 3, 4, 5, 6 ] );

var out = mysample();
// e.g., returns [ 2, 4, 1, 6, 5, 1 ]

out = mysample();
// e.g., returns [ 5, 2, 3, 6, 1, 4 ]

The function accepts the following options:

• seed: pseudorandom number generator seed.
• size: sample size.
• mutate: boolean indicating whether to mutate the pool when sampling without replacement. Default: false.
• replace: boolean indicating whether to sample with replacement. Default: true.

To seed the pseudorandom number generator, set the seed option.

var mysample = sample.factory({
    'seed': 430
});

var out = mysample( [ 1, 2, 3, 4, 5, 6 ] );
// e.g., returns [ 1, 1, 1, 5, 4, 4 ]

mysample = sample.factory( [ 1, 2, 3, 4, 5, 6 ], {
    'seed': 430
});

out = mysample();
// e.g., returns [ 1, 1, 1, 5, 4, 4 ]

To specify a sample size and/or override the default sample size, set the size option.

var mysample = sample.factory({
    'size': 4
});

var out = mysample( [ 0, 1 ] );
// e.g., returns [ 0, 0, 0, 1 ]

// Override the size option...
out = mysample( [ 0, 1 ], {
    'size': 1
});
// e.g., returns [ 1 ]

By default, the returned function draws samples with replacement. To override the default replace strategy, set the replace option.

var mysample = sample.factory({
    'replace': false
});

var out = mysample( [ 1, 2, 3 ] );
// e.g., returns [ 3, 1, 2 ]

If a population from which to sample is provided, the underlying pool remains constant for each function invocation. To mutate the pool by permanently removing observations when sampling without replacement, set the mutate option.

var mysample = sample.factory( [ 1, 2, 3, 4, 5, 6 ], {
    'mutate': true,
    'replace': false,
    'size': 3,
    'seed': 342
});

var out = mysample();
// e.g., returns [ 6, 5, 3 ]

// Override the mutate option...
out = mysample({
    'mutate': false
});
// e.g., returns [ 1, 2, 4 ]

out = mysample();
// e.g., returns [ 1, 2, 4 ]

The returned function returns null after all population units are exhausted.

var mysample = sample.factory( [ 1, 2, 3, 4, 5, 6 ], {
    'mutate': true,
    'replace': false
});

var out = mysample();
// e.g., returns [ 3, 2, 1, 6, 5, 4 ]

out = mysample();
// returns null

• Knuth, Donald E. 1997. The Art of Computer Programming, Volume 2 (3rd Ed.): Seminumerical Algorithms. Boston, MA, USA: Addison-Wesley Longman Publishing Co., Inc.
• Vose, Michael D. 1991. "A linear algorithm for generating random numbers with a given distribution." IEEE Transactions on Software Engineering 17 (9): 972–75. doi:10.1109/32.92917.

This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.

See LICENSE.

Copyright © 2016-2024. The Stdlib Authors.