Statis...OnLine(3pm)

🌸 Statistics::OnLine — bestie edition 💖

okay so this is Statistics::OnLine, a page from the User Contributed Perl Documentation (the 3pm squad, yk). It's a pure Perl implementation of the on-line algorithm that produces statistics ✨ and yes she's serving math, no cap.

---

🌈 NAME 🌈

Statistics::OnLine — a pure Perl glow-up of the on-line algorithm that spits out statistics. 💅

---

🎀 SYNOPSIS 🎀

look at her go, literally:

use Statistics::OnLine;
my $s = Statistics::OnLine->new;

my @data = (1, 2, 3, 4, 5);
$s->add_data( @data );
$s->add_data( 6, 7 );
$s->add_data( 8 );

print "count = ",$s->count,"\tmean = ",$s->mean,"\tvariance = ",$s->variance,"\tvariance_n = ",
      $s->variance_n,"\tskewness = ",$s->skewness,"\tkurtosis = ",$s->kurtosis,"\n";

$s->add_data( ); # does nothing!
print "count = ",$s->count,"\tmean = ",$s->mean,"\tvariance = ",$s->variance,"\tvariance_n = ",
      $s->variance_n,"\tskewness = ",$s->skewness,"\tkurtosis = ",$s->kurtosis,"\n";

$s->add_data( 9, 10 );
print "count = ",$s->count,"\tmean = ",$s->mean,"\tvariance = ",$s->variance,"\tvariance_n = ",
      $s->variance_n,"\tskewness = ",$s->skewness,"\tkurtosis = ",$s->kurtosis,"\n";

note the flex: $s->add_data( ); # does nothing! — she said no data, no drama 💀

---

🦋 DESCRIPTION 🦋

so basically this module is a tool for doing statistic operations on large datasets — like, actually large, the kind that typically could not fit the memory of the machine, e.g. a stream of data from the network. it's giving "we are NOT loading this into RAM bestie." 😭

Once it's instantiated, an object of the class hands you an add_data method to add data to the dataset. When you need some statistics computed — at some point in the stream — you just call the appropriate method. And here's the iconic part: after the stats run, you can keep adding new data. The object will just keep updating the existing data to give you new statistics. main character behavior fr fr. 👑

---

✨ METHODS ✨

• new() — creates a new Statistics::OnLine object and returns it. fresh out the box, baby 🎁
• add_data(@) — adds new data to the object and updates the internal state of the statistics.

The method returns the object itself so you can chain like a queen:

my $v = $s->add_data( 1, 2, 3, 4 )->variance;

• clean() — cleans the internal state of the object and resets all the internal statistics. wipe the slate, start fresh 🧼

Returns the object itself for chaining purposes:

my $v = $s->clean->add_data( 1, 2, 3, 4 )->variance;

• count() — returns the actual number or elements inserted and processed by the object. bestie is keeping receipts 🔢
• mean() — returns the average of the elements inserted into the system:

\fract{ \sum_1^n{x_i} }{ n }

• variance() — returns the variance of the element inserted into the system:

\fract{ \sum_1^n{avg - x_i} }{ n - 1 }

• variance_n() — returns the variance of the element inserted into the system:

\fract{ \sum_1^n{avg - x_i} }{ n }

• skewness() — returns the skewness (third standardized moment) of the element inserted into the system <http://en.wikipedia.org/wiki/Skewness> 📐
• kurtosis() — returns the kurtosis (fourth standardized moment) of the element inserted into the system <http://en.wikipedia.org/wiki/Kurtosis> 📏

---

😭 ERROR MESSAGES 😭

the conditions in which the system can return errors, using a die, are these two iconic little threats:

• too few elements to compute function — some functions need a minimum number of elements before they'll even look at you: mean, variance_n and skewness need at least one element, variance needs at least two, and kurtosis needs at least four. not negotiable, periodt.
• variance is zero: cannot compute kurtosis|skewness — both kurtosis and skewness need the variance to be greater than zero. zero variance = no math for you 🙈

---

🔥 THEORY 🔥

On-line statistics are based on strong mathematical foundations which transform the standard computations into a sequence of operations that incrementally update with new values the actual ones. glow-up math, honestly. ✨

There are some referencence in the web. This documentation suggests you start your investigation from <http://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Higher-order_statistics>. The linked page provides other useful references on the foundations of the method. go read, iykyk 📚

---

💀 CAVEAT 💀

the module is intended to be used in all the situations where:

1. the number of data elements could be too large with respect to the memory of the system, or
2. the elements arrive at different time stamps and intermediate results are needed.

If the length of the stream is fixed, all the data elements are present in a single place, and there is no need for intermediate results, it could be better to use different modules — for instance Statistics::Lite — to make computations.

The reason for this choice is that the module uses a stable approximation, well suited for use on streams (effectively an on-line algorithm). Using this system on fixed datasets could introduce some (little) approximation. so like, tiny approximation energy. not a crisis, but know it 🫶

---

🎀 HISTORY 🎀

1. 0.02 — corrected typos in documentation (a real one, we love growth)
2. 0.01 — initial version of the module 🐣

---

👑 AUTHOR 👑

Francesco Nidito

---

💖 COPYRIGHT 💖

Copyright 2009 Francesco Nidito. All rights reserved.

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

---

🌸 SEE ALSO 🌸

• Statistics::Lite
• <http://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Higher-order_statistics>

---

and that's the whole page, bestie 💅 this one shipped with perl v5.36.0 and it's dated 2022-10-13 — historic. iconic. ate. 🎀✨🦋