edu.uci.ics.jung.statistics
Class Histogram

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

public class Histogram
extends 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(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.
protected  StatisticalMoments moments()
           
 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
clone, equals, finalize, 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 IllegalArgumentException
General constructor method.

Parameters:
n - number of bins.
min - lower limit of first histogram bin.
width - bin width (must be positive).
Throws:
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(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.

moments

protected StatisticalMoments moments()
Returns:
FixedStatisticalMoments

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 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:
RuntimeException - if the histogram has some contents.

setIntegerBinWidth

public void setIntegerBinWidth()
                        throws RuntimeException
Forces the bin width of the histogram to be integer. Note: Can only be called when the histogram is cached.

Throws:
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