0
# Axes
1

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

4
## Capabilities
5

6
### Base Axis Interface
7

8
Common interface shared by all axis types providing fundamental operations.
9

10
```python { .api }
11
class Axis:
12
    def index(self, value):
13
        """
14
        Return the bin index for a given value.
15

16
        Parameters:
17
        - value: Value to find index for
18

19
        Returns:
20
        int: Bin index
21
        """
22

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

27
        Parameters:
28
        - index: Bin index
29

30
        Returns:
31
        Value at the bin center or representative value
32
        """
33

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

38
        Parameters:
39
        - index: Bin index
40

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

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

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

53
    @property
54
    def edges(self):
55
        """Array of bin edges."""
56

57
    @property
58
    def centers(self):
59
        """Array of bin centers."""
60

61
    @property
62
    def widths(self):
63
        """Array of bin widths."""
64

65
    @property
66
    def traits(self) -> Traits:
67
        """Axis traits (underflow, overflow, growth, etc.)."""
68
```
69

70
### Regular Axis
71

72
Evenly spaced bins with configurable range and optional transformations.
73

74
```python { .api }
75
class Regular(Axis):
76
    def __init__(
77
        self,
78
        bins: int,
79
        start: float,
80
        stop: float,
81
        *,
82
        metadata=None,
83
        underflow: bool = True,
84
        overflow: bool = True,
85
        growth: bool = False,
86
        circular: bool = False,
87
        transform=None
88
    ):
89
        """
90
        Create regularly spaced bins.
91

92
        Parameters:
93
        - bins: Number of bins between start and stop
94
        - start: Lower edge of first bin
95
        - stop: Upper edge of last bin
96
        - metadata: User metadata
97
        - underflow: Enable underflow bin
98
        - overflow: Enable overflow bin
99
        - growth: Allow axis to grow beyond bounds
100
        - circular: Enable circular/periodic behavior
101
        - transform: Transform function (log, sqrt, etc.)
102
        """
103

104
    @property
105
    def transform(self):
106
        """Transform applied to axis (if any)."""
107
```
108

109
### Variable Axis
110

111
Non-uniform bin widths defined by explicit edge positions.
112

113
```python { .api }
114
class Variable(Axis):
115
    def __init__(
116
        self,
117
        edges,
118
        *,
119
        metadata=None,
120
        underflow: bool = True,
121
        overflow: bool = True,
122
        growth: bool = False,
123
        circular: bool = False
124
    ):
125
        """
126
        Create variable-width bins.
127

128
        Parameters:
129
        - edges: Array-like sequence of bin edges (len(edges)-1 bins created)
130
        - metadata: User metadata
131
        - underflow: Enable underflow bin
132
        - overflow: Enable overflow bin
133
        - growth: Allow axis to grow beyond bounds
134
        - circular: Enable circular/periodic behavior
135
        """
136
```
137

138
### Integer Axis
139

140
Consecutive integer bins for discrete data.
141

142
```python { .api }
143
class Integer(Axis):
144
    def __init__(
145
        self,
146
        start: int,
147
        stop: int,
148
        *,
149
        metadata=None,
150
        underflow: bool = True,
151
        overflow: bool = True,
152
        growth: bool = False,
153
        circular: bool = False
154
    ):
155
        """
156
        Create integer bins for discrete values.
157

158
        Parameters:
159
        - start: First integer value
160
        - stop: One past the last integer value
161
        - metadata: User metadata
162
        - underflow: Enable underflow bin
163
        - overflow: Enable overflow bin
164
        - growth: Allow axis to grow beyond bounds
165
        - circular: Enable circular/periodic behavior
166
        """
167
```
168

169
### Category Axes
170

171
Categorical bins for labeled data with string or integer categories.
172

173
```python { .api }
174
class StrCategory(Axis):
175
    def __init__(
176
        self,
177
        categories,
178
        *,
179
        metadata=None,
180
        growth: bool = False,
181
        overflow: bool = True
182
    ):
183
        """
184
        Create string category bins.
185

186
        Parameters:
187
        - categories: Iterable of string categories
188
        - metadata: User metadata
189
        - growth: Allow new categories to be added dynamically
190
        - overflow: Include overflow bin for uncategorized items
191
        """
192

193
class IntCategory(Axis):
194
    def __init__(
195
        self,
196
        categories,
197
        *,
198
        metadata=None,
199
        growth: bool = False,
200
        overflow: bool = True
201
    ):
202
        """
203
        Create integer category bins.
204

205
        Parameters:
206
        - categories: Iterable of integer categories
207
        - metadata: User metadata
208
        - growth: Allow new categories to be added dynamically
209
        - overflow: Include overflow bin for uncategorized items
210
        """
211
```
212

213
### Boolean Axis
214

215
Special axis for boolean values.
216

217
```python { .api }
218
class Boolean(Axis):
219
    def __init__(self, *, metadata=None):
220
        """
221
        Create boolean axis with True/False bins.
222

223
        Parameters:
224
        - metadata: User metadata
225
        """
226
```
227

228
### Axis Collections
229

230
Structured containers for multiple axes with collective operations.
231

232
```python { .api }
233
class AxesTuple(tuple):
234
    """Tuple of axes with collective operations."""
235

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

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

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

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

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

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

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

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

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

268
    def broadcast(self):
269
        """Broadcast arrays to full representation."""
270
```
271

272
### Axis Traits
273

274
Configuration properties describing axis behavior.
275

276
```python { .api }
277
class Traits:
278
    underflow: bool = False
279
    overflow: bool = False
280
    circular: bool = False
281
    growth: bool = False
282
    continuous: bool = False
283
    ordered: bool = False
284

285
    @property
286
    def discrete(self) -> bool:
287
        """True if axis is not continuous."""
288
```
289

290
### Transform Classes
291

292
Mathematical transformations for regular axes.
293

294
```python { .api }
295
class AxisTransform:
296
    """Base class for axis transformations."""
297

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

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

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

308
# Pre-configured transforms
309
log: AxisTransform  # Logarithmic transform
310
sqrt: AxisTransform  # Square root transform
311
```
312

313
## Usage Examples
314

315
### Regular Axis with Various Configurations
316

317
```python
318
import boost_histogram as bh
319

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

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

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

329
# Circular axis for angular data
330
axis4 = bh.axis.Regular(360, 0, 360, circular=True)
331
```
332

333
### Variable Width Bins
334

335
```python
336
# Define custom bin edges
337
import numpy as np
338

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

343
# Custom irregular spacing
344
edges = [0, 1, 2, 5, 10, 20, 50, 100]
345
axis = bh.axis.Variable(edges)
346
```
347

348
### Categorical Data
349

350
```python
351
# String categories
352
categories = ["A", "B", "C", "D", "other"]
353
axis1 = bh.axis.StrCategory(categories)
354

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

358
# Integer categories
359
int_categories = [1, 5, 10, 25, 50]
360
axis3 = bh.axis.IntCategory(int_categories)
361
```
362

363
### Multi-Axis Histograms
364

365
```python
366
# 3D histogram with mixed axis types
367
hist = bh.Histogram(
368
    bh.axis.Regular(50, 0, 10, metadata="energy"),
369
    bh.axis.Variable([0, 1, 2, 5, 10, 20], metadata="time"),
370
    bh.axis.StrCategory(["signal", "background"], metadata="type")
371
)
372

373
# Access axis properties
374
print(f"Shape: {hist.shape}")
375
print(f"Axis 0 centers: {hist.axes[0].centers}")
376
print(f"All axis sizes: {hist.axes.size}")
377
```
378

379
### Axis Indexing and Value Conversion
380

381
```python
382
axis = bh.axis.Regular(100, 0, 10)
383

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

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

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

393
# Access all edges and centers
394
all_edges = axis.edges
395
all_centers = axis.centers
396
all_widths = axis.widths
397
```