tessl/pypi-boost-histogram
The Boost::Histogram Python wrapper providing fast histogram implementations with full power and flexibility for scientific computing.
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
histogram-core.mddocs/
Histogram Core
Core histogram functionality for creating, configuring, and managing histograms with various axis types and storage options. The Histogram class provides the primary interface for all histogram operations.
Capabilities
Histogram Creation
Create histograms with specified axes and optional storage configuration.
class Histogram:
def __init__(self, *axes, storage=None, metadata=None):
"""
Create a histogram with the given axes.
Parameters:
- *axes: Axis objects defining the histogram dimensions
- storage: Storage type (defaults to Double)
- metadata: Any metadata to attach to the histogram
"""
@classmethod
def _from_uhi_(cls, inp: dict[str, Any]) -> "Histogram":
"""Create histogram from UHI dictionary representation."""Data Filling
Fill histograms with data points, supporting weights, samples, and multithreading.
def fill(self, *args, weight=None, sample=None, threads=None):
"""
Fill histogram with data.
Parameters:
- *args: Data arrays for each axis (must match histogram dimensionality)
- weight: Array of weights for each data point
- sample: Array of samples for Mean storage types
- threads: Number of threads for parallel filling (None for auto)
Returns:
Self for method chaining
"""Data Access
Access histogram data in various formats and with different flow bin options.
def values(self, flow=False):
"""
Get histogram bin values.
Parameters:
- flow: Include underflow/overflow bins
Returns:
numpy.ndarray of histogram values
"""
def variances(self, flow=False):
"""
Get histogram variances (if available).
Parameters:
- flow: Include underflow/overflow bins
Returns:
numpy.ndarray of variances or None if not available
"""
def counts(self, flow=False):
"""
Get histogram counts.
Parameters:
- flow: Include underflow/overflow bins
Returns:
numpy.ndarray of counts
"""
def view(self, flow=False):
"""
Get a view of the histogram data.
Parameters:
- flow: Include underflow/overflow bins
Returns:
Structured view of histogram data
"""NumPy Integration
Convert histograms to NumPy-compatible formats.
def to_numpy(self, flow=False, dd=False):
"""
Convert histogram to numpy format.
Parameters:
- flow: Include underflow/overflow bins
- dd: Return (values, *edges) for histogram, *edges for HistogramDD
Returns:
Tuple of (values, edges) or (values, *edges) for multidimensional
"""
def __array__(self, dtype=None):
"""
Array interface for numpy operations.
Parameters:
- dtype: Target dtype
Returns:
numpy.ndarray view of histogram values
"""
def _to_uhi_(self) -> dict[str, Any]:
"""
Export histogram to UHI (Universal Histogram Interface) format.
Returns:
Dictionary representation compatible with UHI standard
"""Histogram Properties
Access histogram metadata and structural information.
@property
def ndim(self) -> int:
"""Number of dimensions in the histogram."""
@property
def shape(self) -> tuple[int, ...]:
"""Shape of the histogram (number of bins per axis)."""
@property
def size(self) -> int:
"""Total number of bins in the histogram."""
@property
def axes(self) -> AxesTuple:
"""Tuple of axis objects."""
@property
def kind(self) -> Kind:
"""Histogram kind (COUNT or MEAN)."""
@property
def storage_type(self) -> type[Storage]:
"""Storage type class of the histogram."""
@property
def sum(self) -> Any:
"""Sum of all histogram bins."""
@property
def values_view(self) -> Any:
"""Direct view of histogram values array."""
@property
def variances_view(self) -> Any:
"""Direct view of histogram variances array."""Histogram Operations
Fundamental operations on histograms including copying, resetting, and statistical queries.
def copy(self, deep=True):
"""
Create a copy of the histogram.
Parameters:
- deep: Create deep copy if True, shallow copy if False
Returns:
New Histogram instance
"""
def reset(self):
"""
Reset all bin values to zero.
Returns:
Self for method chaining
"""
def empty(self, flow=False) -> bool:
"""
Check if histogram is empty.
Parameters:
- flow: Include flow bins in check
Returns:
True if all bins are zero
"""
def sum(self, flow=False):
"""
Sum all histogram bins.
Parameters:
- flow: Include flow bins in sum
Returns:
Sum of all bins (type depends on storage)
"""Arithmetic Operations
Histograms support arithmetic operations with other histograms and scalars.
def __add__(self, other):
"""Add histogram with another histogram or scalar."""
def __sub__(self, other):
"""Subtract histogram or scalar from this histogram."""
def __mul__(self, other):
"""Multiply histogram by another histogram or scalar."""
def __truediv__(self, other):
"""Divide histogram by another histogram or scalar."""
# In-place versions
def __iadd__(self, other):
"""In-place addition."""
def __isub__(self, other):
"""In-place subtraction."""
def __imul__(self, other):
"""In-place multiplication."""
def __itruediv__(self, other):
"""In-place division."""
# Comparison operations
def __eq__(self, other) -> bool:
"""Test equality with another histogram."""
def __ne__(self, other) -> bool:
"""Test inequality with another histogram."""Projection Operations
Project multi-dimensional histograms onto lower dimensions.
def project(self, *args):
"""
Project histogram onto specified axes.
Parameters:
- *args: Axis indices to project onto
Returns:
New histogram with projected data
"""Usage Examples
Basic Histogram Creation and Filling
import boost_histogram as bh
import numpy as np
# Create 1D histogram
hist = bh.Histogram(bh.axis.Regular(100, 0, 10))
# Fill with data
data = np.random.uniform(0, 10, 1000)
hist.fill(data)
# Access values
values = hist.values()
print(f"Total counts: {hist.sum()}")Weighted Filling
# Create histogram with weighted storage
hist = bh.Histogram(bh.axis.Regular(50, 0, 1), storage=bh.storage.Weight())
# Fill with weights
data = np.random.random(1000)
weights = np.random.exponential(1, 1000)
hist.fill(data, weight=weights)
# Access values and variances
values = hist.values()
variances = hist.variances()Multi-dimensional Histograms
# Create 2D histogram
hist2d = bh.Histogram(
bh.axis.Regular(50, -2, 2),
bh.axis.Regular(50, -2, 2)
)
# Fill with correlated data
x = np.random.normal(0, 1, 10000)
y = 0.5 * x + np.random.normal(0, 0.8, 10000)
hist2d.fill(x, y)
# Get 2D array
values_2d = hist2d.values()Install with Tessl CLI
npx tessl i tessl/pypi-boost-histogram