LatticeFractile.h

Classes

LatticeFractile -- Static functions to get median and fractiles of a lattice (full description)

template<class T> class LatticeFractile

Interface

Public Members
static Vector<T> unmaskedFractile (const Lattice<T>& lattice, Float fraction, uInt smallSize = 512*512)
static Vector<T> maskedFractile (const MaskedLattice<T>& lattice, Float fraction, uInt smallSize = 512*512)
static Vector<T> unmaskedFractiles (const Lattice<T>& lattice, Float left, Float right, uInt smallSize = 512*512)
static Vector<T> maskedFractiles (const MaskedLattice<T>& lattice, Float left, Float right, uInt smallSize = 512*512)
Private Members
static Vector<T> smallMaskedFractile (const MaskedLattice<T>& lattice, Float fraction)
static Vector<T> smallMaskedFractiles (const MaskedLattice<T>& lattice, Float left, Float right)
static uInt maskedHistogram (T& stv, T& endv, T& minv, T& maxv, Block<uInt>& hist, const Block<T>& lattice)
static void unmaskedHistogram (T& stv, T& endv, T& minv, T& maxv, Block<uInt>& hist, const Block<T>& lattice)
static uInt findBin (uInt& fractileInx, T& stv, T& endv, T minv, T maxv, T step, const Block<uInt>& hist)

Description

Review Status

Date Reviewed:
yyyy/mm/dd
Programs:
Tests:

Prerequisite

Synopsis

This class contains a few static functions to find 1 or 2 fractiles in a lattice. They are primarily used by the LEL classes, but can also be used standalone.
A fractile is the same as a percentile be it that it is given as a fraction instead of a percentage. A fraction of 0.5 yields the median.
When the lattice has a mask, only the masked-on elements are taken into account. If all elements are masked_off, an empty Vector is returned indicating that no fractiles were found.

The algorithm used depends on the size of the lattice. Smallish lattices (i.e. not exceeding the argument smallSize) are handled in one pass im memory. For bigger lattices a multi-pass algorithm is used. First the lattices is binned. Thereafter the algorithm continues with the elements of the bins containing the fractiles. This continues until the number of elements left is less than smallSize. Typically only 2 passes are needed for a big image.
The algorithm is robust and takes possible rounding errors into account. It also takes into account that the lattice can contain many equal values.

Motivation

Separated from file LELFunction.h to make it more commonly usable and to make the source files more readable.

Member Description

static Vector<T> unmaskedFractile (const Lattice<T>& lattice, Float fraction, uInt smallSize = 512*512)
static Vector<T> maskedFractile (const MaskedLattice<T>& lattice, Float fraction, uInt smallSize = 512*512)

Determine the fractile of the given lattice. It returns the value of the lattice at the given fraction. A fraction of 0.5 returns the median. If the lattice has an even number of elements and if the lattice is small enough (< 100 elements), the median is the mean of the 2 middle elements.
If the lattice is masked, onlu masked-on elements are taken into account.
If the lattice is large, successive histograms are made until smallSize elements are left. Thereafter an in-memory algorithm will be used to finish. The number of passes made over the data is undetermined, but a typical number is 2 passes.
Normally a vector with 1 element is returned. If the lattice has no masked-on elements, an empty vector is returned.

static Vector<T> unmaskedFractiles (const Lattice<T>& lattice, Float left, Float right, uInt smallSize = 512*512)
static Vector<T> maskedFractiles (const MaskedLattice<T>& lattice, Float left, Float right, uInt smallSize = 512*512)

Determine the values of the 2 elements at the given fractiles. Thus left=0.25; right=0.75 gives the quartiles of the lattice.
If the lattice is masked, onlu masked-on elements are taken into account.
If the lattice is large, successive histograms are made until smallSize elements are left. Thereafter an in-memory algorithm will be used to finish. The number of passes made over the data is undetermined, but a typical number is 2 passes.
Normally a vector with 2 elements is returned. If the lattice has no masked-on elements, an empty vector is returned.

static Vector<T> smallMaskedFractile (const MaskedLattice<T>& lattice, Float fraction)

Determine the fractile for a small masked lattice.

static Vector<T> smallMaskedFractiles (const MaskedLattice<T>& lattice, Float left, Float right)

Determine the fractiles for a small masked lattice.

static uInt maskedHistogram (T& stv, T& endv, T& minv, T& maxv, Block<uInt>& hist, const Block<T>& lattice)
static void unmaskedHistogram (T& stv, T& endv, T& minv, T& maxv, Block<uInt>& hist, const Block<T>& lattice)

Calculate the first histogram (with 10000 bins). Also calculate the minimum and maximum. It returns the number of masked-on values. Masked-off values are ignored.

static uInt findBin (uInt& fractileInx, T& stv, T& endv, T minv, T maxv, T step, const Block<uInt>& hist)

Helper function which determines which bin in the histogram contains the passed index. On input fractileInx gives the index of the fractile in the entire histogram and stv,endv give the boundaries of the entire histogram. On output fractileInx is the index in the bin bounded by the values given in stv and endv. The nr of values in that bin is returned as the function value. On success it returns True, otherwise (rounding problem) False. In the latter case the fractile is known and equal to endv.