casacore
LatticeFractile.h
Go to the documentation of this file.
1//# LatticeFractile.cc: Static functions to get median and fractiles
2//# Copyright (C) 1999,2000,2001
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef LATTICES_LATTICEFRACTILE_H
29#define LATTICES_LATTICEFRACTILE_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/casa/Arrays/ArrayFwd.h>
35
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39template<class T> class Lattice;
40template<class T> class MaskedLattice;
41template<class T> class Block;
42
43
44// <summary>
45// Static functions to get median and fractiles of a lattice
46// </summary>
47
48// <use visibility=local>
49
50// <reviewed reviewer="" date="yyyy/mm/dd" tests="tLatticeFractile.cc tLELMedian.cc" demos="">
51// </reviewed>
52
53// <prerequisite>
54// <li> <linkto class="Lattice"> Lattice</linkto>
55// </prerequisite>
56
57// <synopsis>
58// This class contains a few static functions to find 1 or 2 fractiles
59// in a lattice. They are primarily used by the LEL classes, but can
60// also be used standalone.
61// <br>
62// A fractile is the same as a percentile be it that it is given as a
63// fraction instead of a percentage. A fraction of 0.5 yields the median.
64// <br>
65// When the lattice has a mask, only the masked-on elements are taken into
66// account. If all elements are masked_off, an empty Vector is returned
67// indicating that no fractiles were found.
68// <p>
69// The algorithm used depends on the size of the lattice.
70// Smallish lattices (i.e. not exceeding the argument smallSize)
71// are handled in one pass im memory.
72// For bigger lattices a multi-pass algorithm is used. First the
73// lattices is binned. Thereafter the algorithm continues with the
74// elements of the bins containing the fractiles. This continues
75// until the number of elements left is less than <src>smallSize</src>.
76// Typically only 2 passes are needed for a big image.
77// <br>
78// The algorithm is robust and takes possible rounding errors into account.
79// It also takes into account that the lattice can contain many equal values.
80// </synopsis>
81
82// <motivation>
83// Separated from file LELFunction.h to make it more commonly usable
84// and to make the source files more readable.
85// </motivation>
86
87//# <todo asof="2001/02/10">
88//# </todo>
89
90
91template<class T> class LatticeFractile
92{
93public:
94 // Determine the fractile of the given lattice. It returns the value
95 // of the lattice at the given fraction. A fraction of 0.5 returns
96 // the median. If the lattice has an even number of elements and if
97 // the lattice is small enough (< 100 elements), the median is the
98 // mean of the 2 middle elements.
99 // <br>If the lattice is masked, only masked-on elements are taken
100 // into account.
101 // <br>If the lattice is large, successive histograms are made until
102 // <src>smallSize</src> elements are left. Thereafter an in-memory
103 // algorithm will be used to finish.
104 // The number of passes made over the data is undetermined, but
105 // a typical number is 2 passes.
106 // <br>Normally a vector with 1 element is returned.
107 // If the lattice has no masked-on elements, an empty vector is returned.
108 // <group>
109 static Vector<T> unmaskedFractile (const Lattice<T>& lattice,
110 Float fraction,
111 uInt smallSize = 4096*4096);
113 Float fraction,
114 uInt smallSize = 4096*4096);
115 // </group>
116
117 // Determine the values of the 2 elements at the given fractiles.
118 // Thus <src>left=0.25; right=0.75</src> gives the quartiles of the lattice.
119 // <br>If the lattice is masked, onlu masked-on elements are taken
120 // into account.
121 // <br>If the lattice is large, successive histograms are made until
122 // <src>smallSize</src> elements are left. Thereafter an in-memory
123 // algorithm will be used to finish.
124 // The number of passes made over the data is undetermined, but
125 // a typical number is 2 passes.
126 // <br>Normally a vector with 2 elements is returned.
127 // If the lattice has no masked-on elements, an empty vector is returned.
128 // <group>
129 static Vector<T> unmaskedFractiles (const Lattice<T>& lattice,
130 Float left, Float right,
131 uInt smallSize = 4096*4096);
133 Float left, Float right,
134 uInt smallSize = 4096*4096);
135 // </group>
136
137private:
138 // Determine the fractile for a small masked lattice.
140 Float fraction);
141
142 // Determine the fractiles for a small masked lattice.
144 Float left, Float right);
145
146 // Calculate the first histogram (with 10000 bins).
147 // Also calculate the minimum and maximum. It returns the number
148 // of masked-on values. Masked-off values are ignored.
149 // <group>
150 static uInt maskedHistogram (T& stv, T& endv, T& minv, T& maxv,
151 Block<uInt>& hist,
152 Block<T>& boundaries,
153 const MaskedLattice<T>& lattice);
154 static void unmaskedHistogram (T& stv, T& endv, T& minv, T& maxv,
155 Block<uInt>& hist,
156 Block<T>& boundaries,
157 const Lattice<T>& lattice);
158 // </group>
159
160 // Helper function which determines which bin in the histogram
161 // contains the passed index.
162 // On input fractileInx gives the index of the fractile in the entire
163 // histogram.
164 // On output stv and endv are set to the boundaries of the bin containing
165 // the index and fractileInx is set to the index in that bin.
166 // The nr of values in that bin is returned as the function value.
167 // minv and maxv are used as the outer limits, thus the first bin extends
168 // to minv and the last bin to maxv.
169 // If the bins are getting too small (i.e. if stv is nearly endv), 0 is
170 // returned. In that case endv contains the fractile.
171 static uInt findBin (uInt& fractileInx,
172 T& stv, T& endv,
173 T minv, T maxv,
174 const Block<uInt>& hist,
175 const Block<T>& boundaries);
176};
177
178
179
180} //# NAMESPACE CASACORE - END
181
182#ifndef CASACORE_NO_AUTO_TEMPLATES
183#include <casacore/lattices/LatticeMath/LatticeFractile.tcc>
184#endif //# CASACORE_NO_AUTO_TEMPLATES
185#endif
static Vector< T > unmaskedFractile(const Lattice< T > &lattice, Float fraction, uInt smallSize=4096 *4096)
Determine the fractile of the given lattice.
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).
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 Vector< T > maskedFractiles(const MaskedLattice< T > &lattice, Float left, Float right, uInt smallSize=4096 *4096)
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.
static void unmaskedHistogram(T &stv, T &endv, T &minv, T &maxv, Block< uInt > &hist, Block< T > &boundaries, const Lattice< T > &lattice)
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.
static Vector< T > maskedFractile(const MaskedLattice< T > &lattice, Float fraction, uInt smallSize=4096 *4096)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
float Float
Definition: aipstype.h:54