edu.uci.ics.jung.statistics
Class Histogram

java.lang.Object
  edu.uci.ics.jung.statistics.Histogram

public class Histogram

extends java.lang.Object

General-purpose class for representing experimental distributions via a histogram. A histogram is primarily characterized by three things:
1) the minimum value in the data, minX
2) the bin width, w
3) the number of bins, n
* The ith bin represents the interval [minX + (i-1)w, minX + i*w]. Each bin contains the number of times a value in the original data set falls within its corresponding interval

Author:

Didier H. Besset (modified by Scott White)

Constructor Summary

Histogram()
Constructor method with unknown limits and a desired number of 50 bins.

Histogram(double from, double to)
Constructor method for approximate range for a desired number of 50 bins.

Histogram(double from, double to, int bins)
Constructor method for approximate range and desired number of bins.

Histogram(int n)
Constructor method with unknown limits and a desired number of 50 bins.

Histogram(int n, double min, double width)
General constructor method.

Histogram(int n, int m)
Constructor method with unknown limits.

Method Summary

double	average() Returns the average of the values accumulated in the histogram bins.
double	binHeight(double x) retrieves the bin given a random value and returns the corresponding height of the bin
int	binIndex(double x)
long	count() Returns the number of accumulated counts.
double	errorOnAverage() Returns the error on average.
void	fill(double x) Fills with a random variable.
void	fill(cern.colt.list.DoubleArrayList list) Fills the histogram with the list of random values
double[]	getBinParameters(double x) Returns the low and high limits and the content of the bin containing the specified number or nul if the specified number lies outside of the histogram limits.
double	getBinWidth() Returns the bin width.
double	getCountsBetween(double x, double y)
double	getCountsUpTo(double x)
double	getDimension() Deprecated. use getNumBins
double	getMaximum()
double	getMinimum() Returns the lower bin limit of the first bin.
int	getNumBins()
double[]	getRange() Returns the range of values to be plotted.
double	kurtosis() Returns the kurtosis of the values accumulated in the histogram bins.
long	overflow() Returns the number of counts accumulated below the lowest bin.
void	reset() Reset histogram.
void	setGrowthAllowed() Allows histogram contents to grow in order to contain all accumulated values.
void	setIntegerBinWidth() Forces the bin width of the histogram to be integer.
int	size() Returns the number of points in the series.
double	skewness() Returns the skewness of the values accumulated in the histogram bins.
double	standardDeviation() Returns the standard deviation of the values accumulated in the histogram bins.
long	totalCount()
long	underflow() Returns the number of counts accumulated below the lowest bin.
double	variance() Returns the variance of the values accumulated in the histogram bins.
double	xValueAt(int index) Returns the end of the bin at the specified index.
double	yValueAt(int index) Returns the content of the bin at the given index.

Methods inherited from class java.lang.Object

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

Constructor Detail

Histogram

public Histogram()

Constructor method with unknown limits and a desired number of 50 bins. The first 100 accumulated values are cached. Then, a suitable range is computed.

Histogram

public Histogram(double from,
                 double to)

Constructor method for approximate range for a desired number of 50 bins. All parameters are adjusted so that the bin width is a round number.

Parameters:

from - approximate lower limit of first histogram bin.

to - approximate upper limit of last histogram bin.

Histogram

public Histogram(double from,
                 double to,
                 int bins)

Constructor method for approximate range and desired number of bins. All parameters are adjusted so that the bin width is a round number.

Parameters:

from - approximate lower limit of first histogram bin.

to - approximate upper limit of last histogram bin.

bins - desired number of bins.

Histogram

public Histogram(int n)

Constructor method with unknown limits and a desired number of 50 bins. Accumulated values are first cached. When the cache is full, a suitable range is computed.

Parameters:

n - size of cache.

Histogram

public Histogram(int n,
                 double min,
                 double width)
          throws java.lang.IllegalArgumentException

General constructor method.

Parameters:

n - number of bins.

min - lower limit of first histogram bin.

width - bin width (must be positive).

Throws:

java.lang.IllegalArgumentException - if the number of bins is non-positive, if the limits are inversed.

Histogram

public Histogram(int n,
                 int m)

Constructor method with unknown limits. Accumulated values are first cached. When the cache is full, a suitable range is computed.

Parameters:

n - size of cache.

m - desired number of bins

Method Detail

fill

public void fill(cern.colt.list.DoubleArrayList list)

Fills the histogram with the list of random values

Parameters:

list - a list of double values

fill

public void fill(double x)

Fills with a random variable.

Parameters:

x - value of the random variable.

average

public double average()

Returns the average of the values accumulated in the histogram bins.

Returns:

average.

binIndex

public int binIndex(double x)

Parameters:

x - double

Returns:

int index of the bin where x is located

count

public long count()

Returns the number of accumulated counts.

Returns:

number of counts.

errorOnAverage

public double errorOnAverage()

Returns the error on average. May throw divide by zero exception.

Returns:

error on average.

binHeight

public double binHeight(double x)

retrieves the bin given a random value and returns the corresponding height of the bin

Parameters:

x - the random value

Returns:

total height of the corresponding bin

getBinParameters

public double[] getBinParameters(double x)

Returns the low and high limits and the content of the bin containing the specified number or nul if the specified number lies outside of the histogram limits.

Returns:

a 3-dimensional array containing the bin limits and the bin content.

getBinWidth

public double getBinWidth()

Returns the bin width.

Returns:

bin width.

getCountsBetween

public double getCountsBetween(double x,
                               double y)

Parameters:

x - double

y - double

Returns:

double

getCountsUpTo

public double getCountsUpTo(double x)

Parameters:

x - double

Returns:

double integrated count up to x

getDimension

public double getDimension()

Deprecated. use getNumBins

Returns the number of bins of the histogram.

Returns:

number of bins.

getNumBins

public int getNumBins()

getMaximum

public double getMaximum()

Returns:

double

getMinimum

public double getMinimum()

Returns the lower bin limit of the first bin.

Returns:

minimum histogram range.

getRange

public double[] getRange()

Returns the range of values to be plotted.

Returns:

An array of 4 double values as follows index 0: minimum of X range 1: maximum of X range 2: minimum of Y range 3: maximum of Y range

kurtosis

public double kurtosis()

Returns the kurtosis of the values accumulated in the histogram bins. The kurtosis measures the sharpness of the distribution near the maximum. Note: The kurtosis of the Normal distribution is 0 by definition.

Returns:

double kurtosis.

overflow

public long overflow()

Returns the number of counts accumulated below the lowest bin.

Returns:

overflow.

reset

public void reset()

Reset histogram.

setGrowthAllowed

public void setGrowthAllowed()
                      throws java.lang.RuntimeException

Allows histogram contents to grow in order to contain all accumulated values. Note: Should not be called after counts have been accumulated in the underflow and/or overflow of the histogram.

Throws:

java.lang.RuntimeException - if the histogram has some contents.

setIntegerBinWidth

public void setIntegerBinWidth()
                        throws java.lang.RuntimeException

Forces the bin width of the histogram to be integer. Note: Can only be called when the histogram is cached.

Throws:

java.lang.RuntimeException - if the histogram has some contents.

size

public int size()

Returns the number of points in the series.

skewness

public double skewness()

Returns the skewness of the values accumulated in the histogram bins.

Returns:

double skewness.

standardDeviation

public double standardDeviation()

Returns the standard deviation of the values accumulated in the histogram bins.

Returns:

double standard deviation.

totalCount

public long totalCount()

Returns:

long

underflow

public long underflow()

Returns the number of counts accumulated below the lowest bin.

Returns:

underflow.

variance

public double variance()

Returns the variance of the values accumulated in the histogram bins.

Returns:

double variance.

xValueAt

public double xValueAt(int index)

Returns the end of the bin at the specified index.

Parameters:

index - the index of the bin.

Returns:

middle of bin

yValueAt

public double yValueAt(int index)

Returns the content of the bin at the given index.

Parameters:

index - the index of the bin.

Returns:

bin content