README.md

Sample

Sample elements from an array-like object.

Usage

Sample elements from an array-like object.

var sample = require( '@stdlib/utils/sample' );

sample( x[, opts] )

Samples elements from an array-like object. By default, elements are being drawing with replacement from x to form an output array of the same length as x.

var bool;
var out;

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

bool = out.length === 3;
// returns true

The function accepts the following options:

• size: sample size. Default: x.length.
• probs: array of element probabilities. Default: [1/x.length,...,1/x.length].
• replace: boolean indicating if to sample with replacement from elements of x. Default: true.

To generate a sample of a different size than the input array, set the size option.

var out;

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

out = sample( [ 0, 1 ], {
    'size': 20
});
// returns e.g. [ 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. Notice that in this case, the size option cannot be set to an integer larger than the number of elements in x.

var out;

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

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

Use the probs option to supply an array of probabilities in cases where the elements in x are not equally likely to be drawn. The option expects an array of non-negative values which sum to one. When sampling without replacement from x, probs denotes the initial element probabilities which are then updated after each draw.

var out;
var x;

x = [ 1, 2, 3, 4, 5, 6 ];
out = sample( x, {
    'probs': [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.5 ]
});
// returns e.g. [ 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
});
// returns e.g. [ 6, 4, 1 ]

sample.factory( [seed] )

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

var mysample = sample.factory( 232 );

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

Examples

var sample = require( '@stdlib/utils/sample' );

var out;
var x;

// By default, sample uniformly with replacement:
x = [ 'a', 'b', 'c', 'd' ];
console.log( 'By default, sample uniformly with replacement:' );
out = sample( x, {
    'size': 20
});
console.log( out );

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

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

// Sample without replacement when (initial) probabilities are non-uniform
x = [ 1, 2, 3, 4, 5, 6];
console.log( 'Sample without replacment (with custom probabilities):' );
out = sample( x, {
    'probs': [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.5 ],
    'size': 3,
    'replace': false
});
console.log( out );