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

Holds 1D 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, distance or intensity.

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 N×M, where M is 1 for a vector-like set of values.

Indexing into the object yields a dip::Distribution::Sample, which references the data in the distribution and can be used to modify it. For example, one can do

dip::Distribution distribution(10);
distribution[0].X() = 1;
distribution[0].Y() += 0.25;

However, the dip::Distribution::X and dip::Distribution::Y functions of the dip::Distribution object itself always return copies of the data, and will not allow modification of the object. One can also use iterators to access all samples in turn.

Elements can be modified in such a way that x is no longer sorted. This could cause some functions such as dip::Distribution::Integrate to produce wrong results. 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 immutable 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. The x values must be 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. The x values must be 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. The x values must be 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. The x values must be 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. more...
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. The x values must be sorted (see Sort).

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

Computes the integral of the distribution. The x values must be sorted (see Sort).

dip::Distribution& NormalizeIntegral( )

Normalizes the integral of the distribution values. The x values must be 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. The x values must be 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.

If the pixelSize is isotropic and has physical units, the first x value will be pixelSize[0].magnitude * offset, and subsequent values will have linear increments of pixelSize[0].magnitude * scaling. Otherwise, pixelSize is ignored.

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