histogram.rst

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:

#include <xtensor/xtensor.hpp>
#include <xtensor/xhistogram.hpp>
#include <xtensor/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:

#include <xtensor/xtensor.hpp>
#include <xtensor/xhistogram.hpp>
#include <xtensor/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).