Math::...gram2D(3pm)

📦

version 0.49 · 6 versions

okay bestie, welcome to the Math::...gram2D(3pm) manual page from User Contributed Perl Documentation — it’s giving Math::GSL::Histogram2D, and we’re about to make 2D histograms make sense 💖✨

🌸 NAME 🌸

Math::GSL::Histogram2D — Create and manipulate histograms of data in 2 dimensions 🦋

💅 SYNOPSIS 💅

Here’s the whole vibe, copied exactly:

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

# raw interface
my $H = gsl_histogram2d_alloc(100, 100);

gsl_histogram2d_set_ranges_uniform($H,0,101, 0, 101);
gsl_histogram2d_increment($H, -50, -12);  # ignored
gsl_histogram2d_increment($H, 70 );
gsl_histogram2d_increment($H, 85.2 );

my $G          = gsl_histogram2d_clone($H);
my $value      = gsl_histogram2d_get($G, 70, 33);
my ($max,$min) = (gsl_histogram2d_min_val($H), gsl_histogram2d_max_val($H) );
my $sum        = gsl_histogram2d_sum($H);

🎀 DESCRIPTION 🎀

This subsystem allows the creation and manipulation of 2D histograms. Currently, only a raw interface exists. periodt. 💅

gsl_histogram2d_alloc($nx, $ny) — This function allocates memory for a two-dimensional histogram with $nx bins in the x direction and $ny bins in the y direction. The function returns a pointer to a newly created gsl_histogram2d struct. If insufficient memory is available a null pointer is returned and the error handler is invoked with an error code of $GSL_ENOMEM. The bins and ranges must be initialized with one of the functions below before the histogram is ready for use. ✨
gsl_histogram2d_calloc — just listed, no extra description in the source. 🍓
gsl_histogram2d_calloc_uniform — same, just a name drop. 🍓
gsl_histogram2d_free($h) — This function frees the 2D histogram h and all of the memory associated with it. 🫶
gsl_histogram2d_increment($h, $xmin, $xmax, $ymin, $ymax) — This function sets the ranges of the existing histogram $h to cover the ranges $xmin to $xmax and $ymin to $ymax uniformly. The values of the histogram bins are reset to zero. 🔥
gsl_histogram2d_accumulate($h, $x, $y, $weight) — This function is similar to gsl_histogram2d_increment but increases the value of the appropriate bin in the histogram $h by the floating-point number $weight. 💖
gsl_histogram2d_find($h, $x, $y) — This function finds indices i and j to the to the bin which covers the coordinates ($x,$y). The bin is located using a binary search. The search includes an optimization for histograms with uniform ranges, and will return the correct bin immediately in this case. If ($x,$y) is found then the function return GSL_SUCCESS, i and j in this order. If ($x,$y) lies outside the valid range of the histogram then the function returns $GSL_EDOM and the error handler is invoked. 👑
gsl_histogram2d_get($h, $i, $j) — This function returns the contents of the ($i,$j)-th bin of the histogram $h. If ($i,$j) lies outside the valid range of indices for the histogram then the error handler is called with an error code of $GSL_EDOM and the function returns 0. 💀
gsl_histogram2d_get_xrange($h, $i) — This functions finds the upper and lower range limits of the $i-th in the x direction of the histogram $h. The range limits are stored in the returned values after 0 or 1 in this order : xlower and xupper. The lower limits are inclusive (i.e. events with these coordinates are included in the bin) and the upper limits are exclusive (i.e. events with the value of the upper limit are not included and fall in the neighboring higher bin, if it exists). The functions returns 0 as first value to indicate success. If $i lies outside the valid range of indices for the histogram then the error handler is called with an error code of GSL_EDOM. 🌸
gsl_histogram2d_get_yrange($h, $j) — This functions finds the upper and lower range limits of the $j-th in the y direction of the histogram $h. The range limits are stored in the returned values after 0 or 1 in this order : ylower and yupper. The lower limits are inclusive (i.e. events with these coordinates are included in the bin) and the upper limits are exclusive (i.e. events with the value of the upper limit are not included and fall in the neighboring higher bin, if it exists). The functions returns 0 as first value to indicate success. If $j lies outside the valid range of indices for the histogram then the error handler is called with an error code of GSL_EDOM. 🌸
gsl_histogram2d_xmax($h) — This functions returns the maximum upper range limit for the x direction of the histogram $h. 🌈
gsl_histogram2d_xmin($h) — This functions returns the minimum lower range limit for the x direction of the histogram $h. 🌈
gsl_histogram2d_nx($h) — This one gives you the number of bins for the x direction. ⭐
gsl_histogram2d_ymax($h) — This functions returns the maximum upper range limit for the y direction of the histogram $h. 🌈
gsl_histogram2d_ymin($h) — This functions returns the minimum lower range limit for the y direction of the histogram $h. 🌈
gsl_histogram2d_ny($h) — This one gives you the number of bins for the y direction. ⭐
gsl_histogram2d_reset($h) — This function resets all the bins of the histogram $h to zero. 🧚
gsl_histogram2d_calloc_range — just listed, no extra details in the source. 🍓
gsl_histogram2d_set_ranges($h, $xrange, $xsize, $yrange, $ysize) — This function sets the ranges of the existing histogram $h using the arrays $xrange and $yrange of size $xsize and $ysize respectively. The values of the histogram bins are reset to zero. 💜
gsl_histogram2d_set_ranges_uniform($h, $xmin, $xmax, $ymin, $ymax) — This function sets the ranges of the existing histogram $h to cover the ranges $xmin to $xmax and $ymin to $ymax uniformly. The values of the histogram bins are reset to zero. 💜
gsl_histogram2d_memcpy($dest, $src) — This function copies the histogram $src into the pre-existing histogram $dest, making $dest into an exact copy of $src. The two histograms must be of the same size. 🫶
gsl_histogram2d_clone($src) — This function returns a pointer to a newly created Math::GSL::Histogram2D::gsl_histogram2d which is an exact copy of the histogram $src.

NOTE: Ranges must be set with a function like gsl_histogram2d_set_ranges_uniform or this function will return undef. 😭

gsl_histogram2d_max_val($h) — the biggest value chillin' in any of the histogram bins. that's it, that's the whole vibe 💖
gsl_histogram2d_max_bin($h) — finds the indices of the bin holding the max value in $h and hands you back three things in this exact order: 0 if the op succeeded, 1 otherwise, then i and j. if multiple bins are tied for the max, it gives you the first one it found. no favorites, just first come first served ✨
gsl_histogram2d_min_val($h) — same energy as above but the smallest value in the bins 🫶
gsl_histogram2d_min_bin($h) — finds the indices of the bin with the min value in $h, returns 0 if it worked, 1 otherwise, then i and j. ties? first bin found wins, periodt 👑
gsl_histogram2d_xmean($h) — the mean of the histogrammed x variable, treating the histogram like a probability distribution. negative bin values get ignored for this calculation, so don't come crying about your negative bins 🙈
gsl_histogram2d_ymean($h) — mean of the histogrammed y variable, histogram-as-probability-distribution style. negative bin values also ignored here, same rule 💜
gsl_histogram2d_xsigma($h) — the standard deviation of the histogrammed x variable, again pretending the histogram is a probability distribution. and yeah, negative bin values are ignored, we been knew 🌸
gsl_histogram2d_ysigma($h) — standard deviation of the histogrammed y variable, probability-distribution treatment, negative bin values ignored. yes it's the same caveat every time, it's giving consistency 🎀
gsl_histogram2d_cov($h) — the covariance of the histogrammed x and y variables, histogram = probability distribution. negative bin values ignored, as always 💅
gsl_histogram2d_sum($h) — the sum of all bin values. plot twist: negative bin values ARE included in this sum, unlike all those means and sigmas up there. it really said "no filtering" 😭
gsl_histogram2d_equal_bins_p($h1, $h2) — returns 1 if every single individual bin range in the two histograms is identical, 0 otherwise. vibe check passed or not, no in-between ⭐
gsl_histogram2d_add($h1, $h2) — adds the contents of $h2's bins into the corresponding bins of $h1, i.e. h'_1(i,j) = h_1(i,j) + h_2(i,j). the two histograms must have identical bin ranges — no mix-and-matching bestie 🔥
gsl_histogram2d_sub($h1, $h2) — subtracts $h2's bins from the corresponding bins of $h1, i.e. h'_1(i,j) = h_1(i,j) - h_2(i,j). again: identical bin ranges required, non-negotiable 💀
gsl_histogram2d_mul($h1, $h2) — multiplies the bins of $h1 by the corresponding bins of $h2, i.e. h'_1(i,j) = h_1(i,j) * h_2(i,j). identical bin ranges. yes. again. it's the rule 🦋
gsl_histogram2d_div($h1, $h2) — divides the bins of $h1 by the corresponding bins of $h2, i.e. h'_1(i,j) = h_1(i,j) / h_2(i,j). and you guessed it, identical bin ranges required 🌈
gsl_histogram2d_scale($h, $scale) — multiplies every bin of $h by the constant $scale, i.e. h'_1(i,j) = h_1(i,j) $scale. ✨
gsl_histogram2d_shift($h, $offset) — shifts every bin of $h by the constant $offset, i.e. h'_1(i,j) = h_1(i,j) + $offset. 🚀
gsl_histogram2d_fwrite($stream $h) — writes the ranges and bins of $h to $stream in binary format. $stream gets opened with the gsl_fopen function from the Math::GSL module. returns 0 on success and $GSL_EFAILED if something went wrong writing to the file. heads up: since it's native binary format, it is not necessarily portable between different architectures — this data does not travel well 💀
gsl_histogram2d_fread($stream $h) — reads into $h from $stream in binary format. $stream is opened with gsl_fopen from Math::GSL. $h must be preallocated with the correct size, because the function uses the number of x and y bins in $h to figure out how many bytes to read. returns 0 on success, $GSL_EFAILED if reading failed. the data is assumed to have been written in native binary format on the same architecture — so same-machine energy only, bestie 😭
gsl_histogram2d_fprintf($stream, $h, $range_format, $bin_format) — writes the ranges and bins of $h line-by-line to $stream (opened with gsl_fopen from Math::GSL) using the format specifiers $range_format and $bin_format. those should be one of the %g, %e or %f formats for floating point numbers. returns 0 on success and $GSL_EFAILED if the write went sideways.

the output gets formatted in five columns, separated by spaces, like so:

xrange[0] xrange[1] yrange[0] yrange[1] bin(0,0)
xrange[0] xrange[1] yrange[1] yrange[2] bin(0,1)
xrange[0] xrange[1] yrange[2] yrange[3] bin(0,2)
....
xrange[0] xrange[1] yrange[ny-1] yrange[ny] bin(0,ny-1)
xrange[1] xrange[2] yrange[0] yrange[1] bin(1,0)
xrange[1] xrange[2] yrange[1] yrange[2] bin(1,1)
xrange[1] xrange[2] yrange[1] yrange[2] bin(1,2)
....
xrange[1] xrange[2] yrange[ny-1] yrange[ny] bin(1,ny-1)
....
xrange[nx-1] xrange[nx] yrange[0] yrange[1] bin(nx-1,0)
xrange[nx-1] xrange[nx] yrange[1] yrange[2] bin(nx-1,1)
xrange[nx-1] xrange[nx] yrange[1] yrange[2] bin(nx-1,2)
....
xrange[nx-1] xrange[nx] yrange[ny-1] yrange[ny] bin(nx-1,ny-1)

every line has the lower and upper limits of the bin plus the contents of the bin. and yeah, since the upper limit of each bin is the lower limit of its neighbor, those values get duplicated — but that's on purpose, because it lets you manipulate the histogram with line-oriented tools. iconic design tbh 🎀

gsl_histogram2d_fscanf($stream, $h) — reads formatted data from $stream (opened with gsl_fopen from Math::GSL) into the histogram $h. the data is assumed to be in the five-column format that gsl_histogram2d_fprintf produces. $h must be preallocated with the correct lengths, because the function uses the sizes of $h to figure out how many numbers to read. returns 0 on success and $GSL_EFAILED if there was a problem reading from the file 🫶
gsl_histogram2d_pdf_alloc($nx, $ny) — allocates memory for a two-dimensional probability distribution of size $nx-by-$ny and returns a pointer to a freshly initialized gsl_histogram2d_pdf struct. if there isn't enough memory, a null pointer comes back and the error handler is invoked with an error code of $GSL_ENOMEM. 😬
gsl_histogram2d_pdf_init($p, $h) — initializes the two-dimensional probability distribution $p calculated from the histogram $h. if any of $h's bins are negative, the error handler gets invoked with an error code of GSL_EDOM, because a probability distribution simply cannot contain negative values. math said no 💅
gsl_histogram2d_pdf_free($p) — frees the two-dimensional probability distribution function $p and all the memory associated with it. clean up after yourself, bestie 🧹
gsl_histogram2d_pdf_sample($p, $r1, $r2) — uses two uniform random numbers between zero and one, $r1 and $r2, to compute a single random sample from the two-dimensional probability distribution p. returns 0 if it worked, 1 otherwise, followed by the x and y values of the sample. ✨

💖 AUTHORS 💖

Jonathan "Duke" Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com> — the two legends who built this whole thing, give them their flowers 🌸👑

📜 COPYRIGHT AND LICENSE 📜

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, you made it to the end 🥳 this one shipped with perl v5.42.3, dated 2026-08-20 — go forth and histogram, 2D style 💖✨🦋

📦 where this page comes from

ubuntu stonking: libmath-gsl-perl 0.49-1build1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms