pyHypergrid 1.0.0

N-dimensional histogram library for multivariate data — binning, rebinning, comparison, and visualization.

Hypergrid

N-dimensional histogram library for multivariate data.

Hypergrid bins arbitrary-dimensional data into a grid, then lets you update it incrementally, reproject it onto new edges, compare two grids statistically, and visualize the distribution — including UMAP projections and temporal drift.

Installation

# pip
pip install pyHypergrid

# uv
uv add pyHypergrid

Optional extras:

# pip — with pandas (describe()) and/or UMAP support
pip install "pyHypergrid[stats]"
pip install "pyHypergrid[umap]"
pip install "pyHypergrid[stats,umap]"

# uv
uv add "pyHypergrid[stats]"
uv add "pyHypergrid[umap]"
uv add "pyHypergrid[stats,umap]"

Quick start

import numpy as np
from hypergrid import DenseHypergrid, SparseHypergrid, AdaptiveHypergrid, compute_edges

data = np.random.randn(5000, 3)

# Auto-compute edges with Freedman-Diaconis rule
edges = compute_edges(data)

# Dense backend (good for low-dim, mostly populated grids)
grid = DenseHypergrid(edges)
grid.fit(data)

# Sparse backend (good for high-dim or sparse data)
grid = SparseHypergrid(edges)
grid.fit(data)

# Incremental update
grid.update(np.random.randn(500, 3))

Adaptive grid

Automatically rebins when too much data falls outside the current boundaries:

from hypergrid import AdaptiveHypergrid

grid = AdaptiveHypergrid(drift_threshold=0.05, buffer_size=5000)
grid.fit(data_batch_1)
grid.update(data_batch_2)   # rebins if >5% overflow

Comparing grids

grid1 = DenseHypergrid(edges); grid1.fit(data1)
grid2 = DenseHypergrid(edges); grid2.fit(data2)

grid1.compare(grid2, method="js")           # Jensen-Shannon divergence
grid1.compare(grid2, method="wasserstein")  # Earth Mover's Distance
grid1.compare(grid2, method="l1")           # Total variation
grid1.compare(grid2, method="kl")           # KL divergence

Visualization

grid.plot_all_marginals()
grid.plot_joint(dim_x=0, dim_y=1)
grid.plot_top_bins(k=20)

grid.plot_umap(n_samples=3000)
grid1.compare_umap(grid2)
grid1.compare_marginal(grid2, dim=0)

Temporal tracking

from hypergrid import DenseHypergrid, TemporalHypergrid

base = DenseHypergrid(edges)
tgrid = TemporalHypergrid(base, decay=0.99, snapshot_interval=1000)

for batch in stream:
    tgrid.update(batch)

tgrid.plot_evolution(method="js")
tgrid.plot_temporal_umap()

Rebinning

new_edges = compute_edges(new_data)
rebinned = grid.rebin_to(new_edges)   # returns dict {index: count}

Architecture

BaseHypergrid  (ABC)
  └─ BaseTensorHypergrid  (+ RebinMixin, ComparisonMixin, EmbeddingMixin, VisualizationMixin)
       ├─ DenseTensorHypergrid   — numpy array backend
       ├─ SparseTensorHypergrid  — bounds-checked sparse dict
       ├─ StaticHypergrid        — pluggable storage backend
       └─ AdaptiveHypergrid      — auto-rebinning on drift

TemporalHypergrid  — wraps any hypergrid, adds decay + snapshots

Storage backends

Class	Backend	Best for
DenseTensorHypergrid	numpy array	Low-dim, mostly full grids
SparseTensorHypergrid	sparse dict (bounds-checked)	High-dim or sparse data
StaticHypergrid	pluggable (default: DictStorage)	Custom backends

License

MIT