07 Jul 2022 00:05:39 UTC
- Distribution: Array-Sample-WeightedRandom
- Module version: 0.005
- Source (raw)
- Browse (raw)
- How to Contribute
- Testers (744 / 0 / 3)
- KwaliteeBus factor: 1
- % Coverage
- License: perl_5
- Perl: v5.10.1
- Activity24 month
- Download (17.5KB)
- MetaCPAN Explorer
- Subscribe to distribution
- This version
- Latest versionPERLANCAR perlancar
- SEE ALSO
- COPYRIGHT AND LICENSE
Array::Sample::WeightedRandom - Sample elements randomly, with weights (with or without replacement)
This document describes version 0.005 of Array::Sample::WeightedRandom (from Perl distribution Array-Sample-WeightedRandom), released on 2022-05-22.
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")
Keywords: weight, weighting, pick
All functions are not exported by default, but exportable.
Syntax: sample_simple_random_with_replacement(\@ary, $n [ , \%opts ]) => list
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
shuffleoption which does the same.
Syntax: sample_simple_random_no_replacement(\@ary, $n [ , \%opts ]) => list
Like "sample_weighted_random_with_replacement" but an element can only be picked once.
Please visit the project's homepage at https://metacpan.org/release/Array-Sample-WeightedRandom.
Source repository is at https://github.com/perlancar/perl-Array-Sample-WeightedRandom.
Data::Random::Weighted returns only a single item, uses hash internally so you can't have duplicate elements, and only allows integer as weights.
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.
This software is copyright (c) 2022 by perlancar <firstname.lastname@example.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.
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.
Module Install Instructions
To install Array::Sample::WeightedRandom, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell install Array::Sample::WeightedRandom
For more information on module installation, please visit the detailed CPAN module installation guide.