hist


Namehist JSON
Version 2.4.0 PyPI version JSON
download
home_pagehttps://github.com/scikit-hep/hist
SummaryHist classes and utilities
upload_time2021-07-07 05:22:38
maintainerThe Scikit-HEP admins
docs_urlNone
authorHenry Schreiner
requires_python>=3.6
licenseBSD-3-Clause
keywords histogram boost-histogram
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <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]
[![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 an analyst-friendly front-end for
[boost-histogram](https://github.com/scikit-hep/boost-histogram), designed for
Python 3.7+ (3.6 users get version 2.3). See [what's new](https://hist.readthedocs.io/en/latest/changelog.html).

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

```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](https://hist.readthedocs.io/en/latest/contributing.html) 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/aminnj"><img src="https://avatars.githubusercontent.com/u/5760027?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nick Amin</b></sub></a><br /><a href="https://github.com/scikit-hep/hist/commits?author=aminnj" title="Code">💻</a></td>
    <td align="center"><a href="http://cern.ch/eduardo.rodrigues"><img src="https://avatars.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>
    <td align="center"><a href="http://andrzejnovak.github.io/"><img src="https://avatars.githubusercontent.com/u/13226500?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Andrzej Novak</b></sub></a><br /><a href="https://github.com/scikit-hep/hist/commits?author=andrzejnovak" title="Code">💻</a></td>
    <td align="center"><a href="http://www.matthewfeickert.com/"><img src="https://avatars.githubusercontent.com/u/5142394?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Matthew Feickert</b></sub></a><br /><a href="https://github.com/scikit-hep/hist/commits?author=matthewfeickert" title="Code">💻</a></td>
  </tr>
  <tr>
    <td align="center"><a href="http://theoryandpractice.org"><img src="https://avatars.githubusercontent.com/u/4458890?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Kyle Cranmer</b></sub></a><br /><a href="https://github.com/scikit-hep/hist/commits?author=cranmer" title="Documentation">📖</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
[pre-commit-badge]:         https://results.pre-commit.ci/badge/github/scikit-hep/hist/main.svg
[pre-commit-link]:          https://results.pre-commit.ci/repo/github/scikit-hep/hist
[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



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/scikit-hep/hist",
    "name": "hist",
    "maintainer": "The Scikit-HEP admins",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "scikit-hep-admins@googlegroups.com",
    "keywords": "histogram,boost-histogram",
    "author": "Henry Schreiner",
    "author_email": "henry.schreiner@cern.ch",
    "download_url": "https://files.pythonhosted.org/packages/82/2d/9c85cb5ef15a98945a029054d44d91a43f067025cc7830322eeb03961144/hist-2.4.0.tar.gz",
    "platform": "Any",
    "description": "<img alt=\"histogram\" width=\"200\" src=\"https://raw.githubusercontent.com/scikit-hep/hist/main/docs/_images/histlogo.png\"/>\n\n# Hist\n\n[![Actions Status][actions-badge]][actions-link]\n[![Documentation Status][rtd-badge]][rtd-link]\n[![pre-commit.ci status][pre-commit-badge]][pre-commit-link]\n[![Code style: black][black-badge]][black-link]\n\n[![PyPI version][pypi-version]][pypi-link]\n[![Conda-Forge][conda-badge]][conda-link]\n[![PyPI platforms][pypi-platforms]][pypi-link]\n[![DOI](https://zenodo.org/badge/239605861.svg)](https://zenodo.org/badge/latestdoi/239605861)\n\n[![GitHub Discussion][github-discussions-badge]][github-discussions-link]\n[![Gitter][gitter-badge]][gitter-link]\n[![Scikit-HEP][sk-badge]](https://scikit-hep.org/)\n\nHist is an analyst-friendly front-end for\n[boost-histogram](https://github.com/scikit-hep/boost-histogram), designed for\nPython 3.7+ (3.6 users get version 2.3). See [what's new](https://hist.readthedocs.io/en/latest/changelog.html).\n\n## Installation\n\nYou can install this library from [PyPI](https://pypi.org/project/hist/) with pip:\n\n```bash\npython3 -m pip install \"hist[plot]\"\n```\n\nIf you do not need the plotting features, you can skip the `[plot]` extra.\n\n## Features\n\nHist currently provides everything boost-histogram provides, and the following enhancements:\n\n- Hist augments axes with names:\n  - `name=` is a unique label describing each axis\n  - `label=` is an optional string that is used in plotting (defaults to `name`\n    if not provided)\n  - Indexing, projection, and more support named axes\n  - Experimental `NamedHist` is a `Hist` that disables most forms of positional access\n\n- The `Hist` class augments `bh.Histogram` with reduced typing construction:\n  - Optional import-free construction system\n  - `flow=False` is a fast way to turn off flow for the axes on construction\n  - Storages can be given by string\n  - `storage=` can be omitted\n  - `data=` can initialize a histogram with existing data\n  - `Hist.from_columns` can be used to initialize with a DataFrame or dict\n\n- Hist implements UHI+; an extension to the UHI (Unified Histogram Indexing) system designed for import-free interactivity:\n  - Uses `j` suffix to switch to data coordinates in access or slices\n  - Uses `j` suffix on slices to rebin\n  - Strings can be used directly to index into string category axes\n\n- Quick plotting routines encourage exploration:\n  - `.plot()` provides 1D and 2D plots (or use `plot1d()`, `plot2d()`)\n  - `.plot2d_full()` shows 1D projects around a 2D plot\n  - `.plot_ratio(...)` make a ratio plot between the histogram and another histogram or callable\n  - `.plot_pull(...)` performs a pull plot\n  - `.plot_pie()` makes a pie plot\n  - `.show()` provides a nice str printout using Histoprint\n\n- Extended Histogram features:\n  - `.density()` computes the density as an array\n  - `.profile(remove_ax)` can convert a ND COUNT histogram into a (N-1)D MEAN histogram\n\n- New modules\n  - `intervals` supports frequentist coverage intervals\n\n- Notebook ready: Hist has gorgeous in-notebook representation.\n  - No dependencies required\n\n## Usage\n\n```python\nfrom hist import Hist\n\n# Quick construction, no other imports needed:\nh = (\n  Hist.new\n  .Reg(10, 0 ,1, name=\"x\", label=\"x-axis\")\n  .Var(range(10), name=\"y\", label=\"y-axis\")\n  .Int64()\n)\n\n# Filling by names is allowed:\nh.fill(y=[1, 4, 6], x=[3, 5, 2])\n\n# Names can be used to manipulate the histogram:\nh.project(\"x\")\nh[{\"y\": 0.5j + 3, \"x\": 5j}]\n\n# You can access data coordinates or rebin with a `j` suffix:\nh[.3j:, ::2j] # x from .3 to the end, y is rebinned by 2\n\n# Elegant plotting functions:\nh.plot()\nh.plot2d_full()\nh.plot_pull(Callable)\n```\n\n## Development\n\nFrom a git checkout, run:\n\n```bash\npython -m pip install -e .[dev]\n```\n\nSee [CONTRIBUTING.md](https://hist.readthedocs.io/en/latest/contributing.html) for information on setting up a development environment.\n\n## Contributors\n\nWe would like to acknowledge the contributors that made this project possible ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n<table>\n  <tr>\n    <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\">\ud83d\udea7</a> <a href=\"https://github.com/scikit-hep/hist/commits?author=henryiii\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/scikit-hep/hist/commits?author=henryiii\" title=\"Documentation\">\ud83d\udcd6</a></td>\n    <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\">\ud83d\udea7</a> <a href=\"https://github.com/scikit-hep/hist/commits?author=LovelyBuggies\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/scikit-hep/hist/commits?author=LovelyBuggies\" title=\"Documentation\">\ud83d\udcd6</a></td>\n    <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\">\ud83d\udcbb</a></td>\n    <td align=\"center\"><a href=\"https://github.com/aminnj\"><img src=\"https://avatars.githubusercontent.com/u/5760027?v=4?s=100\" width=\"100px;\" alt=\"\"/><br /><sub><b>Nick Amin</b></sub></a><br /><a href=\"https://github.com/scikit-hep/hist/commits?author=aminnj\" title=\"Code\">\ud83d\udcbb</a></td>\n    <td align=\"center\"><a href=\"http://cern.ch/eduardo.rodrigues\"><img src=\"https://avatars.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\">\ud83d\udcbb</a></td>\n    <td align=\"center\"><a href=\"http://andrzejnovak.github.io/\"><img src=\"https://avatars.githubusercontent.com/u/13226500?v=4?s=100\" width=\"100px;\" alt=\"\"/><br /><sub><b>Andrzej Novak</b></sub></a><br /><a href=\"https://github.com/scikit-hep/hist/commits?author=andrzejnovak\" title=\"Code\">\ud83d\udcbb</a></td>\n    <td align=\"center\"><a href=\"http://www.matthewfeickert.com/\"><img src=\"https://avatars.githubusercontent.com/u/5142394?v=4?s=100\" width=\"100px;\" alt=\"\"/><br /><sub><b>Matthew Feickert</b></sub></a><br /><a href=\"https://github.com/scikit-hep/hist/commits?author=matthewfeickert\" title=\"Code\">\ud83d\udcbb</a></td>\n  </tr>\n  <tr>\n    <td align=\"center\"><a href=\"http://theoryandpractice.org\"><img src=\"https://avatars.githubusercontent.com/u/4458890?v=4?s=100\" width=\"100px;\" alt=\"\"/><br /><sub><b>Kyle Cranmer</b></sub></a><br /><a href=\"https://github.com/scikit-hep/hist/commits?author=cranmer\" title=\"Documentation\">\ud83d\udcd6</a></td>\n  </tr>\n</table>\n\n<!-- markdownlint-restore -->\n<!-- prettier-ignore-end -->\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.\n\n## Talks\n\n- [2020-07-07 SciPy Proceedings](https://www.youtube.com/watch?v=ERraTfHkPd0&list=PLYx7XA2nY5GfY4WWJjG5cQZDc7DIUmn6Z&index=4)\n- [2020-07-17 PyHEP2020](https://indico.cern.ch/event/882824/contributions/3931299/)\n\n---\n\n## Acknowledgements\n\nThis library was primarily developed by Henry Schreiner and Nino Lau.\n\nSupport 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.\n\n[actions-badge]:            https://github.com/scikit-hep/hist/workflows/CI/badge.svg\n[actions-link]:             https://github.com/scikit-hep/hist/actions\n[black-badge]:              https://img.shields.io/badge/code%20style-black-000000.svg\n[black-link]:               https://github.com/psf/black\n[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/hist\n[conda-link]:               https://github.com/conda-forge/hist-feedstock\n[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github\n[github-discussions-link]:  https://github.com/scikit-hep/hist/discussions\n[gitter-badge]:             https://badges.gitter.im/HSF/PyHEP-histogramming.svg\n[gitter-link]:              https://gitter.im/HSF/PyHEP-histogramming?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge\n[pre-commit-badge]:         https://results.pre-commit.ci/badge/github/scikit-hep/hist/main.svg\n[pre-commit-link]:          https://results.pre-commit.ci/repo/github/scikit-hep/hist\n[pypi-link]:                https://pypi.org/project/hist/\n[pypi-platforms]:           https://img.shields.io/pypi/pyversions/hist\n[pypi-version]:             https://badge.fury.io/py/hist.svg\n[rtd-badge]:                https://readthedocs.org/projects/hist/badge/?version=latest\n[rtd-link]:                 https://hist.readthedocs.io/en/latest/?badge=latest\n[sk-badge]:                 https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg\n\n\n",
    "bugtrack_url": null,
    "license": "BSD-3-Clause",
    "summary": "Hist classes and utilities",
    "version": "2.4.0",
    "split_keywords": [
        "histogram",
        "boost-histogram"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "8fb059e8181e26ef132a5600e9117c05",
                "sha256": "159ec53918d3ed9d1c475ba2ffb442664380ebca9a45b4f9b0e1ab9a37d93029"
            },
            "downloads": -1,
            "filename": "hist-2.4.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8fb059e8181e26ef132a5600e9117c05",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 31911,
            "upload_time": "2021-07-07T05:22:36",
            "upload_time_iso_8601": "2021-07-07T05:22:36.533953Z",
            "url": "https://files.pythonhosted.org/packages/df/96/3de92baa7a09e3eb50a00728e370739f922b3cf2c194568398d56b726980/hist-2.4.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "6e321ce7a8dde1c085aa48f6b34ebbd1",
                "sha256": "a9692668ff0f5e9d381e99e7df501962e6b28dd77b5d3d309ef1b3de3cb634cd"
            },
            "downloads": -1,
            "filename": "hist-2.4.0.tar.gz",
            "has_sig": false,
            "md5_digest": "6e321ce7a8dde1c085aa48f6b34ebbd1",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 207294,
            "upload_time": "2021-07-07T05:22:38",
            "upload_time_iso_8601": "2021-07-07T05:22:38.179571Z",
            "url": "https://files.pythonhosted.org/packages/82/2d/9c85cb5ef15a98945a029054d44d91a43f067025cc7830322eeb03961144/hist-2.4.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-07-07 05:22:38",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "scikit-hep",
    "github_project": "hist",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "hist"
}
        
Elapsed time: 0.27156s