Math::...togram(3pm)

📦
version 0.49 · 6 versions
, in ubuntu stonking

💖 NAME 💖

Math::GSL::Histogram — Create and manipulate histograms of data

okay bestie, welcome to Math::...togram(3pm) from the User Contributed Perl Documentation, and it is lowkey iconic 🎀

✨ SYNOPSIS ✨

use Math::GSL::Histogram qw/:all/;

my $H = gsl_histogram_alloc(100);
gsl_histogram_set_ranges_uniform($H,0,101);
gsl_histogram_increment($H, -50 );  # ignored
gsl_histogram_increment($H, 70 );
gsl_histogram_increment($H, 85.2 );

my $G = gsl_histogram_clone($H);
my $value = gsl_histogram_get($G, 70);
my ($max,$min) = (gsl_histogram_min_val($H), gsl_histogram_max_val($H) );
my $sum = gsl_histogram_sum($H);

🌸 DESCRIPTION 🌸

okay so here's the whole roster of functions this module hands you, no gatekeeping:

  • gsl_histogram_alloc($n) — this one grabs memory for a histogram with $n bins and hands back a pointer to a freshly-made gsl_histogram struct 🫶 but heads up: the bins and the ranges are not initialized yet. you gotta set them up with one of the range-setting functions down below before this histogram is actually ready to serve. no vibes until you do that.
  • gsl_histogram_calloc
  • gsl_histogram_calloc_uniform
  • gsl_histogram_free($h) — frees the histogram $h plus every bit of memory attached to it. say bye 👋
  • gsl_histogram_increment($h, $x) — updates histogram $h by adding one (1.0) to the bin whose range contains the coordinate $x. if $x is inside the valid range of the histogram, the function returns zero, i.e. success, slay. if $x is less than the lower limit of the histogram, it returns $GSL_EDOM and none of the bins get touched. same deal if $x is greater than or equal to the upper limit: $GSL_EDOM, and none of the bins are modified. but here's the tea — the error handler is not called, because it's super common to compute histograms over just a small range of a bigger dataset and simply ignore everything outside your range of interest 💅
  • gsl_histogram_accumulate($h, $x, $weight) — basically gsl_histogram_increment's sibling, except instead of +1 it bumps the right bin in histogram $h up by the floating-point number $weight ✨
  • gsl_histogram_find($h, $x) — finds the bin number that covers the coordinate $x in histogram $h. it locates the bin with a binary search, and there's an optimization baked in for histograms with a uniform range, so in that case it returns the correct bin immediately, no cap. if $x is found in the range of the histogram, the function returns the bin number and returns $GSL_SUCCESS. if $x is outside the valid range of the histogram, it returns $GSL_EDOM and the error handler gets invoked 😭
  • gsl_histogram_get($h, $i) — returns the contents of the $i-th bin of histogram $h. if $i is outside the valid range of indices for that histogram, the error handler is called with an error code of GSL_EDOM and the function returns 0 💀
  • gsl_histogram_get_range($h, $i) — finds the upper and lower range limits of the $i-th bin of histogram $h. if the index $i is valid, the corresponding range limits come back after the 0, in this order: lower first, then upper. the lower limit is inclusive (events with this coordinate are included in the bin) and the upper limit is exclusive (events with the coordinate of the upper limit are excluded and land in the neighboring higher bin, if one exists). the function returns 0 to say success. if $i lies outside the valid range of indices for the histogram, the error handler gets called and the function returns an error code of $GSL_EDOM.
  • gsl_histogram_max($h) — returns the maximum upper limit of histogram $h. it's a way of getting that value without poking at the gsl_histogram struct directly 👑
  • gsl_histogram_min($h) — returns the minimum lower range limit of histogram $h. again: no need to touch the gsl_histogram struct directly, we're being polite.
  • gsl_histogram_bins($h) — returns the number of bins of the histogram $h limit. it's a way of determining this value without accessing the gsl_histogram struct directly.
  • gsl_histogram_reset($h) — resets every bin in histogram $h back to zero. factory reset but make it math 🧚
  • gsl_histogram_calloc_range
  • gsl_histogram_set_ranges($h, $range, $size) — sets the ranges of the existing histogram $h using the array $range of size $size. the values of the histogram bins get reset to zero. your $range array should hold the desired bin limits, and those ranges can be arbitrary — with one rule: they must be monotonically increasing. also note that the size of the $range array should be defined as one element bigger than the number of bins, because that extra element is what supplies the upper value of the final bin 🔥
  • gsl_histogram_set_ranges_uniform($h, $xmin, $xmax) — sets the ranges of the existing histogram $h so they cover the range $xmin to $xmax uniformly. the values of the histogram bins get reset to zero. the bin ranges look like this:
bin[0] corresponds to xmin <= x < xmin + d
bin[1] corresponds to xmin + d <= x < xmin + 2 d
......
bin[n-1] corresponds to xmin + (n-1)d <= x < xmax

where d is the bin spacing, d = (xmax-xmin)/n.

  • gsl_histogram_memcpy($dest, $src) — copies histogram $src into the pre-existing histogram $dest, turning $dest into an exact copy of $src. the two histograms must be the same size, that's non-negotiable bestie.
  • gsl_histogram_clone($src) — returns a pointer to a newly created histogram that's an exact copy of histogram $src. twin energy 🦋
  • gsl_histogram_max_val($h) — returns the maximum value contained in the histogram bins.
  • gsl_histogram_max_bin($h) — returns the index of the bin containing the maximum value. if several bins are out here holding that same maximum value, the smallest index is the one returned.
  • gsl_histogram_min_val($h) — returns the minimum value contained in the histogram bins.
  • gsl_histogram_min_bin($h) — returns the index of the bin containing the minimum value. if several bins contain the same maximum value, the smallest index is returned.
  • gsl_histogram_equal_bins_p($h1, $h2) — returns 1 if all of the individual bin ranges of the two histograms are identical, and 0 otherwise.
  • gsl_histogram_add($h1, $h2) — adds the contents of the bins in histogram $h2 to the corresponding bins of histogram $h1, i.e. h'_1(i) = h_1(i) + h_2(i). the two histograms must have identical bin ranges.
  • gsl_histogram_sub($h1, $h2) — subtracts the contents of the bins in histogram $h2 from the corresponding bins of histogram $h1, i.e. h'_1(i) = h_1(i) - h_2(i). the two histograms must have identical bin ranges.
  • gsl_histogram_mul($h1, $h2) — multiplies the contents of the bins of histogram $h1 by the contents of the corresponding bins in histogram $h2, i.e. h'_1(i) = h_1(i) * h_2(i). the two histograms must have identical bin ranges.
  • gsl_histogram_div($h1, $h2) — divides the contents of the bins of histogram $h1 by the contents of the corresponding bins in histogram $h2, i.e. h'_1(i) = h_1(i) / h_2(i). the two histograms must have identical bin ranges.
  • gsl_histogram_scale($h, $scale) — multiplies the contents of the bins of histogram $h by the constant $scale, i.e. h'_1(i) = h_1(i) * scale.
  • gsl_histogram_shift($h, $offset) — shifts the contents of the bins of histogram $h by the constant $offset, i.e. h'_1(i) = h_1(i) + offset.
  • gsl_histogram_sigma($h) — returns the standard deviation of the histogrammed variable, treating the histogram as a probability distribution. negative bin values are ignored for the purposes of this calculation, and the accuracy of the result is limited by the bin width 🫶
  • gsl_histogram_mean($h) — returns the mean of the histogrammed variable, again treating the histogram as a probability distribution. negative bin values are ignored for the purposes of this calculation too, and yep, accuracy is limited by the bin width.
  • gsl_histogram_sum($h) — returns the sum of all bin values. negative bin values are included in this sum, no filtering.
  • gsl_histogram_fwrite($stream, $h) — writes the ranges and bins of histogram $h to the stream $stream in binary format. $stream must have been opened by the gsl_fopen function from the Math::GSL module. the return value is 0 for success and $GSL_EFAILED if something went wrong writing to the file. ⚠️ and because the data goes out in the native binary format, it may not be portable between different architectures.
  • gsl_histogram_fread($stream, $h) — reads into histogram $h from the open stream $stream in binary format, and $stream again must have been opened by the gsl_fopen function from the Math::GSL module. $h must be preallocated with the correct size, because the function uses the number of bins in $h to figure out how many bytes to read. return value is 0 for success and $GSL_EFAILED if there was a problem reading from the file. and the data is assumed to have been written in the native binary format on the same architecture 🌈
  • gsl_histogram_fprintf($stream, $h, $range_format, $bin_format) — writes the ranges and bins of histogram $h line-by-line to the stream $stream (from the gsl_fopen function in the Math::GSL module) using the format specifiers $range_format and $bin_format. those should be one of the %g, %e or %f formats for floating point numbers. the function returns 0 for success and $GSL_EFAILED if there was a problem writing to the file. the histogram output is formatted in three columns, separated by spaces, like this:
range[0] range[1] bin[0]
range[1] range[2] bin[1]
range[2] range[3] bin[2]
....
range[n-1] range[n] bin[n-1]

the values of the ranges get formatted using range_format and the values of the bins get formatted using bin_format. each line contains the lower and upper limit of the range of the bin plus the value of the bin itself. and yeah, since the upper limit of one bin is the lower limit of the next, those values get duplicated between lines — but that's on purpose, because it lets you manipulate the histogram with line-oriented tools 💅

💖 and that's part one bestie — more parts are still coming, so don't go anywhere!

okay bestie we're BACK and we're picking up right where we left off 💖 no re-intros, no recap, we're just diving straight into the histogram functions. buckle up.

  • gsl_histogram_fscanf($stream, $h) — this one reads formatted data from the stream $stream (which you opened with the gsl_fopen function from the Math::GSL module, iykyk) straight into the histogram $h. the data has to be in the three-column format that gsl_histogram_fprintf spits out, so they're like a matching set fr. and listen — $h must be preallocated with the correct length, because the function literally uses the size of $h to figure out how many numbers to read. it's giving "you must know what you want before you ask." returns 0 for success and $GSL_EFAILED if something went wrong reading from the file. 😭
  • gsl_histogram_pdf_alloc($n) — allocates memory for a probability distribution with $n bins and hands you back a pointer to a freshly initialized gsl_histogram_pdf struct. ✨ if there's not enough memory? null pointer, and the error handler gets invoked with error code $GSL_ENOMEM. so like, it will tell you. 💀
  • gsl_histogram_pdf_init($p, $h) — initializes the probability distribution $p using the contents of the histogram $h. but bestie. if any of the bins of $h are negative, the error handler gets invoked with error code $GSL_EDOM, because a probability distribution cannot contain negative values. that's not a vibe, that's a law of the universe. 🚫
  • gsl_histogram_pdf_free($p) — frees the probability distribution function $p and every last bit of memory associated with it. be a good friend and call this. 🫶
  • gsl_histogram_pdf_sample($p, $r) — this one takes $r, a uniform random number between zero and one, and computes a single random sample from the probability distribution $p. the algorithm used to compute the sample s is exactly this formula:
s = range[i] + delta * (range[i+1] - range[i])

where i is the index that satisfies sum[i] <= r < sum[i+1], and delta is:

(r - sum[i])/(sum[i+1] - sum[i])

not me doing math at you but look at her go, she's beautiful 😌

✨ EXAMPLES ✨

here's how you'd make a histogram with logarithmic bins covering the ranges [1,10), [10,100) and [100,1000). chef's kiss:

$h = gsl_histogram_alloc (3);

# bin[0] covers the range 1 <= x < 10
# bin[1] covers the range 10 <= x < 100
# bin[2] covers the range 100 <= x < 1000

$range = [ 1.0, 10.0, 100.0, 1000.0 ];

gsl_histogram_set_ranges($h, $range, 4);

four range points, three bins, math checks out, we ate 💅

👑 AUTHORS 👑

Jonathan "Duke" Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>

Copyright (C) 2008-2024 Jonathan "Duke" Leto and Thierry Moisan

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

and that's the whole page bestie!! 🦋 this fine piece of documentation was served to you by perl v5.42.3, dated 2026-08-20, under the name Math::...togram(3pm) — yes the name is doing a little bit of hiding, we love an enigmatic main character 💖 now go write some code and free your memory when you're done, mwah 🎀✨

📦 where this page comes from