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
43namespace casacore { //# NAMESPACE CASACORE - BEGIN
44
45//# Forward Declarations
46template <class T> class MaskedLattice;
47template <class T> class TempLattice;
48class IPosition;
49class 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
159template <class T> class LatticeHistograms
160{
161public:
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
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.
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.
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
297protected:
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
308private:
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
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
460template <class T>
462{
463
464public:
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
497private:
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.
LatticeHistograms< T > & operator=(const LatticeHistograms< T > &other)
Assignment operator (copy semantics)
Bool writeDispAxesValues(const String &coords, PGPlotter &plotter, Float nchar) const
Write values of display axes on plots.
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.
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.
Vector< Int > displayAxes() const
Return the display axes.
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