Hist

Hist is a analyst friendly front-end for boost-histogram, designed for Python 3.7+ (3.6 users get version 2.3).

Installation

You can install this library from PyPI with pip:

python3 -m pip install "hist[plot]"

If you do not need the plotting features, you can skip the [plot] extra.

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

  • The Hist class augments bh.Histogram with reduced typing construction:

    • Optional import-free construction system
    • flow=False is a fast way to turn off flow for the axes on construction
    • Storages can be given by string
    • storage= can be omitted
    • data= can initialize a histogram with existing data
    • Hist.from_columns can be used to initialize with a DataFrame or dict

  • 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

  • Extended Histogram features:

    • .density() computes the density as an array
    • .profile(remove_ax) can convert a ND COUNT histogram into a (N-1)D MEAN histogram

  • 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=[3, 5, 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[.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, run:

python -m pip install -e .[dev]

GitHub

https://github.com/scikit-hep/hist