151 lines
4.8 KiB
Plaintext
151 lines
4.8 KiB
Plaintext
|
|
{{alias}}( x[, options] )
|
|
Samples elements from an array-like object.
|
|
|
|
Parameters
|
|
----------
|
|
x: ArrayLike
|
|
Array-like object from which to sample.
|
|
|
|
options: Object (optional)
|
|
Options.
|
|
|
|
options.size: integer (optional)
|
|
Sample size. By default, the function returns an array having the same
|
|
length as `x`. Specify the `size` option to generate a sample of a
|
|
different size.
|
|
|
|
options.probs: Array<number> (optional)
|
|
Element probabilities. By default, the probability of sampling an
|
|
element is the same for all elements. To assign elements different
|
|
probabilities, set the `probs` option. 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.
|
|
|
|
options.replace: boolean (optional)
|
|
Boolean indicating whether to sample with replacement. If the `replace`
|
|
option is set to `false`, the `size` option cannot be an integer larger
|
|
than the number of elements in `x`. Default: `true`.
|
|
|
|
Returns
|
|
-------
|
|
out: Array
|
|
Sample.
|
|
|
|
Examples
|
|
--------
|
|
> var out = {{alias}}( 'abc' )
|
|
e.g., [ 'a', 'a', 'b' ]
|
|
> out = {{alias}}( [ 3, 6, 9 ] )
|
|
e.g., [ 3, 9, 6 ]
|
|
> var bool = ( out.length === 3 )
|
|
true
|
|
|
|
> out = {{alias}}( [ 3, null, NaN, 'abc', function(){} ] )
|
|
e.g., [ 3, 'abc', null, 3, null ]
|
|
|
|
// Set sample size:
|
|
> out = {{alias}}( [ 3, 6, 9 ], { 'size': 10 })
|
|
e.g., [ 6, 3, 9, 9, 9, 6, 9, 6, 9, 3 ]
|
|
> out = {{alias}}( [ 0, 1 ], { 'size': 20 })
|
|
e.g., [ 0, 0, 0, 1, 1, 0, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1, 1, 1, 0 ]
|
|
|
|
// Draw without replacement:
|
|
> out = {{alias}}( [ 1, 2, 3, 4, 5, 6 ], { 'replace': false, 'size': 3 })
|
|
e.g., [ 6, 1, 5 ]
|
|
> out = {{alias}}( [ 0, 1 ], { 'replace': false })
|
|
e.g., [ 0, 1 ]
|
|
|
|
// Assigning non-uniform element probabilities:
|
|
> var x = [ 1, 2, 3, 4, 5, 6 ];
|
|
> var probs = [ 0.1, 0.1, 0.1, 0.1, 0.1, 0.5 ];
|
|
> out = {{alias}}( x, { 'probs': probs })
|
|
e.g., [ 5, 6, 6, 5, 6, 4 ]
|
|
> out = {{alias}}( x, { 'probs': probs, 'size': 3, 'replace': false })
|
|
e.g., [ 6, 4, 1 ]
|
|
|
|
|
|
{{alias}}.factory( [pool, ][options] )
|
|
Returns a function to sample elements from an array-like object.
|
|
|
|
If provided an array-like object `pool`, the returned function will always
|
|
sample from the supplied object.
|
|
|
|
Parameters
|
|
----------
|
|
pool: ArrayLike (optional)
|
|
Array-like object from which to sample.
|
|
|
|
options: Object (optional)
|
|
Options.
|
|
|
|
options.seed: integer (optional)
|
|
Integer-valued seed.
|
|
|
|
options.size: integer (optional)
|
|
Sample size.
|
|
|
|
options.replace: boolean (optional)
|
|
Boolean indicating whether to sample with replacement. Default: `true`.
|
|
|
|
options.mutate: boolean (optional)
|
|
Boolean indicating whether to mutate the `pool` when sampling without
|
|
replacement. If a population from which to sample is provided, the
|
|
underlying `pool` remains by default constant for each function
|
|
invocation. To mutate the `pool` by permanently removing observations
|
|
when sampling without replacement, set the `mutate` option to `true`.
|
|
The returned function returns `null` after all population units are
|
|
exhausted. Default: `false`.
|
|
|
|
Returns
|
|
-------
|
|
fcn: Function
|
|
Function to sample elements from an array-like object.
|
|
|
|
Examples
|
|
--------
|
|
// Set a seed:
|
|
> var mysample = {{alias}}.factory({ 'seed': 232 });
|
|
> var out = mysample( 'abcdefg' )
|
|
e.g., [ 'g', 'd', 'g', 'f', 'c', 'e', 'f' ]
|
|
|
|
// Provide `pool` and set a seed plus a default sample size:
|
|
> var pool = [ 1, 2, 3, 4, 5, 6 ];
|
|
> mysample = {{alias}}.factory( pool, { 'seed': 232, 'size': 2 });
|
|
> out = mysample()
|
|
e.g., [ 6, 4 ]
|
|
> out = mysample()
|
|
e.g., [ 6, 5 ]
|
|
|
|
// Mutate the `pool`:
|
|
> var opts = { 'seed': 474, 'size': 3, 'mutate': true, 'replace': false };
|
|
> pool = [ 1, 2, 3, 4, 5, 6 ];
|
|
> mysample = {{alias}}.factory( pool, opts );
|
|
> out = mysample()
|
|
e.g., [ 4, 3, 6 ]
|
|
> out = mysample()
|
|
e.g., [ 1, 5, 2 ]
|
|
> out = mysample()
|
|
null
|
|
|
|
// Override default `size` parameter when invoking created function:
|
|
> mysample = {{alias}}.factory( [ 0, 1 ], { 'size': 2 });
|
|
> out = mysample()
|
|
e.g., [ 1, 1 ]
|
|
> out = mysample({ 'size': 10 })
|
|
e.g, [ 0, 1, 1, 1, 0, 1, 0, 0, 1, 1 ]
|
|
|
|
// Sample with and without replacement:
|
|
> mysample = {{alias}}.factory( [ 0, 1 ], { 'size': 2 });
|
|
> out = mysample()
|
|
e.g., [ 1, 1 ]
|
|
> out = mysample({ 'replace': false })
|
|
e.g., [ 0, 1 ] or [ 1, 0 ]
|
|
> out = mysample()
|
|
e.g., [ 1, 1 ]
|
|
|
|
See Also
|
|
--------
|
|
|