Wondering what’s next for npm?Check out our public roadmap! »

    random-sampler
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.1 • Public • Published

    random-sampler

    This library provides APIs that useful for sampling a set of data, using normal or weighted possibility.

    Installation

    yarn add random-sampler

    Explaination

    算法介绍(中文)

    Usage

    Initialization

    By default, simply new an instance will provide all API that you need. In this case, Math.random is used as default function to generate random numbers.

    import Sampler from 'random-sampler';
     
    const sampler = new Sampler();

    You could also pass a random generator function when creating instance. Whenever called, it should produce uniform distribution with range [0, 1).

    import Sampler from 'random-sampler';
    import MersenneTwister from 'mersenne-twister';
     
    const generator = new MersenneTwister();
    function getRandom() {
      return generator.random();
    }
    const sampler = new Sampler(getRandom);

    Shuffle Array

    By default, API will use Fish-Yates shuffle algorithm to shuffle array.

    import Sampler from 'random-sampler';
     
    const sampler = new Sampler();
    const array = [1, 2, 3];
    sampler.shuffle(array);
    console.log(array);

    If you provide a function to give weight for each element in array, shuffle will be based on their weights, meaning that possibility of each element to be selected first is different. In general, if there are elements a1, a2, ..., an with weights w1, w2, ..., wn, element ai is selected as first element will have possibility wi / (w1 + w2 + ... + wn).

    import Sampler from 'random-sampler';
     
    const sampler = new Sampler();
    const array = [1, 2, 3];
    function getWeight(element, index) {
      return element + index;
    }
    sampler.shuffler(array, getWeight);
    console.log(array);

    Notice: shuffle API will mutate given array. This is not a immutable API.

    Sample Iterable

    By default, it will use Reservoir algorithm to sample data out of array or any other iterable with size unknown:

    import Sampler from 'random-sampler';
     
    const sampler = new Sampler();
    const array = [1, 2, 3];
    const size = 2;
    const result = sampler.sample(array, size);
    console.log(result);

    If you provide a function to give weight for each element in array, sample will be based on their weights, meaning that possibility of each element to be selected is different (see how shuffle with weighted value works).

    import Sampler from 'random-sampler';
     
    const sampler = new Sampler();
    const array = [1, 2, 3];
    const size = 2;
    function getWeight(element, index) {
      return element + index;
    }
    const result = sampler.sample(array, size, getWeight);
    console.log(result);

    When weights are provided, the element with larger weight will be more likely to be shown in front of sample result.

    Notice: sample API will not mutate given array, but instead, it will produce a new array as result.

    Asynchronous Sampling

    When data cannot be provided synchronously, it's also possible to asynchronously add all elements and get the sample result whenever whished.

    import Sampler from 'random-sampler';
     
    const sampler = new Sampler();
    const size = 2;
    const receiver = sampler.create(size);
     
    window.addEventListener('message', (event) => {
      const data = event.data;
      receiver.add(data);
    });
     
    // at some point:
    console.log(receiver.get());

    .create(number) function will return an object with two available APIs: add and get, where add allows you to add elements and get allows you to get the result based on current status.

    If you provide a second parameter as a function providing weights to each element, weighted random sampling will be used. But still, the return of create(number, function) will provide two available options, i.e. add and get as described above.

    import Sampler from 'random-sampler';
     
    const sampler = new Sampler();
    const size = 2;
    function getWeight(element, index) { return element.length * index; }
    window.addEventListener('message', (event) => {
      const data = event.data;
      receiver.add(data);
    });
     
    // at some point:
    console.log(receiver.get());

    Keywords

    none

    Install

    npm i random-sampler

    DownloadsWeekly Downloads

    2

    Version

    0.1.1

    License

    MIT

    Unpacked Size

    42.2 kB

    Total Files

    32

    Last publish

    Collaborators

    • avatar