/ 
Math-Histo-0.1.0
/ Math::Histo::2D

NAME

Math::Histo::2D - 2-Dimensional Histograms for Math::Histo

SYNOPSIS

use Math::Histo::2D;

# Create uniform 2D histogram (10x5 bins)
my $h2 = Math::Histo::2D->new(
    xbins => 10, xmin => 0.0, xmax => 10.0,
    ybins => 5,  ymin => 0.0, ymax => 5.0,
    sumw2 => 1,
);

# Variable-width 2D grid
my $h2_var = Math::Histo::2D->new(
    xedges => [0, 1, 5, 10],
    yedges => [0, 2, 4, 6],
);

# Fill samples
$h2->fill(2.5, 1.5);
$h2->fill(7.5, 3.5, 2.0); # with weight 2.0
$h2->fill_n([1.0, 2.0, 3.0], [1.0, 2.0, 3.0]);

# Statistical moments & covariance
printf("Mean X: %.4f, Mean Y: %.4f\n", $h2->mean_x, $h2->mean_y);
printf("Covariance: %.4f, Correlation: %.4f\n", $h2->covariance, $h2->correlation);

# Projections and profiles along axes (returns 1D Math::Histo objects)
my $proj_x  = $h2->project_x;
my $proj_y  = $h2->project_y;
my $prof_x  = $h2->profile_x; # Mean of Y in each X bin with std error

# Slices across specific bin ranges
my $slice_x = $h2->slice_x(1, 3); # slice across Y bins [1..3]

# Serialization
my $blob = $h2->serialize_binary;
my $restored = Math::Histo::2D->from_binary($blob);

DESCRIPTION

Math::Histo::2D provides high-performance two-dimensional histograms with SIMD-accelerated batch ingestion, 9-region out-of-bounds guards, covariance/correlation tracking, and 1D projections, slices, and profile histograms.

CONSTRUCTORS

new(%options)

Uniform grid: specify xbins, xmin, xmax, ybins, ymin, ymax.

Variable grid: specify xedges => [...], yedges => [...].

clone(): Deep copy.
from_binary($blob): Deserialize 2D binary format.
from_json($json): Deserialize 2D JSON format.

METHODS

fill($x, $y, [$weight=1.0]): Ingest single 2D sample.
fill_n(\@x, \@y, [\@weights]): Batch ingest 2D samples from Perl array references.
fill_packed_f64($packed_x, $packed_y, [$packed_weights]) (or fill_packed): High-performance SIMD zero-copy batch ingestion from packed binary float64 strings (e.g. pack('d*', ...)).
nx(), ny(): Number of bins along X and Y axes.
xmin(), xmax(): Bounds along X axis.
ymin(), ymax(): Bounds along Y axis.
num_entries(): Total in-range fill entries.
total_weight(): Total in-range accumulated weight.
mean_x(), mean_y(): Mean coordinates along axes.
variance_x(), variance_y(): Variances along axes.
covariance(): Cov(X, Y).
correlation(): Pearson correlation coefficient rho_xy in [-1, 1].
bin_content($ix, $iy): Accumulated weight in cell (ix, iy).
bin_error($ix, $iy): Standard error in cell (ix, iy).
bin_sum_w2($ix, $iy): Sum of weights squared in cell (ix, iy).
project_x(), project_y(): 1D projection histograms (Math::Histo).
slice_x($ymin, $ymax), slice_y($xmin, $xmax): 1D slice histograms.
profile_x(), profile_y(): 1D profile histograms (mean and std error per bin).
serialize_binary(), serialize_json(): Binary and JSON serialization.

SEE ALSO

AUTHOR

Steffen Mueller <cpan@steffen-mueller.net>

LICENSE

MIT License. Copyright (c) 2026 Steffen Mueller and libhisto contributors.