Statistics::TopK(3pm)

✨ Statistics::TopK ✨

okay so bestie, welcome to the Statistics::TopK manual page 💖 it's part of the User Contributed Perl Documentation and honestly? it's giving legendary. this is the module for the top-k streaming algorithm, and we're gonna go through it together, no cap.

---

🌸 NAME 🌸

Statistics::TopK — the implementation of the top-k streaming algorithm. periodt.

---

🎀 SYNOPSIS 🎀

use Statistics::TopK;

my $counter = Statistics::TopK->new(10);
while (my $val = <STDIN>) {
    chomp $val;
    $counter->add($val);
}
my @top = $counter->top;
my %counts = $counter->counts;

like... look at her. she's reading from STDIN, counting stuff, then handing you the top list AND the counts. main character energy fr fr 👑

---

🦋 DESCRIPTION 🦋

so Statistics::TopK implements the top-k streaming algorithm, which is also known as the "heavy hitters" algorithm. iykyk. it's built to process data streams and probabilistically calculate the "k" most frequent items while using limited memory. yes, limited. she's efficient like that 💅

a typical example — and this is such a classic — would be figuring out the top 10 IP addresses listed in an access log. the "simple" solution would be to hash every single IP address to a counter and then sort the resulting hash by counter size. cute idea! except that hash could theoretically need over 4 billion keys. not cute. absolutely not. 😭

the top-k algorithm only needs storage space proportional to the number of items of interest. the way she does it is by sacrificing precision, because she's only a probabilistic counter. trade-offs, babes. that's the vibe.

---

💜 METHODS 💜

🌈 new

$counter = Statistics::TopK->new($k)

creates a brand new Statistics::TopK object, all prepped and ready to count the top $k elements. she's born ready ✨

🍓 add

$count = $counter->add($element)

counts the given $element and returns its approximate count (if any, bestie, if any) in the Statistics::TopK object.

okay important: adding an element does not guarantee it will be counted yet, because the algorithm is probabilistic. the occurrence of the current element might only be used to decrease the count of one of the current top elements. that's just how she works. no notes. 💀

🧚 top

@top = $counter->top()

returns a list of the top-k counted elements. the queens of the list 👑

⭐ counts

%counts = $counter->counts()

returns a hash of the top-k counted elements and their counts. receipts included, we love transparency 🫶

---

🔥 SEE ALSO 🔥

• http://en.wikipedia.org/wiki/Streaming_algorithm#Heavy_hitters

---

🙈 REQUESTS AND BUGS 🙈

please report any bugs or feature requests to <http://rt.cpan.org/Public/Bug/Report.html?Queue=Statistics-TopK>. the author will be notified, and then you'll automatically be notified of progress on your bug as changes get made. it's a whole notification chain, it's giving community 🌸

---

💅 SUPPORT 💅

you can find documentation for this module with the perldoc command.

perldoc Statistics::TopK

you can also look for information at:

• GitHub Source Repository

<http://github.com/gray/statistics-topk>

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Statistics-TopK>

• CPAN Ratings

<http://cpanratings.perl.org/d/Statistics-TopK>

• RT: CPAN's request tracker

<http://rt.cpan.org/Public/Dist/Display.html?Name=Statistics-TopK>

• Search CPAN

<http://search.cpan.org/dist/Statistics-TopK/>

---

👑 COPYRIGHT AND LICENSE 👑

Copyright (C) 2009-2015 gray <gray at cpan.org>, all rights reserved.

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

---

💖 AUTHOR 💖

gray, <gray at cpan.org>

---

and that's the whole page bestie 🎀 this one's from perl v5.36.0, dated 2023-02-03, and it lives at Statistics::TopK(3pm). slay, stay hydrated, and go count some heavy hitters 💖✨