dip::Distribution class

Holds probability density functions and other types of distribution

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

Distribution(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
Distribution(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
Distribution(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
Distribution(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() -> dip::Distribution::Sample
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() -> SampleIterator<dip::dfloat> noexcept
Returns an x-value iterator to the beginning
auto Xbegin() const -> ConstSampleIterator<dip::dfloat> noexcept
Returns an x-value iterator to the beginning
auto Xend() -> SampleIterator<dip::dfloat> noexcept
Returns an x-value iterator to the end
auto Xend() const -> ConstSampleIterator<dip::dfloat> noexcept
Returns an x-value iterator to the end
auto Ybegin(dip::uint index = 0) -> SampleIterator<dip::dfloat>
Returns an y-value iterator to the beginning
auto Ybegin(dip::uint index = 0) const -> ConstSampleIterator<dip::dfloat>
Returns an y-value iterator to the beginning
auto Yend(dip::uint index = 0) -> SampleIterator<dip::dfloat>
Returns an y-value iterator to the end
auto Yend(dip::uint index = 0) const -> ConstSampleIterator<dip::dfloat>
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() -> dip::Distribution::Container
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[0].magnitude * offset, and linear increments of pixelSize[0].magnitude * scaling, if the pixelSize is isotropic and has physical units. The XUnits are also set.

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.