For example, consider a lattice cube (call the axes xyz or [0,1,2]). You could display statistics from xy planes (cursor axes [0,1]) as a function of z (display axes [2]). Or you could retrieve statistics from the z axis (cursor axes [2]) for each [x,y] location (display axes [0,1]).
This class inherits from LatticeStatsBase This base class provides an enum defining allowed statistics types and a helper function to convert between a String and a Vector<Int> describing the desired statistics to plot. An example is shown below.
This class can list, plot and retrieve statistics. When it lists statistics, it always lists all the available statistics. When you plot statistics, you must specify which ones you would like to see.
This class generates a "storage lattice" into which it writes the accumulated statistical sums. It is from this storage lattice that the plotting and retrieval arrays are drawn. The storage lattice is either in core or on disk depending upon its size (if > 10% of memory given by .aipsrc system.resources.memory then it goes into a disk-based PagedArray). If on disk, the storage lattice is deleted when the LatticeStatistics class object destructs. However, currently, if the process is terminated ungracefully, the storage lattice will be left over.
This class has a few virtual functions; they are not part of a nice general polymorphic interface; rather they have specialized functionality. The idea of these is that you can derive a class from LatticeStatistics, such as ImageStatistics which provides you with a little more information when displaying/logging the statistics (such as world coordinates) The virtual functions are
// Construct PagedImage (which isA MaskedLattice) from file name
PagedImage<Float> inImage(inName);
// Construct statistics object
LogOrigin or("myClass", "myFunction(...)", WHERE);
LogIO os(or);
LatticeStatistics<Float> stats(SubImage<FLoat>(inImage), os);
// Set cursor axes to see statistics of yz planes (0 relative)
Vector<Int> cursorAxes(2)
cursorAxes(0) = 1;
cursorAxes(1) = 2;
if (!stats.setAxes(cursorAxes)) return 1;
// Set to list and plot mean, sigma and rms
if (!stats.setList(True)) return 1;
String device = "/xs";
Vector<Int> nxy(2);
nxy(0) = 1;
nxy(1) = 1;
Vector<Int> statsToPlot = LatticeStatsBase::toStatisticTypes("mean,rms,sigma");
if (!stats.setPlotting(statsToPlot, device, nxy)) return 1;
// Now activate actual listing and plotting
if (!stats.display ()) return 1;
// Retrieve statistics into array
Array<Double> sum;
if (!stats.getStatistic(sum, LatticeStatsBase::SUM)) return 1;
In this example, a PagedImage is constructed (which isA
MaskedLattice) with . We set the cursor axes
to be the y and z axes, we specify to list the statistics if we plot them,
and we ask to plot the mean, standard deviation, and root mean square of each
yz plane as a function of x location on the PGPLOT device "/xs" with
1 subplot per page (there will be only one in this case). After the
plotting and listing, we also retrieve the sum of the selected pixels
as a function of x location into an array.
Constructor takes the lattice only. In the absence of a logger you get no messages. This includes error messages and potential listing of the statistics. You can specify whether you want to see progress meters or not. You can force the storage lattice to be disk based, otherwise the decision for core or disk is taken for you.
Copy constructor. Copy semantics are followed. Therefore any storage lattice that has already been created for other is copied to *this
Destructor
Assignment operator. Deletes any storage lattice associated with the object being assigned to and copies any storage lattice that has already been created for "other".
Set the cursor axes (0 relative). A return value of False indicates you have asked for an invalid axis. The default state of the class is to set the cursor axes to all axes in the lattice.
You may specify a pixel intensity range as either one for which all pixels in that range are included or one for which all pixels in that range are excluded. One or the other of include and exclude must therefore be a zero length vector if you call this function. If you are setting an include range, then if you set setMinMaxToInclude=True, the minimum and maximum values that this class returns will always be the minimum and maximum of the include range, respectively. A return value of False indicates that you have given both an include and an exclude range. A vector of length 1 for include and/or exclude means that the range will be set to (say for include) -abs(include(0))<src> to <src>abs(include(0)). A return value of False indicates that both an inclusion and exclusion range were given or that the internal state of the class is bad. If you don't call this function, the default state of the class is to include all pixels.
This function allows you to control whether the statistics are written to the output stream if you are also making a plot. A return value of False indicates that the internal state of the class is bad. If you have created the LatticeStatistics object without a LogIO object, you won't see any listings, but no error conditions will be generated. The default state of the class is to not list the output when making a plot.
This functions enable you to specify which statistics you would like to plot, sets the name of the PGPLOT plotting device and the number of subplots in x and y per page. If you set device but offer a zero length array for nxy then nxy is set to [1,1]. Similarly, the default for statsToPlot is to plot the mean and standard deviation. Use the helper function LatticeStatsBase::toStatisticTypes(String& stats) to convert a String to the desired Vector<Int> statsToPlot. A return value of False indicates invalid plotting arguments or that the internal state of the class is bad. If you don't call this function, the default state of the class is to not make plots.
Display the statistics by listing and/or plotting them. If you don't call this function then you won't see anything ! A return value of False indicates an invalid plotting device, or that the internal state of the class is bad.
CLose plotter
Return the display axes. The returned vector will be valid only if setAxes has been called, or if one of the active "display" or "get*" methods has been called.
Recover the desired Statistic into an array. If you choose to use the T version, be aware that the values in the AccumType version of the Array may not be representable in the T version (e.g. large values for SumSq). The shape of the array is the shape of the display axes (e.g. if the shape of the lattice is [nx,ny,nz] and you ask for the mean of the y axis the shape of the returned array would be [nx,nz]. A returned array of zero shape indicates that there were no good values. A return value of False indicates that the internal state of the class is bad.
Recover position of min and max. Only works if there are no display axes (i.e. statistics found over entire image), otherwise, the returned values are resized to 0 shape. A return value of False indicates that the internal state of the class is bad.
This function gets a vector containing all the statistics for a given location. If posInLattice=True then the location is a location in the input lattice. Any positions on the display axes are ignored. Otherwise, you should just give locations for the display axes only. Use can use the enum in class LatticeStatsBase to find out which locations in the vector contain which statistics. A returned vector of zero shape indicates that there were no good values. A return value of False indicates that the internal state of the class is bad.
Reset argument error condition. If you specify invalid arguments to one of the above set functions, an internal flag will be set which will prevent the work functions from doing anything (should you have chosen to ignore the Boolean return values of the set functions). This function allows you to reset that internal state to good.
Recover last error message
Did we construct with a logger ?
Virtual Functions. See implementation to figure it all out !
Get beam volume if possible. Your lattice needs to be an ImageInterface for you to be able to do this. See for example, class ImageStatistics. When you provide the beam, then the Flux statistic, if requested, can be computed. Returns False if beam not available, else True. The implementation here returns False.
List the statistics to the logger. The implementation here is adequate for all lattices. See ImageStatistics for an example of where extra information is provided. hasBeam is the return value of getBeamArea. If it is true, that means that the FLUX statistics will be available in the storage lattice. dPos is the location of the start of the cursor in the storage image for this row. stats(j,i) is the statistics matrix. for the jth point and the ith statistic. The return value is False if something goes wrong ! Have a look at the implementation to see what you really have to do.
Gets labels for higher order axes and x axis. dPos is the location of the start of the cursor in the storage image for this row.
Given a location in the storage lattice, convert those locations on the non-statistics axis (the last one) and optionally account for the lattice subsectioning
Non-virtual functions
set stream manipulators
Summarize the statistics found over the entire lattice
Calculate statistic from storage lattice and return in an array
Convert a
Find the next label in a list of comma delimitered labels
Find the median per cursorAxes chunk
Create a new storage lattice
Examine an array and determine how many segments of good points it consists
of. A good point occurs if the array value is greater than zero.
Given a location in the lattice and a statistic type, work
out where to put it in the storage lattice
Draw each Y-axis sublabel in a string with a different colour
Plot an array which may have some blanked points.
Thus we plot it in segments
Find min and max of good data in arrays specified by pointers
Find the next nice PGPLOT colour index
Plot the statistics
Retrieve a statistic from the storage lattice and return in an array
Retrieve a statistic from the storage lattice at the specified
location and return in an array
Find the shape of slice from the statistics lattice at one
spatial pixel
See if there were some valid points found in the storage lattice
Stretch min and max by 5%
Initialize process, making some checks
Initialiaze the accumulator
Process the data in the current chunk.
End the accumulation process and return the result arrays
Can handle null mask
Bool findNextDatum (uInt& iFound, const uInt& n, const Vector<AccumType>& mask, const uInt& iStart, const Bool& findGood) const
Find the next good or bad point in an array
Bool findNextLabel (String& subLabel, Int& iLab, String& label) const
void generateRobust ()
Bool generateStorageLattice ()
void lineSegments (uInt& nSeg, Vector<uInt>& start, Vector<uInt>& nPts, const Vector<AccumType>& mask) const
IPosition locInStorageLattice(const IPosition& latticePosition, LatticeStatsBase::StatisticsTypes type) const
void multiColourYLabel (String& label, PGPlotter& plotter, const String& LRLoc, const Vector<uInt>& colours, const Int& nLabs) const
void multiPlot (PGPlotter& plotter, const Vector<AccumType>& x, const Vector<AccumType>& y, const Vector<AccumType>& n) const
void minMax (Bool& none, AccumType& dMin, AccumType& dMax, const Vector<AccumType>& d, const Vector<AccumType>& n) const
Int niceColour (Bool& initColours) const
Bool plotStats (Bool hasBeam, const IPosition& dPos, const Matrix<AccumType>& ord, PGPlotter& plotter)
Bool retrieveStorageStatistic (Array<AccumType>& slice, LatticeStatsBase::LatticeStatsBase type, Bool dropDeg)
Bool retrieveStorageStatistic (Vector<AccumType>& slice, const IPosition& pos, const Bool posInLattice)
IPosition statsSliceShape () const
Bool someGoodPoints ()
void stretchMinMax (AccumType& dMin, AccumType& dMax) const
class StatsTiledCollapser : public TiledCollapser<T,U>
Interface
Description
Review Status
Prerequisite
Etymology
This class is used by LatticeStatistics to generate
statistical sum from an input MaskedLattice.
The input lattice is iterated through in tile-sized chunks
and fed to an object of this class.
Synopsis
StatsTiledCollapser is derived from TiledCollapser which
is a base class used to define methods. Objects of this base class are
used by LatticeApply functions. In this particular case,
we are interested in LatticeApply::tiledApply. This function iterates
through a MaskedLattice and allows you to collapse one or more
axes, computing some values from it, and placing those values into
an output MaskedLattice. It iterates through the input
lattice in optimal tile-sized chunks. LatticeStatistics
uses a StatsTiledCollapser object which it gives to
LatticeApply::tiledApply for digestion. After it has
done its work, LatticeStatistics then accesses the output
Lattice that it made.
Example
// Create collapser. Control information is passed in via the constructor
StatsTiledCollapser<T> collapser(range_p, noInclude_p, noExclude_p,
fixedMinMax_p, blcParent_p);
// This is the first output axis getting collapsed values. In LatticeStatistics
// this is the last axis of the output lattice
Int newOutAxis = outLattice.ndim()-1;
// tiledApply does the work by passing the collapser data in chunks
// and by writing the results into the output lattice
LatticeApply<T>::tiledApply(outLattice, inLattice,
collapser, collapseAxes,
newOutAxis);
In this example, a collapser is made and passed to LatticeApply.
Afterwards, the output Lattice is available for use.
The Lattices must all be the correct shapes on input to tiledApply
Motivation
The LatticeApply classes enable the ugly details of optimal
Lattice iteration to be hidden from the user.
To Do
Member Description
StatsTiledCollapser(const Vector<T>& pixelRange, Bool noInclude, Bool noExclude, Bool fixedMinMax)
Constructor provides pixel selection range and whether that
range is an inclusion or exclusion range. If fixedMinMax=True
and an inclusion range is given, the min and max is set to
that inclusion range.
virtual void init (uInt nOutPixelsPerCollapse)
virtual void initAccumulator (uInt n1, uInt n3)
virtual void process (uInt accumIndex1, uInt accumIndex3, const T* inData, const Bool* inMask, uInt inIncr, uInt nrval, const IPosition& startPos, const IPosition& shape)
virtual void endAccumulator(Array<U>& result, Array<Bool>& resultMask, const IPosition& shape)
virtual Bool canHandleNullMask() const
void minMaxPos(IPosition& minPos, IPosition& maxPos)
Find the location of the minimum and maximum data values
in the input lattice.