Hist

Hist is a analyst friendly front-end for boost-histogram.

Installation

You can install this library from PyPI with pip:

python -m pip install hist

Usage

import hist

# You can create a histogram like this.
h = (
  hist.Hist()
  .Reg(10, 0 ,1, name="x", title="x-axis")
  .Variable(range(10), name="y", title="y-axis")
  .Int64()
)

# Filling by names is allowed in hist.
hist.fill(y=[1, 4, 6], x=[3, 5, 2])

# New ways to manipulate the histogram.
h.project("x")
h[{"y": 1j + 3, "x": 5j}]
...

# Elegant plotting functions.
h.plot()
h.plot2d_full()
h.plot_pull(Callable)
...

Features

• Hist augments metadata by adding names to axes; these are highly recommend and will help you track axes. There is also a special NamedHist, which will enforce all hist axes have names, and all axes will require named access.

  • name= is a unique label describing each axis
  • title= is an optional string that is used in plotting (defaults to name if not provided)
  • Indexing, projection, and more support named axes.

• The Hist class augments the bh.Histogram class with the following shortcuts, designed for interactive exploration without extensive imports:

  • Optional import-free construction system
  • Quick import-free data-coordinates and rebin syntax (use a j suffix for numbers, or strings directly in indexing expressions)

• Quick plotting routines encourage exploration:

  • .plot() provides 1D and 2D plots
  • .plot2d_full() shows 1D projects around a 2D plot
  • .plot_pull(...) performs a pull plot

Development

See CONTRIBUTING.md for information on setting up a development environment.

python -m pip install hist

Usage

import hist

# You can create a histogram like this.
h = (
  hist.Hist()
  .Reg(10, 0 ,1, name="x", title="x-axis")
  .Variable(range(10), name="y", title="y-axis")
  .Int64()
)

# Filling by names is allowed in hist.
hist.fill(y=[1, 4, 6], x=[3, 5, 2])

# New ways to manipulate the histogram.
h.project("x")
h[{"y": 1j + 3, "x": 5j}]
...

# Elegant plotting functions.
h.plot()
h.plot2d_full()
h.plot_pull(Callable)
...

Features

• Hist augments metadata by adding names to axes; these are highly recommend and will help you track axes. There is also a special NamedHist, which will enforce all hist axes have names, and all axes will require named access.

  • name= is a unique label describing each axis
  • title= is an optional string that is used in plotting (defaults to name if not provided)
  • Indexing, projection, and more support named axes.

• The Hist class augments the bh.Histogram class with the following shortcuts, designed for interactive exploration without extensive imports:

  • Optional import-free construction system
  • Quick import-free data-coordinates and rebin syntax (use a j suffix for numbers, or strings directly in indexing expressions)

• Quick plotting routines encourage exploration:

  • .plot() provides 1D and 2D plots
  • .plot2d_full() shows 1D projects around a 2D plot
  • .plot_pull(...) performs a pull plot

Development

See CONTRIBUTING.md for information on setting up a development environment.

Contributors

We would like to acknowledge the contributors that made this project possible (emoji key):

Henry Schreiner 🚧 💻 📖

Nino Lau 🚧 💻📖

This project follows the all-contributors specification.

Talks

• 2020-07-07 SciPy Proceedings
• 2020-07-17 PyHEP2020 (UPCOMING)

Acknowledgements

This library was primarily developed by Henry Schreiner and Nino Lau.

Support for this work was provided by the National Science Foundation cooperative agreement OAC-1836650 (IRIS-HEP) and OAC-1450377 (DIANA/HEP). Any opinions, findings, conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of the National Science Foundation.