Static functions to get median and fractiles of a lattice. More...

#include <LatticeFractile.h>

Static Public Member Functions
static Vector< T >	unmaskedFractile (const Lattice< T > &lattice, Float fraction, uInt smallSize=4096 *4096)
	Determine the fractile of the given lattice. More...

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

static Vector< T >	unmaskedFractiles (const Lattice< T > &lattice, Float left, Float right, uInt smallSize=4096 *4096)
	Determine the values of the 2 elements at the given fractiles. More...

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

Static Private Member Functions
static Vector< T >	smallMaskedFractile (const MaskedLattice< T > &lattice, Float fraction)
	Determine the fractile for a small masked lattice. More...

static Vector< T >	smallMaskedFractiles (const MaskedLattice< T > &lattice, Float left, Float right)
	Determine the fractiles for a small masked lattice. More...

static uInt	maskedHistogram (T &stv, T &endv, T &minv, T &maxv, Block< uInt > &hist, Block< T > &boundaries, const MaskedLattice< T > &lattice)
	Calculate the first histogram (with 10000 bins). More...

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

static uInt	findBin (uInt &fractileInx, T &stv, T &endv, T minv, T maxv, const Block< uInt > &hist, const Block< T > &boundaries)
	Helper function which determines which bin in the histogram contains the passed index. More...

Detailed Description

template<class T>
class casacore::LatticeFractile< T >

Static functions to get median and fractiles of a lattice.

Intended use:

Internal

Review Status

Date Reviewed:: yyyy/mm/dd
Test programs:: tLatticeFractile tLELMedian

Prerequisite

Lattice

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.

Definition at line 91 of file LatticeFractile.h.

Member Function Documentation

template<class T >

static uInt casacore::LatticeFractile< T >::findBin	(	uInt &	fractileInx,
		T &	stv,
		T &	endv,
		T	minv,
		T	maxv,
		const Block< uInt > &	hist,
		const Block< T > &	boundaries
	)

staticprivate

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. On output stv and endv are set to the boundaries of the bin containing the index and fractileInx is set to the index in that bin. The nr of values in that bin is returned as the function value. minv and maxv are used as the outer limits, thus the first bin extends to minv and the last bin to maxv. If the bins are getting too small (i.e. if stv is nearly endv), 0 is returned. In that case endv contains the fractile.

template<class T >

static Vector<T> casacore::LatticeFractile< T >::maskedFractile	(	const MaskedLattice< T > &	lattice,
		Float	fraction,
		uInt	smallSize = `4096 *4096`
	)

static

template<class T >

static Vector<T> casacore::LatticeFractile< T >::maskedFractiles	(	const MaskedLattice< T > &	lattice,
		Float	left,
		Float	right,
		uInt	smallSize = `4096 *4096`
	)

static

template<class T >

static uInt casacore::LatticeFractile< T >::maskedHistogram	(	T &	stv,
		T &	endv,
		T &	minv,
		T &	maxv,
		Block< uInt > &	hist,
		Block< T > &	boundaries,
		const MaskedLattice< T > &	lattice
	)

staticprivate

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.

template<class T >

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

staticprivate

Determine the fractile for a small masked lattice.

template<class T >

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

staticprivate

Determine the fractiles for a small masked lattice.

template<class T >

static Vector<T> casacore::LatticeFractile< T >::unmaskedFractile	(	const Lattice< T > &	lattice,
		Float	fraction,
		uInt	smallSize = `4096 *4096`
	)

static

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, only 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.

template<class T >

static Vector<T> casacore::LatticeFractile< T >::unmaskedFractiles	(	const Lattice< T > &	lattice,
		Float	left,
		Float	right,
		uInt	smallSize = `4096 *4096`
	)

static

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.

template<class T >

static void casacore::LatticeFractile< T >::unmaskedHistogram	(	T &	stv,
		T &	endv,
		T &	minv,
		T &	maxv,
		Block< uInt > &	hist,
		Block< T > &	boundaries,
		const Lattice< T > &	lattice
	)

staticprivate

The documentation for this class was generated from the following file:

lattices/LatticeMath/LatticeFractile.h

Static Public Member Functions

Static Private Member Functions

Detailed Description

template<class T> class casacore::LatticeFractile< T >

Intended use:

Review Status

Prerequisite

Synopsis

Motivation

Member Function Documentation

template<class T>
class casacore::LatticeFractile< T >