Metadata-Version: 2.1
Name: hist
Version: 2.2.0
Summary: Hist classes and utilities
Home-page: https://github.com/scikit-hep/hist
Author: Henry Schreiner
Author-email: henry.schreiner@cern.ch
Maintainer: The Scikit-HEP admins
Maintainer-email: scikit-hep-admins@googlegroups.com
License: BSD-3-Clause
Keywords: histogram,boost-histogram
Platform: Any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: boost-histogram (~=1.0.0)
Requires-Dist: histoprint (>=1.6)
Requires-Dist: numpy (>=1.13.3)
Requires-Dist: typing-extensions ; python_version < "3.8"
Provides-Extra: all
Requires-Dist: Sphinx (>=3.0.0) ; extra == 'all'
Requires-Dist: ipykernel ; extra == 'all'
Requires-Dist: ipython ; extra == 'all'
Requires-Dist: matplotlib (>=3.0) ; extra == 'all'
Requires-Dist: mplhep (>=0.2.16) ; extra == 'all'
Requires-Dist: nbsphinx ; extra == 'all'
Requires-Dist: pillow ; extra == 'all'
Requires-Dist: pytest (>=4.6) ; extra == 'all'
Requires-Dist: recommonmark (>=0.5.0) ; extra == 'all'
Requires-Dist: scipy (>=1.4) ; extra == 'all'
Requires-Dist: sphinx-copybutton ; extra == 'all'
Requires-Dist: sphinx-rtd-theme (>=0.5.0) ; extra == 'all'
Requires-Dist: uncertainties (>=3) ; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest (>=4.6) ; extra == 'dev'
Requires-Dist: matplotlib (>=3.0) ; extra == 'dev'
Requires-Dist: scipy (>=1.4) ; extra == 'dev'
Requires-Dist: uncertainties (>=3) ; extra == 'dev'
Requires-Dist: mplhep (>=0.2.16) ; extra == 'dev'
Requires-Dist: ipykernel ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: matplotlib (>=3.0) ; extra == 'docs'
Requires-Dist: scipy (>=1.4) ; extra == 'docs'
Requires-Dist: uncertainties (>=3) ; extra == 'docs'
Requires-Dist: mplhep (>=0.2.16) ; extra == 'docs'
Requires-Dist: nbsphinx ; extra == 'docs'
Requires-Dist: recommonmark (>=0.5.0) ; extra == 'docs'
Requires-Dist: Sphinx (>=3.0.0) ; extra == 'docs'
Requires-Dist: sphinx-copybutton ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme (>=0.5.0) ; extra == 'docs'
Requires-Dist: ipython ; extra == 'docs'
Requires-Dist: pillow ; extra == 'docs'
Provides-Extra: plot
Requires-Dist: matplotlib (>=3.0) ; extra == 'plot'
Requires-Dist: scipy (>=1.4) ; extra == 'plot'
Requires-Dist: uncertainties (>=3) ; extra == 'plot'
Requires-Dist: mplhep (>=0.2.16) ; extra == 'plot'
Provides-Extra: test
Requires-Dist: pytest (>=4.6) ; extra == 'test'

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

# Hist

[![Actions Status][actions-badge]][actions-link]
[![Documentation Status][rtd-badge]][rtd-link]
[![Code style: black][black-badge]][black-link]

[![PyPI version][pypi-version]][pypi-link]
[![Conda-Forge][conda-badge]][conda-link]
[![PyPI platforms][pypi-platforms]][pypi-link]
[![DOI](https://zenodo.org/badge/239605861.svg)](https://zenodo.org/badge/latestdoi/239605861)

[![GitHub Discussion][github-discussions-badge]][github-discussions-link]
[![Gitter][gitter-badge]][gitter-link]
[![Scikit-HEP][sk-badge]](https://scikit-hep.org/)

Hist is a analyst friendly front-end for
[boost-histogram](https://github.com/scikit-hep/boost-histogram), designed for
Python 3.6+.

## Installation

You can install this library from [PyPI](https://pypi.org/project/hist/) with pip:

```bash
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
  - Storages can be given by string
  - `storage=` can be omitted

- 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
  - `.plot2d_full()` shows 1D projects around a 2D plot
  - `.plot_pull(...)` performs a pull plot

- Notebook ready: Hist has gorgeous in-notebook representation.
  - No dependencies required

## Usage

```python
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:

```bash
python -m pip install -e .[dev]
```

See [CONTRIBUTING.md](./.github/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](https://allcontributors.org/docs/en/emoji-key)):
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tr>
    <td align="center"><a href="https://github.com/henryiii"><img src="https://avatars1.githubusercontent.com/u/4616906?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Henry Schreiner</b></sub></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"><a href="http://lovelybuggies.com.cn/"><img src="https://avatars3.githubusercontent.com/u/29083689?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nino Lau</b></sub></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"><a href="https://github.com/chrisburr"><img src="https://avatars3.githubusercontent.com/u/5220533?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Chris Burr</b></sub></a><br /><a href="https://github.com/scikit-hep/hist/commits?author=chrisburr" title="Code">💻</a></td>
    <td align="center"><a href="https://github.com/eduardo-rodrigues"><img src="https://avatars3.githubusercontent.com/u/5013581?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Eduardo Rodrigues</b></sub></a><br /><a href="https://github.com/scikit-hep/hist/commits?author=eduardo-rodrigues" title="Code">💻</a></td>
  </tr>
</table>
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->



This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.

## Talks

* [2020-07-07 SciPy Proceedings](https://www.youtube.com/watch?v=ERraTfHkPd0&list=PLYx7XA2nY5GfY4WWJjG5cQZDc7DIUmn6Z&index=4)
* [2020-07-17 PyHEP2020](https://indico.cern.ch/event/882824/contributions/3931299/)

---

## 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.


[actions-badge]:            https://github.com/scikit-hep/hist/workflows/CI/badge.svg
[actions-link]:             https://github.com/scikit-hep/hist/actions
[black-badge]:              https://img.shields.io/badge/code%20style-black-000000.svg
[black-link]:               https://github.com/psf/black
[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/hist
[conda-link]:               https://github.com/conda-forge/hist-feedstock
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
[github-discussions-link]:  https://github.com/scikit-hep/hist/discussions
[gitter-badge]:             https://badges.gitter.im/HSF/PyHEP-histogramming.svg
[gitter-link]:              https://gitter.im/HSF/PyHEP-histogramming?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
[pypi-link]:                https://pypi.org/project/hist/
[pypi-platforms]:           https://img.shields.io/pypi/pyversions/hist
[pypi-version]:             https://badge.fury.io/py/hist.svg
[rtd-badge]:                https://readthedocs.org/projects/hist/badge/?version=latest
[rtd-link]:                 https://hist.readthedocs.io/en/latest/?badge=latest
[sk-badge]:                 https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg


