/ 
Array-Sample-WeightedRandom-0.005
River stage one • 5 direct dependents • 6 total dependents
/ Array::Sample::WeightedRandom

NAME

Array::Sample::WeightedRandom - Sample elements randomly, with weights (with or without replacement)

VERSION

This document describes version 0.005 of Array::Sample::WeightedRandom (from Perl distribution Array-Sample-WeightedRandom), released on 2022-05-22.

SYNOPSIS

use Array::Sample::WeightedRandom qw(sample_weighted_random_with_replacement sample_weighted_random_no_replacement);

# "b" will be picked more often because it has a greater weight. it's also more
# likely to be picked at the beginning.
sample_weighted_random_with_replacement([ ["a",1], ["b",2.5] ], 1); => ("b")
sample_weighted_random_with_replacement([ ["a",1], ["b",2.5] ], 1); => ("a")
sample_weighted_random_with_replacement([ ["a",1], ["b",2.5] ], 1); => ("b")
sample_weighted_random_with_replacement([ ["a",1], ["b",2.5] ], 5); => ("b", "b", "a", "b", "b")

sample_weighted_random_no_replacement([ ["a",1], ["b",2.5] ], 5); => ("b", "a")

DESCRIPTION

Keywords: weight, weighting, pick

FUNCTIONS

All functions are not exported by default, but exportable.

sample_weighted_random_with_replacement

Syntax: sample_simple_random_with_replacement(\@ary, $n [ , \%opts ]) => list

Options:

  • pos => bool

    If set to true, will return positions instead of the elements.

  • shuffle => bool

    By default, a heavier-weighted item will be more likely to be at the front of the resulting sample. If this option is set to true, the function will shuffle the random samples before returning it, resulting in random order regardless of weight.

  • algo => str

    Default is 'copy'. Another choice is 'nocopy', which avoids creating a shallow (1-level) copy of the input array. The 'nocopy' algorithm is generally a bit slower but could save memory usage *if* your array is very very large (e.g. tens of millions of elements).

  • with_weight => bool

    If set to true, will return the original elements (values with weights) instead of just the values.

The function takes an array reference (\@ary) and number of samples to take ($n). The array must be structured as follow: each element is a 2-element arrayref containing a value followed by weight (a non-negative real number). The function will take samples at random position but taking weight into consideration. The larger the weight of an element, the greater the possibility of the element's value being chosen *and* the greater the possibility of the element's value being in the front of the samples. An element can be picked more than once.

The function will return a list of sample items (values only, without the weights).

If you want random order regardless of weight, you can shuffle the resulting list e.g. using List::Util's shuffle; or you can use the shuffle option which does the same.

sample_weighted_random_no_replacement

Syntax: sample_simple_random_no_replacement(\@ary, $n [ , \%opts ]) => list

Like "sample_weighted_random_with_replacement" but an element can only be picked once.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Array-Sample-WeightedRandom.

SOURCE

Source repository is at https://github.com/perlancar/perl-Array-Sample-WeightedRandom.

SEE ALSO

Data::Random::Weighted returns only a single item, uses hash internally so you can't have duplicate elements, and only allows integer as weights.

Other sampling methods: Array::Sample::SysRand, Array::Sample::Partition, Array::Sample::SimpleRandom.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Array-Sample-WeightedRandom

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.