0
# Histogram Core
1

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

4
## Capabilities
5

6
### Histogram Creation
7

8
Create histograms with specified axes and optional storage configuration.
9

10
```python { .api }
11
class Histogram:
12
    def __init__(self, *axes, storage=None, metadata=None):
13
        """
14
        Create a histogram with the given axes.
15

16
        Parameters:
17
        - *axes: Axis objects defining the histogram dimensions
18
        - storage: Storage type (defaults to Double)
19
        - metadata: Any metadata to attach to the histogram
20
        """
21

22
    @classmethod
23
    def _from_uhi_(cls, inp: dict[str, Any]) -> "Histogram":
24
        """Create histogram from UHI dictionary representation."""
25
```
26

27
### Data Filling
28

29
Fill histograms with data points, supporting weights, samples, and multithreading.
30

31
```python { .api }
32
def fill(self, *args, weight=None, sample=None, threads=None):
33
    """
34
    Fill histogram with data.
35

36
    Parameters:
37
    - *args: Data arrays for each axis (must match histogram dimensionality)
38
    - weight: Array of weights for each data point
39
    - sample: Array of samples for Mean storage types
40
    - threads: Number of threads for parallel filling (None for auto)
41

42
    Returns:
43
    Self for method chaining
44
    """
45
```
46

47
### Data Access
48

49
Access histogram data in various formats and with different flow bin options.
50

51
```python { .api }
52
def values(self, flow=False):
53
    """
54
    Get histogram bin values.
55

56
    Parameters:
57
    - flow: Include underflow/overflow bins
58

59
    Returns:
60
    numpy.ndarray of histogram values
61
    """
62

63
def variances(self, flow=False):
64
    """
65
    Get histogram variances (if available).
66

67
    Parameters:
68
    - flow: Include underflow/overflow bins
69

70
    Returns:
71
    numpy.ndarray of variances or None if not available
72
    """
73

74
def counts(self, flow=False):
75
    """
76
    Get histogram counts.
77

78
    Parameters:
79
    - flow: Include underflow/overflow bins
80

81
    Returns:
82
    numpy.ndarray of counts
83
    """
84

85
def view(self, flow=False):
86
    """
87
    Get a view of the histogram data.
88

89
    Parameters:
90
    - flow: Include underflow/overflow bins
91

92
    Returns:
93
    Structured view of histogram data
94
    """
95
```
96

97
### NumPy Integration
98

99
Convert histograms to NumPy-compatible formats.
100

101
```python { .api }
102
def to_numpy(self, flow=False, dd=False):
103
    """
104
    Convert histogram to numpy format.
105

106
    Parameters:
107
    - flow: Include underflow/overflow bins
108
    - dd: Return (values, *edges) for histogram, *edges for HistogramDD
109

110
    Returns:
111
    Tuple of (values, edges) or (values, *edges) for multidimensional
112
    """
113

114
def __array__(self, dtype=None):
115
    """
116
    Array interface for numpy operations.
117

118
    Parameters:
119
    - dtype: Target dtype
120

121
    Returns:
122
    numpy.ndarray view of histogram values
123
    """
124

125
def _to_uhi_(self) -> dict[str, Any]:
126
    """
127
    Export histogram to UHI (Universal Histogram Interface) format.
128

129
    Returns:
130
    Dictionary representation compatible with UHI standard
131
    """
132
```
133

134
### Histogram Properties
135

136
Access histogram metadata and structural information.
137

138
```python { .api }
139
@property
140
def ndim(self) -> int:
141
    """Number of dimensions in the histogram."""
142

143
@property
144
def shape(self) -> tuple[int, ...]:
145
    """Shape of the histogram (number of bins per axis)."""
146

147
@property
148
def size(self) -> int:
149
    """Total number of bins in the histogram."""
150

151
@property
152
def axes(self) -> AxesTuple:
153
    """Tuple of axis objects."""
154

155
@property
156
def kind(self) -> Kind:
157
    """Histogram kind (COUNT or MEAN)."""
158

159
@property
160
def storage_type(self) -> type[Storage]:
161
    """Storage type class of the histogram."""
162

163
@property  
164
def sum(self) -> Any:
165
    """Sum of all histogram bins."""
166

167
@property
168
def values_view(self) -> Any:
169
    """Direct view of histogram values array."""
170

171
@property
172
def variances_view(self) -> Any:
173
    """Direct view of histogram variances array."""
174
```
175

176
### Histogram Operations
177

178
Fundamental operations on histograms including copying, resetting, and statistical queries.
179

180
```python { .api }
181
def copy(self, deep=True):
182
    """
183
    Create a copy of the histogram.
184

185
    Parameters:
186
    - deep: Create deep copy if True, shallow copy if False
187

188
    Returns:
189
    New Histogram instance
190
    """
191

192
def reset(self):
193
    """
194
    Reset all bin values to zero.
195

196
    Returns:
197
    Self for method chaining
198
    """
199

200
def empty(self, flow=False) -> bool:
201
    """
202
    Check if histogram is empty.
203

204
    Parameters:
205
    - flow: Include flow bins in check
206

207
    Returns:
208
    True if all bins are zero
209
    """
210

211
def sum(self, flow=False):
212
    """
213
    Sum all histogram bins.
214

215
    Parameters:
216
    - flow: Include flow bins in sum
217

218
    Returns:
219
    Sum of all bins (type depends on storage)
220
    """
221
```
222

223
### Arithmetic Operations
224

225
Histograms support arithmetic operations with other histograms and scalars.
226

227
```python { .api }
228
def __add__(self, other):
229
    """Add histogram with another histogram or scalar."""
230

231
def __sub__(self, other):
232
    """Subtract histogram or scalar from this histogram."""
233

234
def __mul__(self, other):
235
    """Multiply histogram by another histogram or scalar."""
236

237
def __truediv__(self, other):
238
    """Divide histogram by another histogram or scalar."""
239

240
# In-place versions
241
def __iadd__(self, other):
242
    """In-place addition."""
243

244
def __isub__(self, other):
245
    """In-place subtraction."""
246

247
def __imul__(self, other):
248
    """In-place multiplication."""
249

250
def __itruediv__(self, other):
251
    """In-place division."""
252

253
# Comparison operations
254
def __eq__(self, other) -> bool:
255
    """Test equality with another histogram."""
256

257
def __ne__(self, other) -> bool:
258
    """Test inequality with another histogram."""
259
```
260

261
### Projection Operations
262

263
Project multi-dimensional histograms onto lower dimensions.
264

265
```python { .api }
266
def project(self, *args):
267
    """
268
    Project histogram onto specified axes.
269

270
    Parameters:
271
    - *args: Axis indices to project onto
272

273
    Returns:
274
    New histogram with projected data
275
    """
276
```
277

278
## Usage Examples
279

280
### Basic Histogram Creation and Filling
281

282
```python
283
import boost_histogram as bh
284
import numpy as np
285

286
# Create 1D histogram
287
hist = bh.Histogram(bh.axis.Regular(100, 0, 10))
288

289
# Fill with data
290
data = np.random.uniform(0, 10, 1000)
291
hist.fill(data)
292

293
# Access values
294
values = hist.values()
295
print(f"Total counts: {hist.sum()}")
296
```
297

298
### Weighted Filling
299

300
```python
301
# Create histogram with weighted storage
302
hist = bh.Histogram(bh.axis.Regular(50, 0, 1), storage=bh.storage.Weight())
303

304
# Fill with weights
305
data = np.random.random(1000)
306
weights = np.random.exponential(1, 1000)
307
hist.fill(data, weight=weights)
308

309
# Access values and variances
310
values = hist.values()
311
variances = hist.variances()
312
```
313

314
### Multi-dimensional Histograms
315

316
```python
317
# Create 2D histogram
318
hist2d = bh.Histogram(
319
    bh.axis.Regular(50, -2, 2),
320
    bh.axis.Regular(50, -2, 2)
321
)
322

323
# Fill with correlated data
324
x = np.random.normal(0, 1, 10000)
325
y = 0.5 * x + np.random.normal(0, 0.8, 10000)
326
hist2d.fill(x, y)
327

328
# Get 2D array
329
values_2d = hist2d.values()
330
```