casa  5.7.0-16
casacore::LatticeFractile< T > Class Template Reference

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.

Internal

### Review Status

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

### 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 casacore::LatticeFractile< T >::maskedFractile ( const MaskedLattice< T > & lattice, Float fraction, uInt smallSize = `4096 *4096` )
static
template<class T >
 static Vector 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 casacore::LatticeFractile< T >::smallMaskedFractile ( const MaskedLattice< T > & lattice, Float fraction )
staticprivate

Determine the fractile for a small masked lattice.

template<class T >
 static Vector 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 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 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: