/ 
Array-Sample-WeightedRandom-0.002
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.002 of Array::Sample::WeightedRandom (from Perl distribution Array-Sample-WeightedRandom), released on 2022-05-20.

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
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.

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 being chosen. An element can be picked more than once.

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

sample_weighted_random_no_replacement

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

Options:

  • pos => bool

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

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.