Skip to main content

Fast histogramming in python built on pybind11 and OpenMP.

Project description


Build Status status Documentation Status PyPI - Wheel PyPI version Conda Forge

Simple and fast histogramming in Python accelerated with OpenMP (with help from pybind11).

pygram11 provides fast functions for calculating histograms (and their statistical uncertainties). The API is very simple; documentation can be found here (you'll also find some benchmarks there).

Note: the last version of pygram11 supporting Python 2 is 0.5.2.


pygram11 only requires NumPy. To build from source you'll need a C++ compiler with C++11 support.

From PyPI

Binary wheels are provided for Linux (starting with version 0.5.0) and macOS (starting with version 0.5.1), they can be installed from PyPI via pip.

pip install pygram11

From conda-forge

For a simple installation process via the conda package manager pygram11 is part of conda-forge.

conda install pygram11 -c conda-forge

Please note that on macOS the OpenMP libraries from LLVM (libomp) and Intel (libiomp) can clash if your conda environment includes the Intel Math Kernel Library (MKL) package distributed by Anaconda. You may need to install the nomkl package to prevent the clash (Intel MKL accelerates many linear algebra operations, but does not impact pygram11):

conda install nomkl ## sometimes necessary fix (macOS only)

From Source

pip install git+

To ensure OpenMP acceleration in a build from source, read the OpenMP section of the docs. If you have a modern GCC verion on Linux, you probably don't have to worry about anything. If you are on macOS, you'll probably want to install libomp from Homebrew.

Note: For releases older than v0.5, when building from source or PyPI, pybind11 was required to be explicitly installed before pygram11 (because used pybind11 to determine include directories). Starting with v0.5 pybind11 is bundled as a git submodule for installations from source.

In Action

A histogram (with fixed bin width) of weighted data in one dimension, accelerated with OpenMP:

>>> x = np.random.randn(10000)
>>> w = np.random.uniform(0.8, 1.2, 10000)
>>> h, staterr = pygram11.histogram(x, bins=40, range=(-4, 4), weights=w, omp=True)

A histogram with fixed bin width which saves the under and overflow in the first and last bins (using __ to catch the None returned due to the absence of weights):

>>> x = np.random.randn(1000000)
>>> h, __ = pygram11.histogram(x, bins=20, range=(-3, 3), flow=True, omp=True)

A histogram in two dimensions with variable width bins:

>>> x = np.random.randn(10000)
>>> y = np.random.randn(10000)
>>> xbins = [-2.0, -1.0, -0.5, 1.5, 2.0]
>>> ybins = [-3.0, -1.5, -0.1, 0.8, 2.0]
>>> h, __ = pygram11.histogram2d(x, y, bins=[xbins, ybins])

Histogramming multiple weight variations for the same data, then putting the result in a DataFrame (the input pandas DataFrame will be interpreted as a NumPy array):

>>> weights = pd.DataFrame({"weight_a" : np.abs(np.random.randn(10000)),
...                         "weight_b" : np.random.uniform(0.5, 0.8, 10000),
...                         "weight_c" : np.random.rand(10000)})
>>> data = np.random.randn(10000)
>>> count, err = pygram11.histogram(data, bins=20, range=(-3, 3),
...                                 weights=weights, flow=True, omp=True)
>>> count_df = pd.DataFrame(count, columns=weights.columns)
>>> err_df = pd.DataFrame(err, columns=weights.columns)

I also wrote a blog post with some simple examples.

Other Libraries

  • There is an effort to develop an object oriented histogramming library for Python called boost-histogram. This library will be feature complete w.r.t. everything a physicist needs with histograms.
  • Simple and fast histogramming in Python using the NumPy C API: fast-histogram. No weights or overflow).
  • If you want to calculate histograms on a GPU in Python, check out cupy.histogram. They only have 1D histograms (no weights or overflow).

If there is something you'd like to see in pygram11, please open an issue or pull request.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pygram11, version 0.6.1
Filename, size File type Python version Upload date Hashes
Filename, size pygram11-0.6.1-cp36-cp36m-macosx_10_9_x86_64.whl (322.9 kB) File type Wheel Python version cp36 Upload date Hashes View hashes
Filename, size pygram11-0.6.1-cp36-cp36m-manylinux2010_x86_64.whl (1.3 MB) File type Wheel Python version cp36 Upload date Hashes View hashes
Filename, size pygram11-0.6.1-cp37-cp37m-macosx_10_9_x86_64.whl (322.9 kB) File type Wheel Python version cp37 Upload date Hashes View hashes
Filename, size pygram11-0.6.1-cp37-cp37m-manylinux2010_x86_64.whl (1.3 MB) File type Wheel Python version cp37 Upload date Hashes View hashes
Filename, size pygram11-0.6.1-cp38-cp38-macosx_10_9_x86_64.whl (325.7 kB) File type Wheel Python version cp38 Upload date Hashes View hashes
Filename, size pygram11-0.6.1-cp38-cp38-manylinux2010_x86_64.whl (1.3 MB) File type Wheel Python version cp38 Upload date Hashes View hashes
Filename, size pygram11-0.6.1.tar.gz (149.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page