0
# Boost Histogram
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: boost-histogram
7
- **Language**: Python
8
- **Installation**: `pip install boost-histogram`
9

10
## Core Imports
11

12
```python
13
import boost_histogram as bh
14
```
15

16
For NumPy-compatible functions:
17

18
```python
19
import boost_histogram.numpy as bhnp
20
```
21

22
## Basic Usage
23

24
```python
25
import boost_histogram as bh
26
import numpy as np
27

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

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

35
# Access histogram values
36
values = hist.values()
37
centers = hist.axes[0].centers
38

39
# Create a 2D histogram
40
hist2d = bh.Histogram(
41
    bh.axis.Regular(50, -3, 3, metadata="x"),
42
    bh.axis.Regular(50, -3, 3, metadata="y")
43
)
44

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

50
# Get 2D values array
51
values_2d = hist2d.values()
52
```
53

54
## Architecture
55

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

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

64
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.
65

66
## Capabilities
67

68
### Histogram Creation and Management
69

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

72
```python { .api }
73
class Histogram:
74
    def __init__(self, *axes, storage=None, metadata=None): ...
75
    def fill(self, *args, weight=None, sample=None, threads=None): ...
76
    def values(self, flow=False): ...
77
    def variances(self, flow=False): ...
78
    def counts(self, flow=False): ...
79
    def view(self, flow=False): ...
80
    def to_numpy(self, flow=False, view=False, dd=False): ...
81
    def project(self, *args): ...
82
    def sum(self, flow=False): ...
83
    def empty(self, flow=False) -> bool: ...
84
    def reset(self): ...
85
    def copy(self, deep=True): ...
86
    def __array__(self, dtype=None): ...
87
    def __add__(self, other): ...
88
    def __sub__(self, other): ...
89
    def __mul__(self, other): ...
90
    def __truediv__(self, other): ...
91
    @classmethod
92
    def _from_uhi_(cls, inp: dict) -> "Histogram": ...
93
    def _to_uhi_(self) -> dict: ...
94
```
95

96
[Histogram Core](./histogram-core.md)
97

98
### Axis Types and Configuration
99

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

102
```python { .api }
103
class axis.Regular:
104
    def __init__(self, bins, start, stop, *, metadata=None, underflow=True, overflow=True, growth=False, circular=False, transform=None): ...
105

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

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

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

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

118
class axis.Boolean:
119
    def __init__(self, *, metadata=None): ...
120
```
121

122
[Axes](./axes.md)
123

124
### Storage Types and Accumulators
125

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

128
```python { .api }
129
class storage.Double: ...
130
class storage.Int64: ...
131
class storage.Weight: ...
132
class storage.Mean: ...
133
class storage.WeightedMean: ...
134

135
class accumulators.Sum: ...
136
class accumulators.Mean: ...
137
class accumulators.WeightedSum: ...
138
class accumulators.WeightedMean: ...
139
```
140

141
[Storage and Accumulators](./storage-accumulators.md)
142

143
### Indexing and Slicing Operations
144

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

147
```python { .api }
148
class loc(Locator):
149
    def __init__(self, value, offset=0): ...
150
    def __call__(self, axis): ...
151

152
class rebin:
153
    def __init__(self, factor=None, *, groups=None, edges=None, axis=None): ...
154
    def group_mapping(self, axis): ...
155
    def axis_mapping(self, axis): ...
156

157
class at:
158
    def __init__(self, value: int): ...
159
    def __call__(self, axis): ...
160

161
def Slicer(): ...
162

163
# Special locators
164
underflow: Locator
165
overflow: Locator
166
```
167

168
[Indexing and Operations](./indexing-operations.md)
169

170
### NumPy Integration
171

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

174
```python { .api }
175
def numpy.histogram(a, bins=10, range=None, weights=None, density=False, *, histogram=None, storage=None, threads=None): ...
176
def numpy.histogram2d(x, y, bins=10, range=None, weights=None, density=False, *, histogram=None, storage=None, threads=None): ...
177
def numpy.histogramdd(sample, bins=10, range=None, weights=None, density=False, *, histogram=None, storage=None, threads=None): ...
178
```
179

180
[NumPy Integration](./numpy-integration.md)
181

182
## Types
183

184
```python { .api }
185
from typing import Union, Sequence, Optional, Any
186
from numpy.typing import ArrayLike
187

188
# Core types
189
class Histogram: ...
190
class IndexingExpr: ...
191

192
# Enum types
193
class Kind:
194
    COUNT: str
195
    MEAN: str
196

197
# Axis types
198
class Axis: ...
199
class AxesTuple(tuple): ...
200
class ArrayTuple(tuple): ...
201
class Traits:
202
    underflow: bool
203
    overflow: bool
204
    circular: bool
205
    growth: bool
206
    continuous: bool
207
    ordered: bool
208

209
# Storage and accumulator base classes
210
class Storage: ...
211
class Accumulator: ...
212

213
# Locator types
214
class Locator: ...
215
class loc(Locator): ...
216
class rebin: ...
217
class at: ...
218
underflow: Locator
219
overflow: Locator
220

221
# Version information
222
__version__: str
223
```