@stdlib/random-sample

About stdlib...

We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.

The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.

When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.

To join us in bringing numerical computing to the web, get started by checking us out on GitHub, and please consider financially supporting stdlib. We greatly appreciate your continued support!

Sample

Sample elements from an array-like object.

Installation

npm install @stdlib/random-sample

Usage

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

sample( x[, options] )

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.

sample.factory( [pool, ][options] )

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

Examples

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

// By default, sample uniformly with replacement:
var x = [ 'a', 'b', 'c', 'd' ];
var out = sample( x, {
    'size': 10
});
// e.g., returns [ 'd', 'c', 'b', 'b', 'b', 'd', 'c', 'c', 'b', 'd' ]

// Sample with replacement with custom probabilities:
x = [ 'a', 'b', 'c', 'd' ];
out = sample( x, {
    'probs': [ 0.1, 0.1, 0.2, 0.6 ],
    'size': 10
});
// e.g., returns [ 'b', 'a', 'c', 'd', 'd', 'd', 'd', 'c', 'd', 'd' ]

// Sample without replacement:
x = [ 'a', 'b', 'c', 'd' ];
out = sample( x, {
    'size': 3,
    'replace': false
});
// e.g., returns [ 'd', 'c', 'a' ]

// Sample without replacement when (initial) probabilities are nonuniform:
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 [ 2, 3, 6 ]

References

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

---

Notice

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.

Community

---

License

See LICENSE.

Copyright

Copyright © 2016-2024. The Stdlib Authors.