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 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 template<class T> class Lattice;
40 template<class T> class MaskedLattice;
41 template<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 
91 template<class T> class LatticeFractile
92 {
93 public:
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);
112  static Vector<T> maskedFractile (const MaskedLattice<T>& lattice,
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 
137 private:
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 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 > smallMaskedFractiles(const MaskedLattice< T > &lattice, Float left, Float right)
Determine the fractiles for a small masked lattice.
static Vector< T > maskedFractile(const MaskedLattice< T > &lattice, Float fraction, 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 > maskedFractiles(const MaskedLattice< T > &lattice, Float left, Float right, uInt smallSize=4096 *4096)
static Vector< T > unmaskedFractile(const Lattice< T > &lattice, Float fraction, uInt smallSize=4096 *4096)
Determine the fractile of the given lattice.
static Vector< T > smallMaskedFractile(const MaskedLattice< T > &lattice, Float fraction)
Determine the fractile for a small masked lattice.
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