Package pamMaths

Class PamHistogram

java.lang.Object

java.util.Observable

PamUtils.TimedObservable

pamMaths.PamHistogram

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

CalibrationHistogram, PamLogHistogram, TriggerHistogram

public class PamHistogram
extends TimedObservable
implements Cloneable

class for collecting data into a 1-D histogram.

As well as basic histogramming functions, functions exist for downscaling the histogram data and extracting parameters such as variance, skew, etc.

Author:

Doug Gillespie

Constructor Summary

Constructors

Constructor	Description
PamHistogram(double minVal, double maxVal, int nBins)	Constructs a histogram object with minVal and maxVal, specifying the low edge of the lowest bin and the high edge of the highest bin respectively.
PamHistogram(double minVal, double maxVal, int nBins, boolean binCentres)	Constructs a histogram object where minVal and maxVal specify the centres of the lower and upper bins (true) or the lower edge of the lowest bin and the upper edge of the highest bin (false)

Method Summary

Modifier and Type	Method	Description
void	addData(double newData)	Add a single point of data to the histogram but don't notify observers
void	addData(double newData, boolean notify)	Add a single unit value to the histogram and optionally notify all observers
void	addData(double newData, double weight)	Add weighted data to the histogram
void	clear()	Clear all histogram contents
int	getBin(double dataValue)	Work out which bin a particular value will call into.
double	getBinCentre(int iBin)
double[]	getBinCentreValues()	Get the centre value of every bin
double[]	getBinEdgeValues()	Get an array of bin edges.
double[]	getData()	Get the histograms data array.
double	getHiBin()	Get content of high bin - values > max range of histogram
double	getKurtosis()	Get the kurtosis of the distribution (fourth moment) taking the definition from Numerical recipes in C p 612
double	getLoBin()	Get content of low bin - values invalid input: '<' min range of histogram
double	getMaxContent()	Get max bin content, including lo and high fields.
double	getMaxVal()	Get the maximum range value of the histogram
double	getMean()	Calculate the mean of the histogram data
double	getMinVal()	Get the minimum range value of the histogram
double	getMode()	Get's the modal value of the distribution
String	getName()
int	getNBins()	Get the number of histogram bins
double	getScaleMaxVal()	Where to plot to if bin centres were specified.
double	getScaleMinVal()	Where to plot from if bin centres were specified.
double	getSkew()	Get the skewness of the distribution (third moment)
double	getSTD()	Return the standard deviation of the histogram data
double	getStep()	Step size between sucessive bins.
double	getTotalContent()	Get's the sum total of all bin contents, excluding lo and high bins
double	getVariance()	Return the variance of the histogram data
boolean	isBinCentres()
void	printSummary()
void	printSummary(String title, PrintStream printStream)
void	scaleData(double scaleFactor)	Scale the data in the histogram by the given factor
void	setBinCentres(boolean binCentres)
void	setData(int[] data)	Set the histogram data
void	setName(String name)
void	setRange(double minVal, double maxVal, int nBins)	Sets the histogram bin ranges.
String	toString()

Methods inherited from class PamUtils.TimedObservable

getDelay, notifyObservers, notifyObservers, notifyObservers, setDelay

Methods inherited from class java.util.Observable

addObserver, countObservers, deleteObserver, deleteObservers, hasChanged

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

PamHistogram

public PamHistogram(double minVal,
 double maxVal,
 int nBins)

Constructs a histogram object with minVal and maxVal, specifying the low edge of the lowest bin and the high edge of the highest bin respectively.

Parameters:

minVal - min Value

maxVal - max Value

nBins - number of bins

PamHistogram

public PamHistogram(double minVal,
 double maxVal,
 int nBins,
 boolean binCentres)

Constructs a histogram object where minVal and maxVal specify the centres of the lower and upper bins (true) or the lower edge of the lowest bin and the upper edge of the highest bin (false)

Parameters:

minVal - minimum value (low edge or low bin centre, depending on binCentres parameter)

maxVal - maximum value (high edge or high bin centre, depending on binCentres parameter)

nBins - total number of bins

binCentres - specifies whether the minVal and maxVal specify the centres of the lower and upper bins (true) or the lower edge of the lowest bin and the upper edge of the highest bin (false)

Method Details

setRange

public void setRange(double minVal,
 double maxVal,
 int nBins)

Sets the histogram bin ranges.

Note that calling this function will reset the histogram data.

Parameters:

minVal - minimum value (low edge or low bin centre, depending on binCentres parameter)

maxVal - maximum value (high edge or high bin centre, depending on binCentres parameter)

nBins - total number of bins

getBin

public int getBin(double dataValue)

Work out which bin a particular value will call into. N.B. This may return invalid input: '<' 0 or >= getNBins() if the data fall outsied the range of the histogram

Parameters:

dataValue -

Returns:

bin Bumber

getBinCentre

public double getBinCentre(int iBin)

setData

public void setData(int[] data)

Set the histogram data

Parameters:

data - array must be same length as data array in histogram.

addData

public void addData(double newData,
 boolean notify)

Add a single unit value to the histogram and optionally notify all observers

Parameters:

newData - value of the new data

addData

public void addData(double newData)

Add a single point of data to the histogram but don't notify observers

Parameters:

newData - new data point

addData

public void addData(double newData,
 double weight)

Add weighted data to the histogram

Parameters:

newData - value of the data

weight - weight to apply

clear

public void clear()

Clear all histogram contents

scaleData

public void scaleData(double scaleFactor)

Scale the data in the histogram by the given factor

This is used in various parts of PAMGUARD which wish to keep a decaying average distribution - every few seconds the data are halved (or some such) so that all data are represented, but recent data will carry more weight in the distributions.

Parameters:

scaleFactor - FActor to scale data by (generally invalid input: '<' 1)

getMaxContent

public double getMaxContent()

Get max bin content, including lo and high fields.

Returns:

max bin content.

getMean

public double getMean()

Calculate the mean of the histogram data

Returns:

mean value

getSTD

public double getSTD()

Return the standard deviation of the histogram data

Returns:

standard deviation

getVariance

public double getVariance()

Return the variance of the histogram data

Returns:

get variance of distribution in histogram

getSkew

public double getSkew()

Get the skewness of the distribution (third moment)

Returns:

skew

getKurtosis

public double getKurtosis()

Get the kurtosis of the distribution (fourth moment) taking the definition from Numerical recipes in C p 612

Returns:

kurtosis

getMode

public double getMode()

Get's the modal value of the distribution

Returns:

value of the bin centre for the most populated bin

getTotalContent

public double getTotalContent()

Get's the sum total of all bin contents, excluding lo and high bins

Returns:

get total content of all histogram bins

getData

public double[] getData()

Get the histograms data array.

Returns:

An array of double data

getMaxVal

public double getMaxVal()

Get the maximum range value of the histogram

Returns:

max value

getMinVal

public double getMinVal()

Get the minimum range value of the histogram

Returns:

min value

getScaleMinVal

public double getScaleMinVal()

Where to plot from if bin centres were specified.

Returns:

minimum value for plot axis

getScaleMaxVal

public double getScaleMaxVal()

Where to plot to if bin centres were specified.

Returns:

maximum value for plot axis

getNBins

public int getNBins()

Get the number of histogram bins

Returns:

number of histogram bins

getStep

public double getStep()

Step size between sucessive bins.

Returns:

histogram step size (bin width)

getName

public String getName()

setName

public void setName(String name)

toString

public String toString()

Overrides:

toString in class Object

getHiBin

public double getHiBin()

Get content of high bin - values > max range of histogram

Returns:

high bin content

getLoBin

public double getLoBin()

Get content of low bin - values invalid input: '<' min range of histogram

Returns:

low bin content

isBinCentres

public boolean isBinCentres()

setBinCentres

public void setBinCentres(boolean binCentres)

getBinCentreValues

public double[] getBinCentreValues()

Get the centre value of every bin

Returns:

array of bin centres.

getBinEdgeValues

public double[] getBinEdgeValues()

Get an array of bin edges. This will be one longer than the number of bins

Returns:

array of bin edge values.

printSummary

public void printSummary()

printSummary

public void printSummary(String title,
 PrintStream printStream)