or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

axes.mdhistogram-core.mdindex.mdindexing-operations.mdnumpy-integration.mdstorage-accumulators.md
tile.json

tessl/pypi-boost-histogram

The Boost::Histogram Python wrapper providing fast histogram implementations with full power and flexibility for scientific computing.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/boost-histogram@1.6.x

To install, run

npx @tessl/cli install tessl/pypi-boost-histogram@1.6.0

index.mddocs/

Boost Histogram

The Boost::Histogram Python wrapper providing one of the fastest histogram implementations available while maintaining full power and flexibility. This library serves as a foundational tool for scientific computing and data analysis, offering comprehensive histogram creation, manipulation, and analysis capabilities with support for multi-dimensional histograms, various axis types, multiple storage types, and efficient algorithms for filling, slicing, and statistical operations.

Package Information

  • Package Name: boost-histogram
  • Language: Python
  • Installation: pip install boost-histogram

Core Imports

import boost_histogram as bh

For NumPy-compatible functions:

import boost_histogram.numpy as bhnp

Basic Usage

import boost_histogram as bh
import numpy as np

# Create a 1D histogram with regular axis
hist = bh.Histogram(bh.axis.Regular(50, -3, 3))

# Fill with sample data
data = np.random.normal(0, 1, 1000)
hist.fill(data)

# Access histogram values
values = hist.values()
centers = hist.axes[0].centers

# Create a 2D histogram
hist2d = bh.Histogram(
    bh.axis.Regular(50, -3, 3, metadata="x"),
    bh.axis.Regular(50, -3, 3, metadata="y")
)

# Fill with 2D data
x_data = np.random.normal(0, 1, 1000)
y_data = np.random.normal(0, 1, 1000)
hist2d.fill(x_data, y_data)

# Get 2D values array
values_2d = hist2d.values()

Architecture

Boost-histogram is built on the Boost::Histogram C++ library and follows a flexible architecture:

  • Histogram: Main container managing axes, storage, and operations
  • Axes: Define bin boundaries and coordinate systems (Regular, Variable, Integer, Category, Boolean)
  • Storage: Handle data accumulation (Int64, Double, Weight, Mean, etc.)
  • Accumulators: Advanced statistical accumulators for complex analyses
  • Views: Provide structured access to histogram data with named fields

This design provides excellent performance through C++ implementation while maintaining Python ease of use, making it ideal for high-energy physics, data science, and any application requiring fast, flexible histogram operations.

Capabilities

Histogram Creation and Management

Core histogram functionality for creating, configuring, and managing histograms with various axis types and storage options.

class Histogram:
    def __init__(self, *axes, storage=None, metadata=None): ...
    def fill(self, *args, weight=None, sample=None, threads=None): ...
    def values(self, flow=False): ...
    def variances(self, flow=False): ...
    def counts(self, flow=False): ...
    def view(self, flow=False): ...
    def to_numpy(self, flow=False, view=False, dd=False): ...
    def project(self, *args): ...
    def sum(self, flow=False): ...
    def empty(self, flow=False) -> bool: ...
    def reset(self): ...
    def copy(self, deep=True): ...
    def __array__(self, dtype=None): ...
    def __add__(self, other): ...
    def __sub__(self, other): ...
    def __mul__(self, other): ...
    def __truediv__(self, other): ...
    @classmethod
    def _from_uhi_(cls, inp: dict) -> "Histogram": ...
    def _to_uhi_(self) -> dict: ...

Histogram Core

Axis Types and Configuration

Comprehensive axis types for defining histogram bin structures, including regular, variable, categorical, and specialized axes with extensive configuration options.

class axis.Regular:
    def __init__(self, bins, start, stop, *, metadata=None, underflow=True, overflow=True, growth=False, circular=False, transform=None): ...

class axis.Variable:
    def __init__(self, edges, *, metadata=None, underflow=True, overflow=True, growth=False, circular=False): ...

class axis.Integer:
    def __init__(self, start, stop, *, metadata=None, underflow=True, overflow=True, growth=False, circular=False): ...

class axis.StrCategory:
    def __init__(self, categories, *, metadata=None, growth=False, overflow=True): ...

class axis.IntCategory:
    def __init__(self, categories, *, metadata=None, growth=False, overflow=True): ...

class axis.Boolean:
    def __init__(self, *, metadata=None): ...

Axes

Storage Types and Accumulators

Different storage backends for histogram data, from simple counting to complex statistical accumulators with variance tracking and weighted operations.

class storage.Double: ...
class storage.Int64: ...
class storage.Weight: ...
class storage.Mean: ...
class storage.WeightedMean: ...

class accumulators.Sum: ...
class accumulators.Mean: ...
class accumulators.WeightedSum: ...
class accumulators.WeightedMean: ...

Storage and Accumulators

Indexing and Slicing Operations

Advanced indexing capabilities for accessing and modifying histogram data with locators, rebinning, and flow bin management.

class loc(Locator):
    def __init__(self, value, offset=0): ...
    def __call__(self, axis): ...

class rebin:
    def __init__(self, factor=None, *, groups=None, edges=None, axis=None): ...
    def group_mapping(self, axis): ...
    def axis_mapping(self, axis): ...

class at:
    def __init__(self, value: int): ...
    def __call__(self, axis): ...

def Slicer(): ...

# Special locators
underflow: Locator
overflow: Locator

Indexing and Operations

NumPy Integration

NumPy-compatible histogram functions providing familiar interfaces while leveraging boost-histogram's performance advantages.

def numpy.histogram(a, bins=10, range=None, weights=None, density=False, *, histogram=None, storage=None, threads=None): ...
def numpy.histogram2d(x, y, bins=10, range=None, weights=None, density=False, *, histogram=None, storage=None, threads=None): ...
def numpy.histogramdd(sample, bins=10, range=None, weights=None, density=False, *, histogram=None, storage=None, threads=None): ...

NumPy Integration

Types

from typing import Union, Sequence, Optional, Any
from numpy.typing import ArrayLike

# Core types
class Histogram: ...
class IndexingExpr: ...

# Enum types
class Kind:
    COUNT: str
    MEAN: str

# Axis types
class Axis: ...
class AxesTuple(tuple): ...
class ArrayTuple(tuple): ...
class Traits:
    underflow: bool
    overflow: bool
    circular: bool
    growth: bool
    continuous: bool
    ordered: bool

# Storage and accumulator base classes
class Storage: ...
class Accumulator: ...

# Locator types
class Locator: ...
class loc(Locator): ...
class rebin: ...
class at: ...
underflow: Locator
overflow: Locator

# Version information
__version__: str