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

Overview

Eval results

Files

Axes

Name: tessl/pypi-boost-histogram
Author: tessl

Comprehensive axis types for defining histogram bin structures, including regular, variable, categorical, and specialized axes with extensive configuration options. Axes define the coordinate systems and binning strategies for histograms.

Capabilities

Base Axis Interface

Common interface shared by all axis types providing fundamental operations.

class Axis:
    def index(self, value):
        """
        Return the bin index for a given value.

        Parameters:
        - value: Value to find index for

        Returns:
        int: Bin index
        """

    def value(self, index):
        """
        Return the value for a given bin index.

        Parameters:
        - index: Bin index

        Returns:
        Value at the bin center or representative value
        """

    def bin(self, index):
        """
        Return bin edges or representative value for an index.

        Parameters:
        - index: Bin index

        Returns:
        Tuple of (lower, upper) edges for continuous axes, or bin value for discrete axes
        """

    @property
    def size(self) -> int:
        """Number of bins excluding underflow/overflow."""

    @property
    def extent(self) -> int:
        """Number of bins including underflow/overflow."""

    @property
    def edges(self):
        """Array of bin edges."""

    @property
    def centers(self):
        """Array of bin centers."""

    @property
    def widths(self):
        """Array of bin widths."""

    @property
    def traits(self) -> Traits:
        """Axis traits (underflow, overflow, growth, etc.)."""

Regular Axis

Evenly spaced bins with configurable range and optional transformations.

class Regular(Axis):
    def __init__(
        self,
        bins: int,
        start: float,
        stop: float,
        *,
        metadata=None,
        underflow: bool = True,
        overflow: bool = True,
        growth: bool = False,
        circular: bool = False,
        transform=None
    ):
        """
        Create regularly spaced bins.

        Parameters:
        - bins: Number of bins between start and stop
        - start: Lower edge of first bin
        - stop: Upper edge of last bin
        - metadata: User metadata
        - underflow: Enable underflow bin
        - overflow: Enable overflow bin
        - growth: Allow axis to grow beyond bounds
        - circular: Enable circular/periodic behavior
        - transform: Transform function (log, sqrt, etc.)
        """

    @property
    def transform(self):
        """Transform applied to axis (if any)."""

Variable Axis

Non-uniform bin widths defined by explicit edge positions.

class Variable(Axis):
    def __init__(
        self,
        edges,
        *,
        metadata=None,
        underflow: bool = True,
        overflow: bool = True,
        growth: bool = False,
        circular: bool = False
    ):
        """
        Create variable-width bins.

        Parameters:
        - edges: Array-like sequence of bin edges (len(edges)-1 bins created)
        - metadata: User metadata
        - underflow: Enable underflow bin
        - overflow: Enable overflow bin
        - growth: Allow axis to grow beyond bounds
        - circular: Enable circular/periodic behavior
        """

Integer Axis

Consecutive integer bins for discrete data.

class Integer(Axis):
    def __init__(
        self,
        start: int,
        stop: int,
        *,
        metadata=None,
        underflow: bool = True,
        overflow: bool = True,
        growth: bool = False,
        circular: bool = False
    ):
        """
        Create integer bins for discrete values.

        Parameters:
        - start: First integer value
        - stop: One past the last integer value
        - metadata: User metadata
        - underflow: Enable underflow bin
        - overflow: Enable overflow bin
        - growth: Allow axis to grow beyond bounds
        - circular: Enable circular/periodic behavior
        """

Category Axes

Categorical bins for labeled data with string or integer categories.

class StrCategory(Axis):
    def __init__(
        self,
        categories,
        *,
        metadata=None,
        growth: bool = False,
        overflow: bool = True
    ):
        """
        Create string category bins.

        Parameters:
        - categories: Iterable of string categories
        - metadata: User metadata
        - growth: Allow new categories to be added dynamically
        - overflow: Include overflow bin for uncategorized items
        """

class IntCategory(Axis):
    def __init__(
        self,
        categories,
        *,
        metadata=None,
        growth: bool = False,
        overflow: bool = True
    ):
        """
        Create integer category bins.

        Parameters:
        - categories: Iterable of integer categories
        - metadata: User metadata
        - growth: Allow new categories to be added dynamically
        - overflow: Include overflow bin for uncategorized items
        """

Boolean Axis

Special axis for boolean values.

class Boolean(Axis):
    def __init__(self, *, metadata=None):
        """
        Create boolean axis with True/False bins.

        Parameters:
        - metadata: User metadata
        """

Axis Collections

Structured containers for multiple axes with collective operations.

class AxesTuple(tuple):
    """Tuple of axes with collective operations."""

    @property
    def size(self) -> tuple[int, ...]:
        """Size of each axis."""

    @property
    def extent(self) -> tuple[int, ...]:
        """Extent of each axis (including flow bins)."""

    @property
    def centers(self) -> ArrayTuple:
        """Meshgrid of axis centers."""

    @property
    def edges(self) -> ArrayTuple:
        """Meshgrid of axis edges."""

    @property
    def widths(self) -> ArrayTuple:
        """Meshgrid of axis widths."""

    def value(self, *indexes) -> tuple:
        """Values for given indices across all axes."""

    def index(self, *values) -> tuple:
        """Indices for given values across all axes."""

    def bin(self, *indexes) -> tuple:
        """Bin edges/values for given indices across all axes."""

class ArrayTuple(tuple):
    """Tuple of arrays with broadcasting and reduction operations."""

    def broadcast(self):
        """Broadcast arrays to full representation."""

Axis Traits

Configuration properties describing axis behavior.

class Traits:
    underflow: bool = False
    overflow: bool = False
    circular: bool = False
    growth: bool = False
    continuous: bool = False
    ordered: bool = False

    @property
    def discrete(self) -> bool:
        """True if axis is not continuous."""

Transform Classes

Mathematical transformations for regular axes.

class AxisTransform:
    """Base class for axis transformations."""

    def forward(self, value: float) -> float:
        """Apply forward transformation."""

    def inverse(self, value: float) -> float:
        """Apply inverse transformation."""

class Pow(AxisTransform):
    def __init__(self, power: float):
        """Power transformation: x^power."""

# Pre-configured transforms
log: AxisTransform  # Logarithmic transform
sqrt: AxisTransform  # Square root transform

Usage Examples

Regular Axis with Various Configurations

import boost_histogram as bh

# Basic regular axis
axis1 = bh.axis.Regular(100, 0, 10)

# Regular axis with log transform
axis2 = bh.axis.Regular(50, 1, 100, transform=bh.axis.transform.log)

# Growing axis that expands automatically
axis3 = bh.axis.Regular(20, -5, 5, growth=True)

# Circular axis for angular data
axis4 = bh.axis.Regular(360, 0, 360, circular=True)

Variable Width Bins

# Define custom bin edges
import numpy as np

# Logarithmic spacing
edges = np.logspace(0, 2, 21)  # 20 bins from 1 to 100
axis = bh.axis.Variable(edges)

# Custom irregular spacing
edges = [0, 1, 2, 5, 10, 20, 50, 100]
axis = bh.axis.Variable(edges)

Categorical Data

# String categories
categories = ["A", "B", "C", "D", "other"]
axis1 = bh.axis.StrCategory(categories)

# Growing string categories
axis2 = bh.axis.StrCategory([], growth=True)  # Start empty, add as needed

# Integer categories
int_categories = [1, 5, 10, 25, 50]
axis3 = bh.axis.IntCategory(int_categories)

Multi-Axis Histograms

# 3D histogram with mixed axis types
hist = bh.Histogram(
    bh.axis.Regular(50, 0, 10, metadata="energy"),
    bh.axis.Variable([0, 1, 2, 5, 10, 20], metadata="time"),
    bh.axis.StrCategory(["signal", "background"], metadata="type")
)

# Access axis properties
print(f"Shape: {hist.shape}")
print(f"Axis 0 centers: {hist.axes[0].centers}")
print(f"All axis sizes: {hist.axes.size}")

Axis Indexing and Value Conversion

axis = bh.axis.Regular(100, 0, 10)

# Convert values to indices
idx = axis.index(5.5)  # Get bin index for value 5.5

# Convert indices to values  
value = axis.value(50)  # Get center value of bin 50

# Get bin edges
edges = axis.bin(25)  # Get (lower, upper) edges of bin 25

# Access all edges and centers
all_edges = axis.edges
all_centers = axis.centers
all_widths = axis.widths

Install with Tessl CLI