Quickstart#

All of the examples will assume the following import:

```import hist
from hist import Hist
```

In boost-histogram, a histogram is collection of Axis objects and a storage.

Making a histogram#

You can make a histogram like this:

```h = Hist(hist.axis.Regular(bins=10, start=0, stop=1, name="x"))
```

If you’d like to type less, you can leave out the keywords for the numbers.

```h = Hist(hist.axis.Regular(10, 0, 1, name="x"))
```

Hist also supports a “quick-construct” system, which does not require using anything beyond the `Hist` class:

```h = Hist.new.Regular(10, 0, 1, name="x").Double()
```

Note that you have to specify the storage at the end (but this does make it easier to use `Weight` or other useful storages).

The exact same syntax is used any number of dimensions:

```hist3D = (
Hist.new.Regular(10, 0, 100, circular=True, name="x")
.Regular(10, 0.0, 10.0, name="y")
.Variable([1, 2, 3, 4, 5, 5.5, 6], name="z")
.Weight()
)
```

See Axes and Transform.

You can also select a different storage with the `storage=` keyword argument; see Storages for details about the other storages.

Filling a histogram#

Once you have a histogram, you can fill it using `.fill`. Ideally, you should give arrays, but single values work as well:

```h = Hist(hist.axis.Regular(10, 0.0, 1.0, name="x"))
h.fill(0.9)
h.fill([0.9, 0.3, 0.4])
```

Slicing and rebinning#

You can slice into a histogram using bin coordinates or data coordinates by appending a `j` to an index. You can also rebin with a number ending in `j` in the third slice entry, or remove an entire axis using `sum`:

```h = Hist(
hist.axis.Regular(10, 0, 1, name="x"),
hist.axis.Regular(10, 0, 1, name="y"),
hist.axis.Regular(10, 0, 1, name="z"),
)
mini = h[1:5, 0.2j:0.9j, sum]
# Will be 4 bins x 7 bins
```

See Indexing.

Accessing the contents#

You can use `hist.values()` to get a NumPy array from any histogram. You can get the variances with `hist.variances()`, though if you fill an unweighted storage with weights, this will return None, as you no longer can compute the variances correctly (please use a weighted storage if you need to). You can also get the number of entries in a bin with `.counts()`; this will return counts even if your storage is a mean storage. See Plots.

If you want access to the full underlying storage, `.view()` will return a NumPy array for simple storages or a RecArray-like wrapper for non-simple storages. Most methods offer an optional keyword argument that you can pass, `flow=True`, to enable the under and overflow bins (disabled by default).

```np_array = h.view()
```

Setting the contents#

You can set the contents directly as you would a NumPy array; you can set either values or arrays at a time:

```h[2] = 3.5
h[hist.underflow] = 0  # set the underflow bin
hist2d[3:5, 2:4] = np.eye(2)  # set with array
```

For non-simple storages, you can add an extra dimension that matches the constructor arguments of that accumulator. For example, if you want to fill a Weight histogram with three values, you can dimension:

```h[0:3] = [[1, 0.1], [2, 0.2], [3, 0.3]]
```

See Indexing.

Accessing Axes#

The axes are directly available in the histogram, and you can access a variety of properties, such as the `edges` or the `centers`. All properties and methods are also available directly on the `axes` tuple:

```ax0 = h.axes[0]
X, Y = h.axes.centers
```

See Axes.

Saving Histograms#

You can save histograms using pickle:

```import pickle

with open("file.pkl", "wb") as f:
pickle.dump(h, f)

with open("file.pkl", "rb") as f:

assert h == h2
```

Special care was taken to ensure that this is fast and efficient. Please use the latest version of the Pickle protocol you feel comfortable using; you cannot use version 0, the version that was default on Python 2. The most recent versions provide performance benefits.

Computing with Histograms#

As an complete example, let’s say you wanted to compute and plot the density, without using `.density()`:

```import functools
import operator

import matplotlib.pyplot as plt
import numpy as np

import hist

# Make a 2D histogram
hist2d = hist.Hist(hist.axis.Regular(50, -3, 3), hist.axis.Regular(50, -3, 3))

# Fill with Gaussian random values
hist2d.fill(np.random.normal(size=1_000_000), np.random.normal(size=1_000_000))

# Compute the areas of each bin
areas = functools.reduce(operator.mul, hist2d.axes.widths)

# Compute the density
density = hist2d.values() / hist2d.sum() / areas

# Make the plot
fig, ax = plt.subplots()
mesh = ax.pcolormesh(*hist2d.axes.edges.T, density.T)
fig.colorbar(mesh)
plt.savefig("simple_density.png")
```