LatticeHistograms.h

Classes

LatticeHistograms -- Displays histograms of regions from a lattice. (full description)
HistTiledCollapser -- Generate histograms, tile by tile, from a masked lattice (full description)

template <class T> class LatticeHistograms

Interface

Public Members
LatticeHistograms(const MaskedLattice<T>& lattice, LogIO& os, Bool showProgress=True, Bool forceDisk=False)
LatticeHistograms(const MaskedLattice<T>& lattice, Bool showProgress=True, Bool forceDisk=False)
LatticeHistograms(const LatticeHistograms<T> &other)
virtual ~LatticeHistograms ()
LatticeHistograms<T> &operator=(const LatticeHistograms<T> &other)
Bool setAxes (const Vector<Int>& cursorAxes)
Bool setNBins (const uInt& nBins)
Bool setIncludeRange (const Vector<T>& include)
Bool setGaussian (const Bool& doGauss)
Bool setForm (const Bool& doLog, const Bool& doCumu)
Bool setStatsList(const Bool& doList)
Bool setPlotting(PGPlotter& plotter, const Vector<Int>& nxy)
Bool display ()
void closePlotting()
Vector<Int> displayAxes() const
Bool getHistograms (Array<T>& values, Array<T>& counts)
Bool getHistogram (Vector<T>& values, Vector<T>& counts, const IPosition& pos, const Bool posInLattice=False)
void resetError ()
String errorMessage() const
Bool setNewLattice (const MaskedLattice<T>& lattice)
Protected Members
IPosition locHistInLattice (const IPosition& histPosition, Bool relativeToParent=True) const
Private Members
static Float convertT (const T value)
static T convertF (const Float value)
Bool displayHistograms ()
Bool displayOneHistogram (const T&linearSum, const T&linearYMax, const IPosition& histPos, const IPosition<T> &stats, const IPosition<T>& values, const IPosition<T>& counts, Vector& plotter)
void extractOneHistogram (T& linearSum, T& linearYMax, Vector<T>& values, Vector<T>& counts, const Vector<T>& stats, const Vector<T>& intCounts)
Bool generateStorageLattice()
void getStatistics (Vector<T> &stats, const IPosition &pos) const
void listStatistics(LogIO& os, const Vector<T>& stats, T binWidth)
void makeHistograms()
Bool makeStatistics()
Bool setInclude (Vector<T>& range, Bool& noInclude, const Vector<T>& include, ostream& os)
void setStream (ostream& os, Int oPrec)
virtual String writeCoordinates(const IPosition& histPos) const
Bool writeDispAxesValues (const String& coords, PGPlotter& plotter, Float nchar) const

Description

Review Status

Date Reviewed:
yyyy/mm/dd

Prerequisite

Etymology

This is a class designed to display histograms from MaskedLattices

Synopsis

This class enable you to display and/or retrieve histograms evaluated over specified regions from a MaskedLattice. The dimension of the region is arbitrary, but the size of each dimension is always the size of the corresponding lattice axis. The histograms are displayed as a function of location of the axes not used to evaluate the histograms over. The axes which you evaluate the histograms over are called the cursor axes, the others are called the display axes.

For example, consider a lattice cube (call the axes xyz or [0,1,2]). You could display histograms from xy planes (cursor axes [0,1]) as a function of z (display axes [2]). Or you could retrieve histograms from the z axis (cursor axes [2]) for each [x,y] location (display axes [0,1]).

This class generates a "storage lattice" into which it writes the histograms. 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 LatticeHistograms object destructs.

Tip Note that for complex lattices, real and imaginary are treated independently. They are binned and plotted separately.
Tip If you ignore return error statuses from the functions that set the state of the class, the internal status of the class is set to bad. This means it will just keep on returning error conditions until you explicitly recover the situation. A message describing the last error condition can be recovered with function errorMessage.

Example

    // Construct PagedImage from file name
    
         PagedImage<Float> inImage(inName);
      
    // Construct histogram object
         
         LogOrigin or("myClass", "myFunction(...)", WHERE);
         LogIO os(or);
         ImageHistograms<Float> histo(inImage, os);
         
    // Set cursor axes to see statistics of yz planes (0 relative)
    
         Vector<Int> cursorAxes(2)
         cursorAxes(0) = 1;
         cursorAxes(1) = 2;
         if (!histo.setAxes(cursorAxes)) return 1;
    
    // Set to list and plot mean, sigma and rms
    
         if (!histo.setList(True)) return 1;
         String device = "/xs";
         Vector<Int> nxy(2);
         nxy(0) = 3;
         nxy(1) = 3;
         if (!histo.setPlotting(device, nxy)) return 1;
    
    // Now activate actual listing and plotting
    
         if (!histo.display ()) return 1;
    
    // Retrieve histograms into array
    
         Array<Float> values, counts;
         if (!histo.getHistograms(values, counts)) return 1;
    
    
In this example, a PagedImage is constructed. We set the cursor axes to be the y and z axes so we make a histogram of each yz plane as a function of x location on the PGPLOT device "/xs" with 9 subplots per page. After the plotting we also retrieve the histograms into an array.

Motivation

The generation of histograms from an image is a basic and necessary capability.

To Do

Member Description

LatticeHistograms(const MaskedLattice<T>& lattice, LogIO& os, Bool showProgress=True, Bool forceDisk=False)

Constructor takes the MaskedLattice and a LogIO object for logging. You can also 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.

LatticeHistograms(const MaskedLattice<T>& lattice, Bool showProgress=True, Bool forceDisk=False)

Constructor takes the MaskedLattice only. In the absence of a logger you get no messages. This includes error messages and potential listing of 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.

LatticeHistograms(const LatticeHistograms<T> &other)

Copy constructor (copy semantics)

virtual ~LatticeHistograms ()

Destructor

LatticeHistograms<T> &operator=(const LatticeHistograms<T> &other)

Assignment operator (copy semantics)

Bool setAxes (const Vector<Int>& cursorAxes)

Set the cursor axes (0 relative). A return value of False indicates you have asked for an invalid axis or that the internal status of the class is bad. The default state of the class is to set the cursor axes to all axes in the lattice.

Bool setNBins (const uInt& nBins)

Set the number of bins for the histogram. Note that the bin width is worked out for each histogram separately from the data minimum and maximum. The default state of the class is to set 25 bins. A return value of False indicates you gave a non-positive bin width or that the internal status of the class is bad.

Bool setIncludeRange (const Vector<T>& include)

Specify a pixel intensity range for which all pixels in that range are included. A vector of length 1 for include means that the range will be set to -abs(include(0))<src> to <src>abs(include(0)). A return value of False indicates that the internal status of the class is bad. If you don't call this function, the default state of the class is to include all pixels.

Bool setGaussian (const Bool& doGauss)

Specify that a Gaussian overlay should be plotted on the histogram. This Gaussian has the same mean and standard deviation as the data that were binned, and the same integral as the histogram. A return value of False indicates that the internal status of the class is bad. The default state of the class is to not draw a Gaussian overlay.

Bool setForm (const Bool& doLog, const Bool& doCumu)

Specify the form of the histogram. It can be plotted linearly or logarithmically, and cumulatively or non-cumulatively. A return value of False indicates that the internal status of the class is bad. The default state of the class is to draw the histograms linearly and non-cumulatively.

Bool setStatsList(const Bool& doList)

This function allows you to control whether some statistics of the data that contributed to the histogram are written to the output stream. A return value of False indicates that the internal status of the class is bad. The default state of the class is to not list statistics.

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 page. If you set plotter but offer a zero length array for nxy then nxy is set to [1,1]. A return value of False indicates invalid plotting arguments or that the internal status of the class is bad. If you don't call this function, the default state of the class is to not set a plotting device.

Bool display ()

Display the histograms by plotting them. A return value of False indicates an invalid plotting device, or that the internal status of the class is bad. If you don't call this function you won't see any histograms.

void closePlotting()

CLose the plotter

Vector<Int> displayAxes() const

Return the display axes

Bool getHistograms (Array<T>& values, Array<T>& counts)

This function retrieves the histograms into Array. The shape of the first dimension of this array is the number of bins. The rest of 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 histograms of the y axis the shape of the returned array would be [nbins,nx,nz]. The histograms are retrieved in the form specified by the setForm function. The arrays are resized internally. A return value of False indicates that the internal status of the class is bad.

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. The histogram is retrieved in the form specified by the setForm function. The vectors are resized internally. 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. A return value of False indicates that the internal status of the class is bad.

void resetError ()

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.

String errorMessage() const

Recover last error message

Bool setNewLattice (const MaskedLattice<T>& lattice)

Set a MaskedLattice. A return value of False indicates the lattice had an invalid type or that the internal status of the class is bad.

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 (the first one) relative to the parent or current lattice

static Float convertT (const T value)

Convert a to a for plotting

static T convertF (const Float value)

Convert a (from plotting) to a

Bool displayHistograms ()

Display histograms as a function of display axis

Bool displayOneHistogram (const T&linearSum, const T&linearYMax, const IPosition& histPos, const IPosition<T> &stats, const IPosition<T>& values, const IPosition<T>& counts, Vector& plotter)

Display one histogram

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 generateStorageLattice()

Iterate through the lattice and generate the histogram accumulation lattice

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, or the histogram storage lattice

void listStatistics(LogIO& os, const Vector<T>& stats, T binWidth)

List statistics

void makeHistograms()

Fill histograms storage lattice

Bool makeStatistics()

Create and fill statistics object

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

virtual String writeCoordinates(const IPosition& histPos) const

Make a string with pixel coordinates of display axes. This function is over-ridden by ImageHistograms which inherits from LatticeHistograms.

Bool writeDispAxesValues (const String& coords, PGPlotter& plotter, Float nchar) const

Write values of display axes on plots


class HistTiledCollapser : public TiledCollapser<T,T>

Interface

Public Members
HistTiledCollapser(LatticeStatistics<T>* pStats, uInt nBins)
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<T>& result, Array<Bool>& resultMask, const IPosition& shape)
virtual Bool canHandleNullMask() const

Description

Review Status

Date Reviewed:
yyyy/mm/dd

Prerequisite

Etymology

This class is used by LatticeHistograms to generate histograms from an input MaskedLattice. The input lattice is iterated through in tile-sized chunks and fed to an object of this class.

Synopsis

HistTiledCollapser 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. LatticeHistograms uses a HistTiledCollapser object which it gives to LatticeApply::tiledApply for digestion. After it has done its work, LatticeHistograms then accesses the output Lattice that it made.

Example

    // Created collapser. Control information is passed in via the constructor.
    
      HistTiledCollapser<T> collapser(pStats, nBins_p);
    
    // This is the first output axis getting  collapsed values. In LatticeHistograms
    // this is the first axis of the output lattice
    
      Int newOutAxis = 0;
    
    // 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

HistTiledCollapser(LatticeStatistics<T>* pStats, uInt nBins)

Constructor

virtual void init (uInt nOutPixelsPerCollapse)

Initialize process, making some checks

virtual void initAccumulator (uInt n1, uInt n3)

Initialize the accumulator

virtual void process (uInt accumIndex1, uInt accumIndex3, const T* inData, const Bool* inMask, uInt inIncr, uInt nrval, const IPosition& startPos, const IPosition& shape)

Process the data in the current chunk.

virtual void endAccumulator(Array<T>& result, Array<Bool>& resultMask, const IPosition& shape)

End the accumulation process and return the result arrays

virtual Bool canHandleNullMask() const

Can handle null mask