@stdlib/random-sample
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.5 • Public • Published

    Sample

    NPM version Build Status Coverage Status dependencies

    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' );
    
    var out;
    var x;
    
    // By default, sample uniformly with replacement:
    x = [ 'a', 'b', 'c', 'd' ];
    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

    Chat


    License

    See LICENSE.

    Copyright

    Copyright © 2016-2021. The Stdlib Authors.

    Install

    npm i @stdlib/random-sample

    Homepage

    stdlib.io

    DownloadsWeekly Downloads

    55

    Version

    0.0.5

    License

    Apache-2.0

    Unpacked Size

    80.1 kB

    Total Files

    17

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar