.. meta::
   :description: boost-histogram is a Python package for fast, multi-dimensional
      histograms, with Python bindings for the Boost.Histogram C++ library.

.. image:: _images/BoostHistogramPythonLogo.png
  :width: 70%
  :alt: Boost histogram logo
  :align: center

Welcome to boost-histogram's documentation!
===========================================

|Actions Status| |Documentation Status| |PyPI version| |Conda-Forge|
|PyPI platforms| |DOI| |GitHub Discussion| |Scikit-HEP|

Boost-histogram (`source <https://github.com/scikit-hep/boost-histogram>`__) is
a Python package providing Python bindings for Boost.Histogram_ (`source
<https://github.com/boostorg/histogram>`__).  You can install this library from
`PyPI <https://pypi.org/project/boost-histogram/>`__ with pip or you can use
Conda via `conda-forge <https://github.com/conda-forge/boost-histogram-feedstock>`__:

.. code-block:: bash

   python -m pip install boost-histogram

.. code-block:: bash

   conda install -c conda-forge boost-histogram

All the normal best-practices for Python apply; you should be in a
virtual environment, etc. See :ref:`usage-installation` for more details. An example of usage:

.. code-block:: python3

   import boost_histogram as bh

   # Compose axis however you like; this is a 2D histogram
   hist = bh.Histogram(bh.axis.Regular(2, 0, 1), bh.axis.Regular(4, 0.0, 1.0))

   # Filling can be done with arrays, one per dimension
   hist.fill([0.3, 0.5, 0.2], [0.1, 0.4, 0.9])

   # NumPy array view into histogram counts, no overflow bins
   counts = hist.view()

See :ref:`usage-quickstart` for more.


.. toctree::
   :maxdepth: 1
   :caption: User Guide:

   user-guide/installation
   user-guide/quickstart
   user-guide/histogram
   user-guide/axes
   user-guide/storage
   user-guide/accumulators
   user-guide/transforms
   user-guide/indexing
   user-guide/plotting
   user-guide/analyses
   user-guide/numpy
   user-guide/subclassing
   user-guide/comparison


.. toctree::
  :maxdepth: 1
  :caption: Examples:

  notebooks/SimpleExample
  notebooks/MultiCellExample
  notebooks/ThreadedFills
  notebooks/PerformanceComparison
  notebooks/xarray
  notebooks/BoostHistogramHandsOn

.. toctree::
   :maxdepth: 2
   :titlesonly:
   :caption: Developers
   :glob:

   contributing
   support
   changelog

.. toctree::
  :caption: API Reference:

  api/modules

Acknowledgements
----------------

This library was primarily developed by Henry Schreiner and Hans
Dembinski.

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.

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. _Boost.Histogram: https://www.boost.org/doc/libs/release/libs/histogram/doc/html/index.html
.. |Actions Status| image:: https://github.com/scikit-hep/boost-histogram/workflows/Tests/badge.svg
   :target: https://github.com/scikit-hep/boost-histogram/actions
.. |Documentation Status| image:: https://readthedocs.org/projects/boost-histogram/badge/?version=latest
   :target: https://boost-histogram.readthedocs.io/en/latest/?badge=latest
.. |PyPI version| image:: https://badge.fury.io/py/boost-histogram.svg
   :target: https://pypi.org/project/boost-histogram
.. |Conda-Forge| image:: https://img.shields.io/conda/vn/conda-forge/boost-histogram
   :target: https://github.com/conda-forge/boost-histogram-feedstock
.. |PyPI platforms| image:: https://img.shields.io/pypi/pyversions/boost-histogram
   :target: https://pypi.org/project/boost-histogram/
.. |DOI| image:: https://zenodo.org/badge/148885351.svg
   :target: https://zenodo.org/badge/latestdoi/148885351
.. |GitHub Discussion| image:: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
   :target: https://github.com/scikit-hep/boost-histogram/discussions
.. |Scikit-HEP| image:: https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg
   :target: https://scikit-hep.org/
