casacore
LatticeHistograms.h
Go to the documentation of this file.
1 //# LatticeHistograms.h: generate histograms from a lattice
2 //# Copyright (C) 1996,1997,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_LATTICEHISTOGRAMS_H
29 #define LATTICES_LATTICEHISTOGRAMS_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Arrays/ArrayFwd.h>
35 #include <casacore/lattices/LatticeMath/TiledCollapser.h>
36 #include <casacore/lattices/LatticeMath/LatticeStatistics.h>
37 #include <casacore/lattices/LatticeMath/LatticeProgress.h>
38 #include <casacore/casa/Logging/LogIO.h>
39 #include <casacore/casa/System/PGPlotter.h>
40 #include <casacore/scimath/Mathematics/NumericTraits.h>
41 #include <casacore/casa/iosfwd.h>
42 
43 namespace casacore { //# NAMESPACE CASACORE - BEGIN
44 
45 //# Forward Declarations
46 template <class T> class MaskedLattice;
47 template <class T> class TempLattice;
48 class IPosition;
49 class PGPlotter;
50 
51 // <summary>
52 // Displays histograms of regions from a lattice.
53 // </summary>
54 
55 // <use visibility=export>
56 
57 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
58 // </reviewed>
59 
60 // <prerequisite>
61 // <li> <linkto class=MaskedLattice>MaskedLattice</linkto>
62 // </prerequisite>
63 
64 // <etymology>
65 // This is a class designed to display histograms from MaskedLattices
66 // </etymology>
67 
68 // <synopsis>
69 // This class enable you to display and/or retrieve histograms evaluated over
70 // specified regions from a MaskedLattice. The dimension of the region is arbitrary, but
71 // the size of each dimension is always the size of the corresponding lattice axis.
72 // The histograms are displayed as a function of location of the axes not
73 // used to evaluate the histograms over. The axes which you evaluate the histograms
74 // over are called the cursor axes, the others are called the display axes.
75 //
76 // For example, consider a lattice cube (call the axes xyz or [0,1,2]). You could
77 // display histograms from xy planes (cursor axes [0,1]) as a function of z (display
78 // axes [2]). Or you could retrieve histograms from the z axis (cursor axes [2])
79 // for each [x,y] location (display axes [0,1]).
80 //
81 // This class generates a "storage lattice" into which it writes the histograms.
82 // It is from this storage lattice that the plotting and retrieval
83 // arrays are drawn. The storage lattice is either in core or on disk
84 // depending upon its size (if > 10% of memory given by .aipsrc system.resources.memory
85 // then it goes into a disk-based PagedArray). If on disk, the
86 // storage lattice is deleted when the <src>LatticeHistograms</src>
87 // object destructs.
88 //
89 //
90 // <note role=tip>
91 // Note that for complex lattices, real and imaginary are treated independently.
92 // They are binned and plotted separately.
93 // </note>
94 //
95 // <note role=tip>
96 // If you ignore return error statuses from the functions that set the
97 // state of the class, the internal status of the class is set to bad.
98 // This means it will just keep on returning error conditions until you
99 // explicitly recover the situation. A message describing the last
100 // error condition can be recovered with function errorMessage.
101 
102 // </note>
103 // </synopsis>
104 
105 // <example>
106 // <srcBlock>
108 //
109 // PagedImage<Float> inImage(inName);
110 //
112 //
113 // LogOrigin or("myClass", "myFunction(...)", WHERE);
114 // LogIO os(or);
115 // ImageHistograms<Float> histo(inImage, os);
116 //
118 //
119 // Vector<Int> cursorAxes(2)
120 // cursorAxes(0) = 1;
121 // cursorAxes(1) = 2;
122 // if (!histo.setAxes(cursorAxes)) return 1;
123 //
125 //
126 // if (!histo.setList(True)) return 1;
127 // String device = "/xs";
128 // Vector<Int> nxy(2);
129 // nxy(0) = 3;
130 // nxy(1) = 3;
131 // if (!histo.setPlotting(device, nxy)) return 1;
132 //
134 //
135 // if (!histo.display ()) return 1;
136 //
138 //
139 // Array<Float> values, counts;
140 // if (!histo.getHistograms(values, counts)) return 1;
141 //
142 // </srcBlock>
143 // In this example, a <src>PagedImage</src> is constructed. We set the cursor axes
144 // to be the y and z axes so we make a histogram of each yz plane as a function
145 // of x location on the PGPLOT device "/xs" with 9 subplots per page.
146 // After the plotting we also retrieve the histograms into an array.
147 // </example>
148 
149 // <motivation>
150 // The generation of histograms from an image is a basic and necessary capability.
151 // </motivation>
152 //
153 // <todo asof="2000/04/04">
154 // <li> Make ascii listing of histograms as well as plots if desired
155 // </todo>
156 //
157 
158 
159 template <class T> class LatticeHistograms
160 {
161 public:
162 
163 // Constructor takes the MaskedLattice and a <src>LogIO</src> object for logging.
164 // You can also specify whether you want to see progress meters or not.
165 // You can force the storage lattice to be disk based, otherwise
166 // the decision for core or disk is taken for you.
168  LogIO& os,
169  Bool showProgress=True,
170  Bool forceDisk=False);
171 
172 // Constructor takes the MaskedLattice only. In the absence of a logger you get no messages.
173 // This includes error messages and potential listing of statistics.
174 // You can specify whether you want to see progress meters or not.
175 // You can force the storage lattice to be disk based, otherwise
176 // the decision for core or disk is taken for you.
178  Bool showProgress=True,
179  Bool forceDisk=False);
180 
181 // Copy constructor (copy semantics)
183 
184 // Destructor
185  virtual ~LatticeHistograms ();
186 
187 // Assignment operator (copy semantics)
189 
190 // Set the cursor axes (0 relative). A return value of <src>False</src>
191 // indicates you have asked for an invalid axis or that the internal
192 // status of the class is bad. The default state of the class is to set
193 // the cursor axes to all axes in the lattice.
194  Bool setAxes (const Vector<Int>& cursorAxes);
195 
196 // Set the number of bins for the histogram. Note that the bin width is
197 // worked out for each histogram separately from the data minimum and maximum.
198 // The default state of the class is to set 25 bins. A return value of <src>False</src>
199 // indicates you gave a non-positive bin width or that the internal status of the
200 // class is bad.
201  Bool setNBins (const uInt& nBins);
202 
203 // Specify a pixel intensity range for which all pixels in that range are
204 // included. A vector of length 1 for <src>include</src> means that the
205 // range will be set to <src>-abs(include(0))</src> to <src>abs(include(0))</src>.
206 // A return value of <src>False</src> indicates that the internal
207 // status of the class is bad. If you don't call this function, the default
208 // state of the class is to include all pixels.
209  Bool setIncludeRange (const Vector<T>& include);
210 
211 // Specify that a Gaussian overlay should be plotted on the histogram. This
212 // Gaussian has the same mean and standard deviation as the data that were
213 // binned, and the same integral as the histogram. A return value of <src>False</src>
214 // indicates that the internal status of the class is bad. The default state of
215 // the class is to not draw a Gaussian overlay.
216  Bool setGaussian (const Bool& doGauss);
217 
218 // Specify the form of the histogram. It can be plotted linearly or
219 // logarithmically, and cumulatively or non-cumulatively. A return value
220 // of <src>False</src> indicates that the internal status of the class is bad.
221 // The default state of the class is to draw the histograms linearly and
222 // non-cumulatively.
223  Bool setForm (const Bool& doLog, const Bool& doCumu);
224 
225 // This function allows you to control whether some statistics of the
226 // data that contributed to the histogram are written to the output
227 // stream. A return value of <src>False</src> indicates that the internal
228 // status of the class is bad. The default state of the class is to not
229 // list statistics.
230  Bool setStatsList(const Bool& doList);
231 
232 // This function sets the name of the PGPLOT plotting device and the number of
233 // subplots in x and y per page. If you set <src>plotter</src> but offer
234 // a zero length array for <src>nxy</src> then <src>nxy</src> is set
235 // to [1,1]. A return value of <src>False</src> indicates invalid
236 // plotting arguments or that the internal status of the class is bad. If you
237 // don't call this function, the default state of the class is to not set
238 // a plotting device.
240  const Vector<Int>& nxy);
241 
242 // Display the histograms by plotting them. A return value of <src>False</src>
243 // indicates an invalid plotting device, or that the internal status of the class is bad.
244 // If you don't call this function you won't see any histograms.
246 
247 // CLose the plotter
249 
250 // Return the display axes
252 
253 // This function retrieves the histograms into <src>Array</src>. The shape of the first
254 // dimension of this array is the number of bins. The rest of the shape of the
255 // array is the shape of the display axes (e.g. if the shape of the lattice is
256 // [nx,ny,nz] and you ask for histograms of the y axis the shape of the returned
257 // array would be [nbins,nx,nz]. The histograms are retrieved in the form
258 // specified by the <src>setForm</src> function. The arrays are resized internally.
259 // A return value of <src>False</src> indicates that the internal status of the class is bad.
260  Bool getHistograms (Array<T>& values, Array<T>& counts);
261 
262  // in this version, the set of stats for each histogram is also returned. The
263  // stats array has the shape of the display axes.
264  Bool getHistograms (Array<T>& values, Array<T>& counts, Array<Vector<T> >& stats);
265 
266 
267 // This function retrieves the histogram at the specified location
268 // into <src>Vectors</src>. The histogram is retrieved in the form
269 // specified by the <src>setForm</src> function. The vectors are resized
270 // internally. If <src>posInLattice=True</src> then the location is a
271 // location in the input lattice. Any positions on the display axes
272 // are ignored. Otherwise, you should just give locations for
273 // the display axes only. A return value of <src>False</src> indicates that
274 // the internal status of the class is bad.
276  Vector<T>& counts,
277  const IPosition& pos,
278  const Bool posInLattice=False);
279 
280 // Reset argument error condition. If you specify invalid arguments to
281 // one of the above <src>set</src> functions, an internal flag will be set which will
282 // prevent the work functions from doing anything (should you have chosen
283 // to ignore the Boolean return values of the <src>set</src> functions).
284 // This function allows you to reset that internal state to good.
286 
287 // Recover last error message
288  String errorMessage() const {return error_p;};
289 
290 // Set a MaskedLattice. A return value of <src>False</src> indicates the
291 // lattice had an invalid type or that the internal status of the class is bad.
293 
294 // These things are protected only so that they are available to ImageHistograms
295 // which inherits from LatticeHistograms
296 
297 protected:
302 
303 // Given a location in the histogram storage lattice, convert those locations on the
304 // non-histogram axis (the first one) relative to the parent or current lattice
305  IPosition locHistInLattice (const IPosition& histPosition,
306  Bool relativeToParent=True) const;
307 
308 private:
309 
310 // A useful typedef
312 
324 
325 
326 // Convert a <tt>T</tt> to a <tt>Float</tt> for plotting
327  static Float convertT (const T value) {return Float(std::real(value));};
328 
329 // Convert a <tt>Float</tt> (from plotting) to a <tt>T</tt>
330  static T convertF (const Float value) {return T(value);};
331 
332 // Display histograms as a function of display axis
334 
335 // Display one histogram
336  Bool displayOneHistogram (const T&linearSum,
337  const T&linearYMax,
338  const IPosition& histPos,
339  const Vector<T> &stats,
340  const Vector<T>& values,
341  const Vector<T>& counts,
342  PGPlotter& plotter);
343 
344 
345 // Fish out and convert to the appropriate form one histogram from the
346 // storage lattice
347  void extractOneHistogram (T& linearSum,
348  T& linearYMax,
349  Vector<T>& values,
350  Vector<T>& counts,
351  const Vector<T>& stats,
352  const Vector<T>& intCounts);
353 
354 // Iterate through the lattice and generate the histogram accumulation lattice
356 
357 // Get the statistics from the statistics object for the current
358 // location of either the input lattice, or the histogram storage lattice
359  void getStatistics (Vector<T> &stats,
360  const IPosition &pos) const;
361 
362 // List statistics
363  void listStatistics(LogIO& os, const Vector<T>& stats, T binWidth);
364 
365 
366 // Fill histograms storage lattice
368 
369 // Create and fill statistics object
371 
372 // Check/set include pixel range
374  Bool& noInclude,
375  const Vector<T>& include,
376  ostream& os);
377 
378 // Set stream attributes
379  void setStream (ostream& os, Int oPrec);
380 
381 // Make a string with pixel coordinates of display axes. This function
382 // is over-ridden by ImageHistograms which inherits from LatticeHistograms.
383  virtual String writeCoordinates(const IPosition& histPos) const;
384 
385 // Write values of display axes on plots
387  PGPlotter& plotter,
388  Float nchar) const;
389 };
390 
391 
392 
393 // <summary> Generate histograms, tile by tile, from a masked lattice </summary>
394 //
395 // <use visibility=export>
396 //
397 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
398 // </reviewed>
399 //
400 // <prerequisite>
401 // <li> <linkto class=LatticeApply>LatticeApply</linkto>
402 // <li> <linkto class=TiledCollapser>TiledCollapser</linkto>
403 // </prerequisite>
404 //
405 // <etymology>
406 // This class is used by <src>LatticeHistograms</src> to generate
407 // histograms from an input <src>MaskedLattice</src>.
408 // The input lattice is iterated through in tile-sized chunks
409 // and fed to an object of this class.
410 // </etymology>
411 //
412 // <synopsis>
413 // <src>HistTiledCollapser</src> is derived from <src>TiledCollapser</src> which
414 // is a base class used to define methods. Objects of this base class are
415 // used by <src>LatticeApply</src> functions. In this particular case,
416 // we are interested in <src>LatticeApply::tiledApply</src>. This function iterates
417 // through a <src>MaskedLattice</src> and allows you to collapse one or more
418 // axes, computing some values from it, and placing those values into
419 // an output <src>MaskedLattice</src>. It iterates through the input
420 // lattice in optimal tile-sized chunks. <src>LatticeHistograms</src>
421 // uses a <src>HistTiledCollapser</src> object which it gives to
422 // <src>LatticeApply::tiledApply</src> for digestion. After it has
423 // done its work, <src>LatticeHistograms</src> then accesses the output
424 // <src>Lattice</src> that it made.
425 // </synopsis>
426 //
427 // <example>
428 // <srcblock>
430 //
431 // HistTiledCollapser<T> collapser(pStats, nBins_p);
432 //
435 //
436 // Int newOutAxis = 0;
437 //
440 //
441 // LatticeApply<T>::tiledApply(outLattice, inLattice,
442 // collapser, collapseAxes,
443 // newOutAxis);
444 //
445 // </srcblock>
446 // In this example, a collapser is made and passed to LatticeApply.
447 // Afterwards, the output Lattice is available for use.
448 // The Lattices must all be the correct shapes on input to tiledApply
449 // </example>
450 //
451 // <motivation>
452 // The LatticeApply classes enable the ugly details of optimal
453 // Lattice iteration to be hidden from the user.
454 // </motivation>
455 //
456 // <todo asof="1998/05/10">
457 // <li>
458 // </todo>
459 
460 template <class T>
462 {
463 
464 public:
465 // Constructor
467 
469 
470 // Initialize process, making some checks
471  virtual void init (uInt nOutPixelsPerCollapse);
472 
473 // Initialize the accumulator
474  virtual void initAccumulator (uInt64 n1, uInt64 n3);
475 
476 // Process the data in the current chunk.
477  virtual void process (
478  uInt accumIndex1,
479  uInt accumIndex3,
480  const T* inData,
481  const Bool* inMask,
482  uInt inDataIncr,
483  uInt inMaskIncr,
484  uInt nrval,
485  const IPosition& startPos,
486  const IPosition& shape
487  );
488 
489 // End the accumulation process and return the result arrays
490  virtual void endAccumulator(Array<T>& result,
491  Array<Bool>& resultMask,
492  const IPosition& shape);
493 
494 // Can handle null mask
495  virtual Bool canHandleNullMask() const {return True;};
496 
497 private:
503 };
504 
505 
506 
507 } //# NAMESPACE CASACORE - END
508 
509 #ifndef CASACORE_NO_AUTO_TEMPLATES
510 #include <casacore/lattices/LatticeMath/LatticeHistograms.tcc>
511 #endif //# CASACORE_NO_AUTO_TEMPLATES
512 #endif
simple 1-D array
Definition: Block.h:200
Generate histograms, tile by tile, from a masked lattice.
LatticeStatistics< T > * pStats_p
virtual void process(uInt accumIndex1, uInt accumIndex3, const T *inData, const Bool *inMask, uInt inDataIncr, uInt inMaskIncr, uInt nrval, const IPosition &startPos, const IPosition &shape)
Process the data in the current chunk.
virtual Bool canHandleNullMask() const
Can handle null mask.
HistTiledCollapser(LatticeStatistics< T > *pStats, uInt nBins)
Constructor.
virtual void init(uInt nOutPixelsPerCollapse)
Initialize process, making some checks.
virtual void initAccumulator(uInt64 n1, uInt64 n3)
Initialize the accumulator.
virtual void endAccumulator(Array< T > &result, Array< Bool > &resultMask, const IPosition &shape)
End the accumulation process and return the result arrays
Bool setNBins(const uInt &nBins)
Set the number of bins for the histogram.
LatticeStatistics< T > * pStats_p
Bool setInclude(Vector< T > &range, Bool &noInclude, const Vector< T > &include, ostream &os)
Check/set include pixel range.
void setStream(ostream &os, Int oPrec)
Set stream attributes.
Bool writeDispAxesValues(const String &coords, PGPlotter &plotter, Float nchar) const
Write values of display axes on plots.
Vector< Int > displayAxes() const
Return the display axes.
Bool displayOneHistogram(const T &linearSum, const T &linearYMax, const IPosition &histPos, const Vector< T > &stats, const Vector< T > &values, const Vector< T > &counts, PGPlotter &plotter)
Display one histogram.
virtual String writeCoordinates(const IPosition &histPos) const
Make a string with pixel coordinates of display axes.
Bool displayHistograms()
Display histograms as a function of display axis.
Bool setAxes(const Vector< Int > &cursorAxes)
Set the cursor axes (0 relative).
Bool setStatsList(const Bool &doList)
This function allows you to control whether some statistics of the data that contributed to the histo...
Bool makeStatistics()
Create and fill statistics object.
void getStatistics(Vector< T > &stats, const IPosition &pos) const
Get the statistics from the statistics object for the current location of either the input lattice,...
void makeHistograms()
Fill histograms storage lattice.
virtual ~LatticeHistograms()
Destructor.
String errorMessage() const
Recover last error message.
LatticeHistograms(const MaskedLattice< T > &lattice, Bool showProgress=True, Bool forceDisk=False)
Constructor takes the MaskedLattice only.
LatticeHistograms(const MaskedLattice< T > &lattice, LogIO &os, Bool showProgress=True, Bool forceDisk=False)
Constructor takes the MaskedLattice and a LogIO object for logging.
void closePlotting()
CLose the plotter.
void resetError()
Reset argument error condition.
Bool setForm(const Bool &doLog, const Bool &doCumu)
Specify the form of the histogram.
Bool generateStorageLattice()
Iterate through the lattice and generate the histogram accumulation lattice.
Bool setGaussian(const Bool &doGauss)
Specify that a Gaussian overlay should be plotted on the histogram.
NumericTraits< T >::PrecisionType AccumType
A useful typedef.
IPosition locHistInLattice(const IPosition &histPosition, Bool relativeToParent=True) const
Given a location in the histogram storage lattice, convert those locations on the non-histogram axis ...
static T convertF(const Float value)
Convert a Float (from plotting) to a T
void listStatistics(LogIO &os, const Vector< T > &stats, T binWidth)
List statistics.
LatticeHistograms< T > & operator=(const LatticeHistograms< T > &other)
Assignment operator (copy semantics)
Bool setNewLattice(const MaskedLattice< T > &lattice)
Set a MaskedLattice.
const MaskedLattice< T > * pInLattice_p
Bool getHistograms(Array< T > &values, Array< T > &counts)
This function retrieves the histograms into Array.
Bool display()
Display the histograms by plotting them.
LogIO os_p
These things are protected only so that they are available to ImageHistograms which inherits from Lat...
static Float convertT(const T value)
Convert a T to a Float for plotting.
Bool setPlotting(PGPlotter &plotter, const Vector< Int > &nxy)
This function sets the name of the PGPLOT plotting device and the number of subplots in x and y per p...
Bool setIncludeRange(const Vector< T > &include)
Specify a pixel intensity range for which all pixels in that range are included.
Bool getHistogram(Vector< T > &values, Vector< T > &counts, const IPosition &pos, const Bool posInLattice=False)
This function retrieves the histogram at the specified location into Vectors.
TempLattice< T > * pStoreLattice_p
void extractOneHistogram(T &linearSum, T &linearYMax, Vector< T > &values, Vector< T > &counts, const Vector< T > &stats, const Vector< T > &intCounts)
Fish out and convert to the appropriate form one histogram from the storage lattice.
Bool getHistograms(Array< T > &values, Array< T > &counts, Array< Vector< T > > &stats)
in this version, the set of stats for each histogram is also returned.
LatticeHistograms(const LatticeHistograms< T > &other)
Copy constructor (copy semantics)
Char PrecisionType
Higher precision type (Float->Double)
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition: ExprNode.h:1987
float Float
Definition: aipstype.h:54
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
const Bool True
Definition: aipstype.h:43
LatticeExprNode real(const LatticeExprNode &expr)
unsigned long long uInt64
Definition: aipsxtype.h:39