<img alt="histogram" width="200" src="https://raw.githubusercontent.com/scikit-hep/hist/main/docs/_images/histlogo.png"/>

Hist

[![Actions Status][actions-badge]][actions-link] [![Documentation Status][rtd-badge]][rtd-link] [![pre-commit.ci status][pre-commit-badge]][pre-commit-link]

[![PyPI version][pypi-version]][pypi-link] [![Conda-Forge][conda-badge]][conda-link] [![PyPI platforms][pypi-platforms]][pypi-link] [![DOI][doi-badge]][doi-link] [![License][license-badge]][license-link]

[![GitHub Discussion][github-discussions-badge]][github-discussions-link] [![Gitter][gitter-badge]][gitter-link] [![Binder][binder-badge]][binder-link] [![Scikit-HEP][sk-badge]][sk-link] [![SPEC 4 — Using and Creating Nightly Wheels][spec4-badge]][spec4-link]

Hist is an analyst-friendly front-end for boost-histogram, designed for Python 3.10+ (3.6-3.9 users get older versions). See what's new.

Installation

You can install this library from PyPI with pip:

python3 -m pip install "hist[plot,fit]"

If you do not need the plotting features, you can skip the [plot] and/or [fit] extras. [fit] is not currently supported in WebAssembly.

Features

Hist currently provides everything boost-histogram provides, and the following enhancements:

• Hist augments axes with names:

  • name= is a unique label describing each axis.
  • label= is an optional string that is used in plotting (defaults to name if not provided).
  • Indexing, projection, and more support named axes.
  • Experimental NamedHist is a Hist that disables most forms of positional access, forcing users to use only names.

• The Hist class augments bh.Histogram with simpler construction:

  • flow=False is a fast way to turn off flow for the axes on construction.
  • storage= can be omitted, strings and storages can be positional.
  • data= can initialize a histogram with existing data.
  • Hist.from_columns can be used to initialize with a DataFrame or dict.
  • You can cast back and forth with boost-histogram (or any other extensions).

• Hist support QuickConstruct, an import-free construction system that does not require extra imports:

  • Use Hist.new.<axis>().<axis>().<storage>().
  • Axes names can be full (Regular) or short (Reg).
  • Histogram arguments (like data=) can go in the storage.

• Extended Histogram features:

  • Direct support for .name and .label, like axes.
  • .density() computes the density as an array.
  • .profile(remove_ax) can convert a ND COUNT histogram into a (N-1)D MEAN histogram.
  • .sort(axis) supports sorting a histogram by a categorical axis. Optionally takes a function to sort by.
  • .fill_flattened(...) will flatten and fill, including support for AwkwardArray.
  • .integrate(...), which takes the opposite arguments as .project.

• Hist implements UHI+; an extension to the UHI (Unified Histogram Indexing) system designed for import-free interactivity:

  • Uses j suffix to switch to data coordinates in access or slices.
  • Uses j suffix on slices to rebin.
  • Strings can be used directly to index into string category axes.

• Quick plotting routines encourage exploration:

  • .plot() provides 1D and 2D plots (or use plot1d(), plot2d())
  • .plot2d_full() shows 1D projects around a 2D plot.
  • .plot_ratio(...) make a ratio plot between the histogram and another histogram or callable.
  • .plot_pull(...) performs a pull plot.
  • .plot_pie() makes a pie plot.
  • .show() provides a nice str printout using Histoprint.

• Stacks: work with groups of histograms with identical axes

  • Stacks can be created with h.stack(axis), using index or name of an axis (StrCategory axes ideal).
  • You can also create with hist.stacks.Stack(h1, h2, ...), or use from_iter or from_dict.
  • You can index a stack, and set an entry with a matching histogram.
  • Stacks support .plot() and .show(), with names (plot labels default to original axes info).
  • Stacks pass through .project, *, +, and -.

• New modules

  • intervals supports frequentist coverage intervals.

• Notebook ready: Hist has gorgeous in-notebook representation.

  • No dependencies required

Usage

from hist import Hist

# Quick construction, no other imports needed:
h = (
    Hist.new.Reg(10, 0, 1, name="x", label="x-axis")
    .Var(range(10), name="y", label="y-axis")
    .Int64()
)

# Filling by names is allowed:
h.fill(y=[1, 4, 6], x=[0.3, 0.5, 0.2])

# Names can be used to manipulate the histogram:
h.project("x")
h[{"y": 0.5j + 3, "x": 5j}]

# You can access data coordinates or rebin with a `j` suffix:
h[0.3j:, ::2j]  # x from .3 to the end, y is rebinned by 2

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

Development

From a git checkout, either use nox, or run:

python -m pip install -e .[dev]

See Contributing guidelines for information on setting up a development environment.

Contributors

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

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/henryiii"><img src="https://avatars1.githubusercontent.com/u/4616906?v=4?s=100" width="100px;" alt="Henry Schreiner"/><br />_{<b>Henry Schreiner</b>}</a><br /><a href="#maintenance-henryiii" title="Maintenance">🚧</a> <a href="https://github.com/scikit-hep/hist/commits?author=henryiii" title="Code">💻</a> <a href="https://github.com/scikit-hep/hist/commits?author=henryiii" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="http://lovelybuggies.com.cn/"><img src="https://avatars3.githubusercontent.com/u/29083689?v=4?s=100" width="100px;" alt="Nino Lau"/><br />_{<b>Nino Lau</b>}</a><br /><a href="#maintenance-LovelyBuggies" title="Maintenance">🚧</a> <a href="https://github.com/scikit-hep/hist/commits?author=LovelyBuggies" title="Code">💻</a> <a href="https://github.com/scikit-hep/hist/commits?author=LovelyBuggies" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/chrisburr"><img src="https://avatars3.githubusercontent.com/u/5220533?v=4?s=100" width="100px;" alt="Chris Burr"/><br />_{<b>Chris Burr</b>}</a><br /><a href="https://github.com/scikit-hep/hist/commits?author=chrisburr" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/aminnj"><img src="https://avatars.githubusercontent.com/u/5760027?v=4?s=100" width="100px;" alt="Nick Amin"/><br />_{<b>Nick Amin</b>}</a><br /><a href="https://github.com/scikit-hep/hist/commits?author=aminnj" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="http://cern.ch/eduardo.rodrigues"><img src="https://avatars.githubusercontent.com/u/5013581?v=4?s=100" width="100px;" alt="Eduardo Rodrigues"/><br />_{<b>Eduardo Rodrigues</b>}</a><br /><a href="https://github.com/scikit-hep/hist/commits?author=eduardo-rodrigues" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="http://andrzejnovak.github.io/"><img src="https://avatars.githubusercontent.com/u/13226500?v=4?s=100" width="100px;" alt="Andrzej Novak"/><br />_{<b>Andrzej Novak</b>}</a><br /><a href="https://github.com/scikit-hep/hist/commits?author=andrzejnovak" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="http://www.matthewfeickert.com/"><img src="https://avatars.githubusercontent.com/u/5142394?v=4?s=100" width="100px;" alt="Matthew Feickert"/><br />_{<b>Matthew Feickert</b>}</a><br /><a href="https://github.com/scikit-hep/hist/commits?author=matthewfeickert" title="Code">💻</a></td> </tr> <tr> <td align="center" valign="top" width="14.28%"><a href="http://theoryandpractice.org"><img src="https://avatars.githubusercontent.com/u/4458890?v=4?s=100" width="100px;" alt="Kyle Cranmer"/><br />_{<b>Kyle Cranmer</b>}</a><br /><a href="https://github.com/scikit-hep/hist/commits?author=cranmer" title="Documentation">📖</a></td> <td align="center" valign="top" width="14.28%"><a href="http://dantrim.github.io"><img src="https://avatars.githubusercontent.com/u/7841565?v=4?s=100" width="100px;" alt="Daniel Antrim"/><br />_{<b>Daniel Antrim</b>}</a><br /><a href="https://github.com/scikit-hep/hist/commits?author=dantrim" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/nsmith-"><img src="https://avatars.githubusercontent.com/u/6587412?v=4?s=100" width="100px;" alt="Nicholas Smith"/><br />_{<b>Nicholas Smith</b>}</a><br /><a href="https://github.com/scikit-hep/hist/commits?author=nsmith-" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="http://meliache.srht.site"><img src="https://avatars.githubusercontent.com/u/5121824?v=4?s=100" width="100px;" alt="Michael Eliachevitch"/><br />_{<b>Michael Eliachevitch</b>}</a><br /><a href="https://github.com/scikit-hep/hist/commits?author=meliache" title="Code">💻</a></td> <td align="center" valign="top" width="14.28%"><a href="https://github.com/jonas-eschle"><img src="https://avatars.githubusercontent.com/u/17454848?v=4?s=100" width="100px;" alt="Jonas Eschle"/><br /><su