.. Copyright (c) 2016, Johan Mabille, Sylvain Corlay and Wolf Vollprecht

   Distributed under the terms of the BSD 3-Clause License.

   The full license is in the file LICENSE, distributed with this software.

.. _histogram:

Histogram
=========

Basic usage
-----------

* :cpp:func:`xt::histogram(a, bins[, weights][, density]) <xt::histogram>`
* :cpp:func:`xt::histogram_bin_edges(a[, weights][, left, right][, bins][, mode]) <xt::histogram_bin_edges>`

.. note::
    Any of the options ``[...]`` can be omitted (though the order must be preserved). The defaults are:

    *   ``weights`` = :cpp:func:`xt::ones(data.shape()) <xt::ones>`
    *   ``density`` = ``false``
    *   ``left`` = :cpp:func:`xt::amin(data)(0) <xt::amin>`
    *   ``right`` = :cpp:func:`Xt::amax(data)(0) <xt::amax>`
    *   ``bins`` = ``10``
    *   ``mode`` = :cpp:enumerator:`xt::histogram::automatic`

The behavior, in-, and output of :cpp:func:`xt::histogram` is similar to that of :any:`numpy.histogram`
with that difference that the bin-edges are obtained by a separate function call:

.. code-block:: cpp

    #include <xtensor/containers/xtensor.hpp>
    #include <xtensor/misc/xhistogram.hpp>
    #include <xtensor/io/xio.hpp>

    int main()
    {
        xt::xtensor<double,1> data = {1., 1., 2., 2., 3.};

        xt::xtensor<double,1> count = xt::histogram(data, std::size_t(2));

        xt::xtensor<double,1> bin_edges = xt::histogram_bin_edges(data, std::size_t(2));

        return 0;
    }

Bin-edges algorithm
-------------------

To customize the algorithm to be used to construct the histogram, one needs to make use of the latter
:cpp:func:`xt::histogram_bin_edges`. For example:

.. code-block:: cpp

    #include <xtensor/containers/xtensor.hpp>
    #include <xtensor/misc/xhistogram.hpp>
    #include <xtensor/io/xio.hpp>

    int main()
    {
        xt::xtensor<double,1> data = {1., 1., 2., 2., 3.};

        xt::xtensor<double,1> bin_edges = xt::histogram_bin_edges(data, std::size_t(2), xt::histogram_algorithm::uniform);

        xt::xtensor<double,1> prob = xt::histogram(data, bin_edges, true);

        std::cout << bin_edges << std::endl;
        std::cout << prob << std::endl;

        return 0;
    }

The following :cpp:enum:`xt::histogram_algorithm` are available:

* :cpp:enumerator:`~xt::histogram_algorithm::automatic`: equivalent to :cpp:enumerator:`~xt::histogram_algorithm::linspace`.
* :cpp:enumerator:`~xt::histogram_algorithm::linspace`: linearly spaced bin-edges.
* :cpp:enumerator:`~xt::histogram_algorithm::logspace`: bins that logarithmically increase in size.
* :cpp:enumerator:`~xt::histogram_algorithm::uniform`: bin-edges such that the number of data points is
  the same in all bins (as much as possible).