# Analysis module#include "diplib/distribution.h" dip::Distribution class

Holds probability density functions and other types of distribution

### Contents

• Reference

This is a container class to hold results of certain type of analysis that compute a property as a function of scale or intensity. Even though a histogram could fit within this description, the `dip::Histogram` class is specifically meant to hold histograms, and purposefully kept separate from this class. A `dip::Histogram` with a 1D histogram can be cast to a `dip::Distribution`.

Distributions represent a function y of x, where x is not necessarily uniformly spaced. Both x and y are stored as double-precision floating point values. The distribution can also be a multi-valued function, with multiple y values for every x value. In this case, the y values for each x are arranged as a 2D matrix NxM, where M is 1 for a vector-like set of values.

Elements can be modified in such a way that x is no longer sorted. The `Sort` method applies a stable sort to restore the order.

## Constructors, destructors, assignment and conversion operators

dip::uint size = 0, dip::uint rows = 1, dip::uint columns = 1) explicit
A zero-initialized distribution can be created by giving a size, and number of values (or rows and columns) per sample
std::vector<dfloat> const& x, dip::uint rows = 1, dip::uint columns = 1) explicit
A zero-initialized distribution can be created by giving an array of the x values, and number of values (or rows and columns) per sample
std::vector<dfloat> const& x, std::vector<dfloat> const& y)
A distribution can be created by giving an array of the x values and an array of the y values
dip::Histogram const& histogram)
A 1D `dip::Histogram` can be cast to a `dip::Distribution`

## Classes

class Sample
One sample of a distribution.
class Iterator
An iterator for `dip::Distribution`. Dereferences into a `Sample`.

## Aliases

using ValueType = dip::dfloat
Data type of values stored in container
using Container = std::vector<ValueType>
Container used internally to store the data

## Functions

auto Empty() const -> bool noexcept
Checks whether the distribution is empty (size is 0)
auto Size() const -> dip::uint noexcept
Returns the size of the distribution (number of data points)
auto ValuesPerSample() const -> dip::uint
Returns the number of y values per sample
auto Rows() const -> dip::uint
Returns the number of rows in the matrix of y values
auto Columns() const -> dip::uint
Returns the number of columns in the matrix of y values
auto XUnits() const -> dip::Units const&
Returns the units used along the x axis.
auto XUnits() -> dip::Units&
Returns a modifiable reference to the units used along the x axis.
auto Back(
Gets the x and y values at the end
auto Back() const -> dip::Distribution::Sample const
Gets the x and y values at the end
auto begin() -> dip::Distribution::Iterator noexcept
Returns an iterator to the beginning
auto begin() const -> dip::Distribution::Iterator noexcept
Returns an iterator to the beginning
auto end() -> dip::Distribution::Iterator noexcept
Returns an iterator to the end
auto end() const -> dip::Distribution::Iterator noexcept
Returns an iterator to the end
auto Xbegin() -> dip::SampleIterator noexcept
Returns an x-value iterator to the beginning
auto Xbegin() const -> dip::ConstSampleIterator noexcept
Returns an x-value iterator to the beginning
auto Xend() -> dip::SampleIterator noexcept
Returns an x-value iterator to the end
auto Xend() const -> dip::ConstSampleIterator noexcept
Returns an x-value iterator to the end
auto Ybegin(dip::uint index = 0) -> dip::SampleIterator
Returns an y-value iterator to the beginning
auto Ybegin(dip::uint index = 0) const -> dip::ConstSampleIterator
Returns an y-value iterator to the beginning
auto Yend(dip::uint index = 0) -> dip::SampleIterator
Returns an y-value iterator to the end
auto Yend(dip::uint index = 0) const -> dip::ConstSampleIterator
Returns an y-value iterator to the end
auto X() const -> std::vector<dfloat>
Copies the x values to a new array
auto Y(dip::uint index = 0) const -> std::vector<dfloat>
Copies the y values to a new array
auto Sort() -> dip::Distribution&
Sorts the data in the distribution according to the x values.
auto Cumulative() -> dip::Distribution&
Converts the distribution to a cumulative distribution, where each element is the sum of all elements up to that element in the original distribution (i.e. x spacing is ignored).
auto Sum(dip::uint index = 0) const -> dip::dfloat
Computes the sum of the y values.
auto NormalizeSum() -> dip::Distribution&
Normalizes the sum of the y values.
auto Integrate() -> dip::Distribution&
Converts the distribution to a cumulative distribution, where each element is the integral of the original distribution up to that element. Make sure the data are sorted (see `Sort`).
auto Integral(dip::uint index = 0) const -> dip::dfloat
Computes the integral of the distribution. Make sure the data are sorted (see `Sort`).
auto NormalizeIntegral() -> dip::Distribution&
Normalizes the integral of the distribution values. Make sure the data are sorted (see `Sort`).
auto Differentiate() -> dip::Distribution&
Converts the cumulative distribution to a distribution, where each element is the derivative of the original distribution at that element. Make sure the data are sorted (see `Sort`).
auto MaximumLikelihood(
Computes the most likely x values. In essence, returns the x values which maximize the corresponding y value.
void SetSampling(dip::PixelSize const& pixelSize = {}, dip::dfloat offset = 0.0, dip::dfloat scaling = 1.0)
Fills the values for the x axis, starting with `pixelSize.magnitude * offset`, and linear increments of `pixelSize.magnitude * scaling`, if the `pixelSize` is isotropic and has physical units. The `XUnits` are also set to the units of the isotropic `pixelSize`, or otherwise to “px”.

## Operators

auto operator[](dip::uint index) -> dip::Distribution::Sample
Gets the x and y values at location `index`
auto operator[](dip::uint index) const -> dip::Distribution::Sample const
Gets the x and y values at location `index`
auto operator+=(dip::Distribution const& other) -> dip::Distribution&
Adds two distributions. Their x values must match exactly.
auto operator*=(dip::dfloat scale) -> dip::Distribution&
Scales the distribution, multiplying each y value by `scale`.
auto operator/=(dip::dfloat scale) -> dip::Distribution&
Scales the distribution, dividing each y value by `scale`.

## Function documentation

### std::ostream& dip::operator<<(std::ostream& os, dip::Histogram const& histogram)#include "diplib/histogram.h"

You can output a `dip::Histogram` to `std::cout` or any other stream. Some information about the histogram is printed.