# Histogram class

Computes and holds histograms.

### Contents

A histogram is computed by the constructor. A default-constructed `Histogram`

is empty and can
only be assigned to.

A histogram can have multiple dimensions. In general, a scalar image will yield a classical one-dimensional histogram, and a tensor image will yield a multi-dimensional histogram, with one dimension per tensor element. The first tensor element determines the index along the first dimension, the second tensor element that along the second dimension, etc.

To facilitate usage for one-dimensional histograms, all getter functions that return a value for a given dimension, default to dimension 0, so can be called without arguments.

## Constructors, destructors, assignment and conversion operators

- Histogram(dip::Image const& input, dip::Image const& mask = {}, dip::Histogram::ConfigurationArray configuration = {}) explicit
- The constructor takes an image, an optional mask, and configuration options for each histogram dimension.
- Histogram(dip::Image const& input, dip::Image const& mask, dip::Histogram::Configuration configuration)
- This version of the constructor is identical to the previous one, but with a single configuration parameter instead of an array.
- Histogram(dip::Image const& input1, dip::Image const& input2, dip::Image const& mask, dip::Histogram::ConfigurationArray configuration = {})
- A version of the constructor that takes two scalar input images, and constructs their joint histogram (a 2D histogram, equal to the one obtained if the two images were the two channels of a tensor image).
- Histogram(dip::Measurement::IteratorFeature const& featureValues, dip::Histogram::ConfigurationArray configuration = {}) explicit
- The constructor takes an
`IteratorFeature`

of a`dip::Measurement`

object, and configuration options for each histogram dimension. - Histogram(dip::Histogram::ConfigurationArray configuration) explicit
- An empty histogram with the given configuration. Histogram bins are initialized to 0.
- Histogram(dip::Histogram::Configuration const& configuration) explicit
- An empty histogram with the given configuration. Histogram bins are initialized to 0.
- Histogram(dip::Histogram::CountType const* data, dip::Histogram::Configuration const& configuration)
- Create a 1D histogram around existing data. No ownership is transferred.
- Histogram() defaulted
- The default-initialized histogram is empty and can only be assigned to.

## Classes

- struct Configuration
- Configuration information for how the histogram is computed.

## Aliases

- using CountType = dip::uint64
- Type of histogram bins. See
`dip::DT_COUNT`

. - using ConfigurationArray = dip::DimensionArray
- An array of
`dip::Histogram::Configuration`

objects, one per histogram dimension.

## Functions

- static auto OptimalConfiguration() -> dip::Histogram::Configuration
- Creates a
`dip::Histogram::Configuration`

that uses the optimal bin size according to the Freedman–Diaconis rule. - static auto OptimalConfigurationWithFullRange() -> dip::Histogram::Configuration
- Like
`dip::Histogram::OptimalConfiguration`

, but includes the full data range (min to max); note that this can potentially lead to extremely large histograms. - void swap(dip::Histogram& other) noexcept
- Swaps
`this`

and`other`

. - auto IsInitialized() const -> bool
- Returns false for a default-initialized histogram.
- auto Copy() const -> dip::Histogram
- Deep copy, returns a copy of
`this`

with its own data segment. - void ReverseLookup(dip::Image const& input, dip::Image& out, dip::BooleanArray excludeOutOfBoundValues = {false})
- Performs a reverse histogram lookup, yielding an image “painted” with the bin values.
- auto Dimensionality() const -> dip::uint
- Returns the histogram dimensionality.
- auto Bins(dip::uint dim = 0) const -> dip::uint
- Returns the number of bins along dimension
`dim`

- auto BinSize(dip::uint dim = 0) const -> dip::dfloat
- Returns the size of the bins along dimension
`dim`

- auto LowerBound(dip::uint dim = 0) const -> dip::dfloat
- Returns the lower bound of the histogram for dimension
`dim`

- auto UpperBound(dip::uint dim = 0) const -> dip::dfloat
- Returns the upper bound of the histogram for dimension
`dim`

- auto BinBoundaries(dip::uint dim = 0) const -> dip::FloatArray
- Returns the bin boundaries along dimension
`dim`

(`Bins(dim)+1`

values). - auto BinCenters(dip::uint dim = 0) const -> dip::FloatArray
- Returns the bin centers along dimension
`dim`

- auto BinCenter(dip::uint bin, dip::uint dim = 0) const -> dip::dfloat
- Returns the bin center for the given
`bin`

along dimension`dim`

- auto Bin(dip::dfloat value) const -> dip::uint
- Gets the bin for
`value`

in a 1D histogram - auto Bin(dip::dfloat x_value, dip::dfloat y_value) const -> dip::UnsignedArray
- Gets the bin for {
`x_value`

,`y_value`

} in a 2D histogram - auto Bin(dip::dfloat x_value, dip::dfloat y_value, dip::dfloat z_value) const -> dip::UnsignedArray
- Gets the bin for {
`x_value`

,`y_value`

,`z_value`

} in a 3D histogram - auto Bin(dip::FloatArray const& value) const -> dip::UnsignedArray
- Gets the bin for
`value`

in an nD histogram - auto At(dip::uint x) const -> dip::Histogram::CountType
- Get the value at the given bin in a 1D histogram
- auto At(dip::uint x, dip::uint y) const -> dip::Histogram::CountType
- Get the value at the given bin in a 2D histogram
- auto At(dip::uint x, dip::uint y, dip::uint z) const -> dip::Histogram::CountType
- Get the value at the given bin in a 3D histogram
- auto At(dip::UnsignedArray const& bin) const -> dip::Histogram::CountType
- Get the value at the given bin
- auto GetImage() const -> dip::Image const&
- Get the image that holds the bin counts. The image is always scalar and of type
`dip::DT_COUNT`

. - auto begin() const -> dip::ConstImageIterator
- Returns an iterator to the first bin
- static auto end() -> dip::ConstImageIterator
- Returns an end iterator
- auto Origin() const -> dip::Histogram::CountType const*
- Returns a pointer to the first bin
- auto Count() const -> dip::uint
- Returns the total number of elements in the histogram (sum of bins)
- auto Cumulative() -> dip::Histogram&
- Converts the histogram to a cumulative histogram. For each bin, it will contain the sum of that bin with all the previous ones.
- auto GetMarginal(dip::uint dim) const -> dip::Histogram
- Returns the marginal histogram for dimension
`dim`

. - auto Smooth(dip::FloatArray sigma) -> dip::Histogram&
- Smooths the histogram, using Gaussian smoothing with parameters
`sigma`

.

## Operators

- auto operator+=(dip::Histogram const& other) -> dip::Histogram&
- Adds a histogram to *this.
`other`

must have identical properties. - auto operator-=(dip::Histogram const& other) -> dip::Histogram&
- Subtracts a histogram from *this, using saturated subtraction.
`other`

must have identical properties.

## Function documentation

### Histogram(dip::Image const& input, dip::Image const& mask = {}, dip::Histogram::ConfigurationArray configuration = {}) explicit

The constructor takes an image, an optional mask, and configuration options for each histogram dimension.

`configuration`

should have as many elements as tensor elements in `input`

. If `configuration`

has only
one element, it will be used for all histogram dimensions. If it is an empty array, appropriate configuration
values for `input`

are chosen based on its data type (see `dip::Histogram::Configuration::Configuration`

).

### Histogram(dip::Measurement::IteratorFeature const& featureValues, dip::Histogram::ConfigurationArray configuration = {}) explicit

The constructor takes an `IteratorFeature`

of a `dip::Measurement`

object, and configuration
options for each histogram dimension.

`configuration`

should have as many elements as values in `featureValues`

. If `configuration`

has only
one element, it will be used for all histogram dimensions. In the default configuration, the histogram
will stretch from lowest to highest value, in 100 bins.

### Histogram(dip::Histogram::ConfigurationArray configuration) explicit

An empty histogram with the given configuration. Histogram bins are initialized to 0.

The array must not be empty. The histogram will have `configuration->size()`

dimensions.
`configuration[ii].lowerIsPercentile`

and `configuration[ii].upperIsPercentile`

must all be false (since
there is no way of determining these percentiles).

The `GetImage`

method returns a const reference to the histogram bins (in the form of an image),
but it is possible to modify the values in the bins (modify the pixel values of this image).

### Histogram(dip::Histogram::Configuration const& configuration) explicit

An empty histogram with the given configuration. Histogram bins are initialized to 0.

The histogram will have one dimension.
`configuration.lowerIsPercentile`

and `configuration.upperIsPercentile`

must both be false (since
there is no way of determining these percentiles).

The `GetImage`

method returns a const reference to the histogram bins (in the form of an image),
but it is possible to modify the values in the bins (modify the pixel values of this image).

### Histogram(dip::Histogram::CountType const* data, dip::Histogram::Configuration const& configuration)

Create a 1D histogram around existing data. No ownership is transferred.

`data`

is a raw pointer to the data that will be encapsulated by the output histogram. Data must
be contiguous and of type `dip::Histogram::CountType`

. `configuration`

determines how many
bins are pointed to by `data`

.

Even though the data pointer is declared `const`

here, it is possible to obtain a non-const
pointer to the data later.

### static dip::Histogram::Configuration OptimalConfiguration()

Creates a `dip::Histogram::Configuration`

that uses the optimal bin size according to the Freedman–Diaconis rule.

The Freedman–Diaconis rule sets the bin size to , where IQR is the interquartile range (the distance from the lower to the upper quartile), and is the number of samples over which the histogram will be computed.

The histogram limits are chosen to avoid extremely large histograms, by ignoring values 50 IQRs below the lower quartile or above the upper quartile.

### dip::Histogram Copy() const

Deep copy, returns a copy of `this`

with its own data segment.

When making a copy of a histogram, the data segment is shared:

Histogram second = first; second.Smooth(); // modifies `first` also!

In contrast, this function returns a deep copy of `this`

, with its own data segment:

Histogram second = first.Copy(); second.Smooth(); // OK

### void ReverseLookup(dip::Image const& input, dip::Image& out, dip::BooleanArray excludeOutOfBoundValues = {false})

Performs a reverse histogram lookup, yielding an image “painted” with the bin values.

The bin corresponding to each pixel in the input image is found in the histogram, and this bin’s
value is written to `output`

.

`input`

must be similar to the image used to generate the histogram (at least have the same number
of tensor elements, which corresponds to the dimensionality of the histogram). The lookup occurs
in the same way as when generating the histogram. The `excludeOutOfBoundValues`

parameter for each
dimension indicates if an edge bin is found or no bin is found (yielding a 0 output) if the pixel
is not represented in the histogram.

`output`

is a scalar image with data type `dip::Histogram::CountType`

, containing the histogram
bin values.

This function is particularly interesting when applied to a histogram resulting from clustering
algorithms such as `dip::KMeansClustering`

or
`dip::MinimumVariancePartitioning`

.

### dip::Histogram& Cumulative()

Converts the histogram to a cumulative histogram. For each bin, it will contain the sum of that bin with all the previous ones.

The cumulative histogram has `this->Count()`

as the right-most bin. The `Count`

method applied to the
cumulative histogram is meaningless, as are `Mean`

and the other statistics functions.

For a multi-dimensional histogram, the cumulative histogram has `bin(i,j,k)`

equal to the sum of all bins
with indices equal or smaller to `i`

, `j`

and `k`

: `bin(1..i,1..j,1..k)`

. It is computed through the
`dip::CumulativeSum`

function.

### dip::Histogram GetMarginal(dip::uint dim) const

Returns the marginal histogram for dimension `dim`

.

The marginal histogram represents the marginal intensity distribution. It is a 1D histogram determined
by summing over all dimensions except `dim`

, and is equivalent to the histogram for tensor element
`dim`

.

### dip::Histogram& Smooth(dip::FloatArray sigma)

Smooths the histogram, using Gaussian smoothing with parameters `sigma`

.

Set a single sigma value, or one value per histogram dimension. The value is in bins, yielding a Gaussian
kernel of size `2 * std::ceil( 3 * sigma ) + 1`

bins. See `dip::GaussFIR`

for information on the smoothing
operation applied. `sigma`

defaults to 1.

The histogram is extended by `std::ceil( 3 * sigma )`

below and above the original bounds, to prevent the
histogram count to change.

### dip::Histogram& operator+=(dip::Histogram const& other)

Adds a histogram to *this. `other`

must have identical properties.

Adding multiple histograms together can be useful, for example, when accumulating pixel values from multiple images, or in multiple threads.