Statist...ampling(3)

💖 Statistics::CaseResampling 💖

okay bestie, so this is a page out of the User Contributed Perl Documentation, section 3 (Statist...ampling(3) if you're being formal, which we are not). it's an XS module that does efficient resampling + median math with confidence intervals, and it is so much cooler than it sounds. buckle up. 🎀

---

✨ NAME ✨

Statistics::CaseResampling — Efficient resampling and calculation of medians with confidence intervals 💅

---

🌸 SYNOPSIS 🌸

no cap, here's the whole vibe in one go:

use Statistics::CaseResampling ':all';

my $sample = [1,3,5,7,1,2,9]; # ... usually MUCH more data ...
my $confidence = 0.95; # ~2*sigma or "90% within confidence limits"
#my $confidence = 0.37; # ~1*sigma or "~66% within confidence limits"

# calculate the median of the sample with lower and upper confidence
# limits using resampling/bootstrapping:
my ($lower_cl, $median, $upper_cl)
  = median_simple_confidence_limits($sample, $confidence);

# There are many auxiliary functions:

my $resampled = resample($sample);
# $resampled is now a random set of measurements from $sample,
# including potential duplicates

my $medians = resample_medians($sample, $n_resamples);
# $medians is now an array reference containing the medians
# of $n_resamples resample runs
# This is vastly more efficient that doing the same thing with
# repeated resample() calls!
# Analogously:
my $means = resample_means($sample, $n_resamples);

# you can get the cl's from a set of separately resampled medians, too:
my ($lower_cl, $median, $upper_cl)
  = simple_confidence_limits_from_samples($median, $medians, $confidence);

# utility functions:
print median([1..5]), "\n"; # prints 3
print mean([1..5]), "\n"; # prints 3, too, surprise!
print select_kth([1..5], 1), "\n"; # inefficient way to calculate the minimum

---

🦋 DESCRIPTION 🦋

so the entire point of this (XS) module is to calculate the median (or, in principle, other statistics too) with confidence intervals on a sample. how? a little technique called bootstrapping 💫. in a nutshell: it resamples the sample a lot of times, and for each resample it calculates the median. then, from the distribution of all those medians, it calculates the confidence limits. it's giving statistics but make it iconic.

to actually pull off the confidence limit calculation, a bunch of other functions had to be implemented efficiently — and by "efficiently" we mean both algorithmically efficient AND done in C. those functions are honestly useful all on their own, so they get exposed to Perl. most notably, this module serves up a median (and general selection) algorithm that runs in linear time, as opposed to the trivial implementation that requires O(n*log(n)). periodt. 👑

🎲 Random numbers 🎲

the resampling involves drawing so many random numbers. therefore, the module comes with an embedded Mersenne twister (taken from Math::Random::MT).

if you want to change the seed of the RNG, do this:

$Statistics::CaseResampling::Rnd
  = Statistics::CaseResampling::RdGen::setup($seed);

or

$Statistics::CaseResampling::Rnd
  = Statistics::CaseResampling::RdGen::setup(@seed);

⚠️ bestie, listen: do not use the embedded random number generator for other purposes. use Math::Random::MT instead! and at this point, you cannot change the type of RNG. that's just how it is. 🙈

📦 EXPORT 📦

None by default. (she's shy.)

you can export any of the functions documented below using standard Exporter semantics, including the customary :all group. ✨

---

💜 FUNCTIONS 💜

this list is loosely sorted from basic to comprehensive, because the more complicated functions are usually (under the hood, in C) implemented using the basic building blocks. unfortunately, that means you may want to read the documentation backwards. :) 🙃

also, there's a whole set of general purpose, fast (XS) functions for calculating statistical metrics. those are useful completely without the bootstrapping stuff, so they get their own OTHER FUNCTIONS section down below. 🫶

All of these functions are written in C for speed. 🔥

🍓 resample(ARRAYREF)

returns a reference to an array holding N random elements from the input array, where N is the length of the original array.

this is different from shuffling in that it's random drawing without removing the drawn elements from the sample. so yeah, duplicates are gonna happen. it's fine. it's the whole point. 💅

🍓 resample_medians(ARRAYREF, NMEDIANS)

returns a reference to an array containing the medians of NMEDIANS resamples of the original input sample.

🍓 resample_means(ARRAYREF, NMEANS)

returns a reference to an array containing the means of NMEANS resamples of the original input sample.

🍓 simple_confidence_limits_from_median_samples(STATISTIC, STATISTIC_SAMPLES, CONFIDENCE)

calculates the confidence limits for STATISTIC. returns the lower confidence limit, the statistic, and the upper confidence limit. STATISTIC_SAMPLES is the output of, for example, resample_means(\@sample). CONFIDENCE indicates the fraction of data within the confidence limits (assuming a normal, symmetric distribution of the statistic => simple confidence limits).

for example, to get the 90% confidence (~2 sigma) interval for the mean of your sample, you can do this:

my $sample = [<numbers>];
my $means = resample_means($sample, $n_resamples);
my ($lower_cl, $mean, $upper_cl)
  = simple_confidence_limits_from_samples(mean($sample), $means, 0.90);

if you want to apply this logic to other statistics, like the first or third quartile, you have to manually resample and you lose the advantage of doing it in C:

my $sample = [<numbers>];
my $quartiles = [];
foreach (1..1000) {
  push @$quartiles, first_quartile(resample($sample));
}
my ($lower_cl, $firstq, $upper_cl)
  = simple_confidence_limits_from_samples(
      first_quartile($sample), $quartiles, 0.90
    );

for a reliable calculation of the confidence limits, you should use at least 1000 samples, if not more. yes. this whole procedure is expensive. 💀

for medians, though? use the next function:

👑 median_simple_confidence_limits(SAMPLE, CONFIDENCE, [NSAMPLES])

calculates the confidence limits for the CONFIDENCE level for the median of SAMPLE. returns the lower confidence limit, the median, and the upper confidence limit.

in order to calculate the limits, a lot of resampling has to be done. NSAMPLES defaults to 1000. try running this a couple of times on your data interactively to see how the limits still vary a little bit at this setting. (she wiggles. that's normal. 🧚)

---

🌈 OTHER FUNCTIONS 🌈

💫 approx_erf($x)

calculates an approximatation of the error function of x. implemented after

Winitzki, Sergei (6 February 2008).
"A handy approximation for the error function and its inverse" (PDF).
http://homepages.physik.uni-muenchen.de/~Winitzki/erf-approx.pdf

quoting: Relative precision better than 1.3e-4.

💫 approx_erf_inv($x)

calculates an approximation of the inverse of the error function of x.

algorithm from the same source as approx_erf.

quoting: Relative precision better than 2e-3.

💫 nsigma_to_alpha($nsigma)

calculates the probability that a measurement from a normal distribution is further away from the mean than $nsigma standard deviations.

the confidence level (what you pass as the CONFIDENCE parameter to some functions in this module) is 1 - nsigma_to_alpha($nsigma).

💫 alpha_to_nsigma($alpha)

inverse of nsigma_to_alpha().

💫 mean(ARRAYREF)

calculates the mean of a sample.

💫 median(ARRAYREF)

calculates the median (second quartile) of a sample. works in linear time thanks to using a selection instead of a sort. slay.

unfortunately, the way this is implemented, the median of an even number of parameters is, here, defined as the n/2-1th largest number and not the average of the n/2-1th and the n/2th number. this shouldn't matter for nontrivial sample sizes! 🙈

💫 median_absolute_deviation(ARRAYREF)

calculates the median absolute deviation (MAD) in what I believe is O(n). take care to rescale the MAD before using it in place of a standard deviation. ⚠️

💫 first_quartile(ARRAYREF)

calculates the first quartile of the sample.

💫 third_quartile(ARRAYREF)

calculates the third quartile of the sample.

💫 select_kth(ARRAYREF, K)

selects the kth smallest element from the sample.

this is the general function that implements the median/quartile calculation. you get the median with this definition of K:

my $k = int(@$sample/2) + (@$sample & 1);
my $median = select_kth($sample, $k);

💫 sample_standard_deviation

given the sample mean and an anonymous array of numbers (the sample), calculates the sample standard deviation.

💫 population_standard_deviation

same as sample_standard_deviation, but without the correction to N.

---

⭐ TODO ⭐

one could calculate more statistics in C for performance. (manifesting it. 🕯️)

---

🔍 SEE ALSO 🔍

Math::Random::MT

on the approximation of the error function:

Winitzki, Sergei (6 February 2008).
"A handy approximation for the error function and its inverse" (PDF).
http://homepages.physik.uni-muenchen.de/~Winitzki/erf-approx.pdf

the ~O(n) median implementation is based on C.A.R. Hoare's quickselect algorithm. see <http://en.wikipedia.org/wiki/Selection_algorithm#Partition-based_general_selection_algorithm>. right now, it does not implement the Median of Medians algorithm that would guarantee linearity. (she's fast, she's not guaranteed-fast, iykyk. 💀)

---

🫶 AUTHOR 🫶

Steffen Mueller, <cpan@steffen-mueller.net>

Daniel Dragan, <bulk88@hotmail.com>, who supplied MSVC compatibility patches.

---

📜 COPYRIGHT AND LICENSE 📜

Copyright (C) 2010, 2011, 2012, 2013, 2025 by Steffen Mueller

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available.

---

okay and that's the whole page bestie, tysm for reading 💖 this one came courtesy of perl v5.42.3, dated 2026-10-12 — go forth and bootstrap responsibly, the confidence limits believe in you 🎀✨🦋