@stdlib/random-sample
v0.2.1
Published
Sample elements from an array-like object.
Downloads
30,368
Readme
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 fromx
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 thepool
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.