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

Holds probability density functions and other types of distribution

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

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 ConstSample: One unmutable sample of a distribution, see dip::Distribution::Sample for details. more...
template<typename T> class IteratorTemplate: An iterator for dip::Distribution. Dereferences into a Sample or a ConstSample (the value of T). more...
class Sample: One sample of a distribution. more...

Aliases

using ConstIterator = dip::Distribution::IteratorTemplate: An iterator for const dip::Distribution. Dereferences into a ConstSample.
using Container = std::vector<ValueType>: Container used internally to store the data
using Iterator = dip::Distribution::IteratorTemplate: An iterator for dip::Distribution. Dereferences into a Sample.
using ValueType = dip::dfloat: Data type of values stored in container

Functions

auto Back() -> dip::Distribution::Sample: Gets the x and y values at the end
auto Back() const -> dip::Distribution::ConstSample: 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::ConstIterator noexcept: Returns an iterator to the beginning
auto Columns() const -> dip::uint: Returns the number of columns in the matrix of y 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 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 Empty() const -> bool noexcept: Checks whether the distribution is empty (size is 0)
auto end() -> dip::Distribution::Iterator noexcept: Returns an iterator to the end
auto end() const -> dip::Distribution::ConstIterator noexcept: Returns an iterator to the end
auto Integral(dip::uint index = 0) const -> dip::dfloat: Computes the integral of the distribution. Make sure the data are sorted (see Sort).
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 MaximumLikelihood() -> dip::Distribution::Container: Computes the most likely x values. In essence, returns the x values which maximize the corresponding y value.
auto NormalizeIntegral() -> dip::Distribution&: Normalizes the integral of the distribution values. Make sure the data are sorted (see Sort).
auto NormalizeSum() -> dip::Distribution&: Normalizes the sum of the y values.
auto Rows() const -> dip::uint: Returns the number of rows in the matrix of y values
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 to the units of the isotropic pixelSize, or otherwise to “px”.
auto Size() const -> dip::uint noexcept: Returns the size of the distribution (number of data points)
auto Sort() -> dip::Distribution&: Sorts the data in the distribution according to the x values.
auto Sum(dip::uint index = 0) const -> dip::dfloat: Computes the sum of the y values.
auto ValuesPerSample() const -> dip::uint: Returns the number of y values per sample
auto X() const -> std::vector<dfloat>: Copies the x values to a new array
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 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 Y(dip::uint index = 0) const -> std::vector<dfloat>: Copies the y values to a new array
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

Operators

auto operator*=(dip::dfloat scale) -> dip::Distribution&: Scales the distribution, multiplying each y value by scale.
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, dividing each y value by scale.
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::ConstSample: Gets the x and y values at location index

Alias documentation

using ValueType = dip::dfloat

Data type of values stored in container

using Container = std::vector<ValueType>

Container used internally to store the data

using Iterator = dip::Distribution::IteratorTemplate

An iterator for dip::Distribution. Dereferences into a Sample.

using ConstIterator = dip::Distribution::IteratorTemplate

An iterator for const dip::Distribution. Dereferences into a ConstSample.

Function documentation

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

bool Empty( ) const noexcept

Checks whether the distribution is empty (size is 0)

dip::uint Size( ) const noexcept

Returns the size of the distribution (number of data points)

dip::uint ValuesPerSample( ) const

Returns the number of y values per sample

dip::uint Rows( ) const

Returns the number of rows in the matrix of y values

dip::uint Columns( ) const

Returns the number of columns in the matrix of y values

dip::Units const& XUnits( ) const

Returns the units used along the x axis.

dip::Units& XUnits( )

Returns a modifiable reference to the units used along the x axis.

dip::Distribution::Sample Back( )

Gets the x and y values at the end

dip::Distribution::ConstSample Back( ) const

Gets the x and y values at the end

dip::Distribution::Iterator begin( ) noexcept

Returns an iterator to the beginning

dip::Distribution::ConstIterator begin( ) const noexcept

Returns an iterator to the beginning

dip::Distribution::Iterator end( ) noexcept

Returns an iterator to the end

dip::Distribution::ConstIterator end( ) const noexcept

Returns an iterator to the end

dip::SampleIterator Xbegin( ) noexcept

Returns an x-value iterator to the beginning

dip::ConstSampleIterator Xbegin( ) const noexcept

Returns an x-value iterator to the beginning

dip::SampleIterator Xend( ) noexcept

Returns an x-value iterator to the end

dip::ConstSampleIterator Xend( ) const noexcept

Returns an x-value iterator to the end

dip::SampleIterator Ybegin( dip::uint index = 0)

Returns an y-value iterator to the beginning

dip::ConstSampleIterator Ybegin( dip::uint index = 0) const

Returns an y-value iterator to the beginning

dip::SampleIterator Yend( dip::uint index = 0)

Returns an y-value iterator to the end

dip::ConstSampleIterator Yend( dip::uint index = 0) const

Returns an y-value iterator to the end

std::vector<dfloat> X( ) const

Copies the x values to a new array

std::vector<dfloat> Y( dip::uint index = 0) const

Copies the y values to a new array

dip::Distribution& Sort( )

Sorts the data in the distribution according to the x values.

dip::Distribution& Cumulative( )

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).

dip::dfloat Sum( dip::uint index = 0) const

Computes the sum of the y values.

dip::Distribution& NormalizeSum( )

Normalizes the sum of the y values.

dip::Distribution& Integrate( )

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).

dip::dfloat Integral( dip::uint index = 0) const

Computes the integral of the distribution. Make sure the data are sorted (see Sort).

dip::Distribution& NormalizeIntegral( )

Normalizes the integral of the distribution values. Make sure the data are sorted (see Sort).

dip::Distribution& Differentiate( )

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).

dip::Distribution::Container 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[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 to the units of the isotropic pixelSize, or otherwise to “px”.

dip::Distribution::Sample operator[]( dip::uint index)

Gets the x and y values at location index

dip::Distribution::ConstSample operator[]( dip::uint index) const