org.apache.commons.math3.stat.descriptive
Class SummaryStatistics

java.lang.Object
  extended by org.apache.commons.math3.stat.descriptive.SummaryStatistics
All Implemented Interfaces:
Serializable, StatisticalSummary
Direct Known Subclasses:
SynchronizedSummaryStatistics

public class SummaryStatistics
extends Object
implements StatisticalSummary, Serializable

Computes summary statistics for a stream of data values added using the addValue method. The data values are not stored in memory, so this class can be used to compute statistics for very large data streams.

The StorelessUnivariateStatistic instances used to maintain summary state and compute statistics are configurable via setters. For example, the default implementation for the variance can be overridden by calling setVarianceImpl(StorelessUnivariateStatistic). Actual parameters to these methods must implement the StorelessUnivariateStatistic interface and configuration must be completed before addValue is called. No configuration is necessary to use the default, commons-math provided implementations.

Note: This class is not thread-safe. Use SynchronizedSummaryStatistics if concurrent access from multiple threads is required.

Version:
$Id: SummaryStatistics.java 1416643 2012-12-03 19:37:14Z tn $
See Also:
Serialized Form

Constructor Summary
SummaryStatistics()
          Construct a SummaryStatistics instance
SummaryStatistics(SummaryStatistics original)
          A copy constructor.
 
Method Summary
 void addValue(double value)
          Add a value to the data
 void clear()
          Resets all statistics and storage
 SummaryStatistics copy()
          Returns a copy of this SummaryStatistics instance with the same internal state.
static void copy(SummaryStatistics source, SummaryStatistics dest)
          Copies source to dest.
 boolean equals(Object object)
          Returns true iff object is a SummaryStatistics instance and all statistics have the same values as this.
 StorelessUnivariateStatistic getGeoMeanImpl()
          Returns the currently configured geometric mean implementation
 double getGeometricMean()
          Returns the geometric mean of the values that have been added.
 double getMax()
          Returns the maximum of the values that have been added.
 StorelessUnivariateStatistic getMaxImpl()
          Returns the currently configured maximum implementation
 double getMean()
          Returns the mean of the values that have been added.
 StorelessUnivariateStatistic getMeanImpl()
          Returns the currently configured mean implementation
 double getMin()
          Returns the minimum of the values that have been added.
 StorelessUnivariateStatistic getMinImpl()
          Returns the currently configured minimum implementation
 long getN()
          Returns the number of available values
 double getPopulationVariance()
          Returns the population variance of the values that have been added.
 double getSecondMoment()
          Returns a statistic related to the Second Central Moment.
 double getStandardDeviation()
          Returns the standard deviation of the values that have been added.
 double getSum()
          Returns the sum of the values that have been added
 StorelessUnivariateStatistic getSumImpl()
          Returns the currently configured Sum implementation
 StorelessUnivariateStatistic getSumLogImpl()
          Returns the currently configured sum of logs implementation
 StatisticalSummary getSummary()
          Return a StatisticalSummaryValues instance reporting current statistics.
 double getSumOfLogs()
          Returns the sum of the logs of the values that have been added.
 double getSumsq()
          Returns the sum of the squares of the values that have been added.
 StorelessUnivariateStatistic getSumsqImpl()
          Returns the currently configured sum of squares implementation
 double getVariance()
          Returns the (sample) variance of the available values.
 StorelessUnivariateStatistic getVarianceImpl()
          Returns the currently configured variance implementation
 int hashCode()
          Returns hash code based on values of statistics
 void setGeoMeanImpl(StorelessUnivariateStatistic geoMeanImpl)
           Sets the implementation for the geometric mean.
 void setMaxImpl(StorelessUnivariateStatistic maxImpl)
           Sets the implementation for the maximum.
 void setMeanImpl(StorelessUnivariateStatistic meanImpl)
           Sets the implementation for the mean.
 void setMinImpl(StorelessUnivariateStatistic minImpl)
           Sets the implementation for the minimum.
 void setSumImpl(StorelessUnivariateStatistic sumImpl)
           Sets the implementation for the Sum.
 void setSumLogImpl(StorelessUnivariateStatistic sumLogImpl)
           Sets the implementation for the sum of logs.
 void setSumsqImpl(StorelessUnivariateStatistic sumsqImpl)
           Sets the implementation for the sum of squares.
 void setVarianceImpl(StorelessUnivariateStatistic varianceImpl)
           Sets the implementation for the variance.
 String toString()
          Generates a text report displaying summary statistics from values that have been added.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SummaryStatistics

public SummaryStatistics()
Construct a SummaryStatistics instance


SummaryStatistics

public SummaryStatistics(SummaryStatistics original)
                  throws NullArgumentException
A copy constructor. Creates a deep-copy of the original.

Parameters:
original - the SummaryStatistics instance to copy
Throws:
NullArgumentException - if original is null
Method Detail

getSummary

public StatisticalSummary getSummary()
Return a StatisticalSummaryValues instance reporting current statistics.

Returns:
Current values of statistics

addValue

public void addValue(double value)
Add a value to the data

Parameters:
value - the value to add

getN

public long getN()
Returns the number of available values

Specified by:
getN in interface StatisticalSummary
Returns:
The number of available values

getSum

public double getSum()
Returns the sum of the values that have been added

Specified by:
getSum in interface StatisticalSummary
Returns:
The sum or Double.NaN if no values have been added

getSumsq

public double getSumsq()
Returns the sum of the squares of the values that have been added.

Double.NaN is returned if no values have been added.

Returns:
The sum of squares

getMean

public double getMean()
Returns the mean of the values that have been added.

Double.NaN is returned if no values have been added.

Specified by:
getMean in interface StatisticalSummary
Returns:
the mean

getStandardDeviation

public double getStandardDeviation()
Returns the standard deviation of the values that have been added.

Double.NaN is returned if no values have been added.

Specified by:
getStandardDeviation in interface StatisticalSummary
Returns:
the standard deviation

getVariance

public double getVariance()
Returns the (sample) variance of the available values.

This method returns the bias-corrected sample variance (using n - 1 in the denominator). Use getPopulationVariance() for the non-bias-corrected population variance.

Double.NaN is returned if no values have been added.

Specified by:
getVariance in interface StatisticalSummary
Returns:
the variance

getPopulationVariance

public double getPopulationVariance()
Returns the population variance of the values that have been added.

Double.NaN is returned if no values have been added.

Returns:
the population variance

getMax

public double getMax()
Returns the maximum of the values that have been added.

Double.NaN is returned if no values have been added.

Specified by:
getMax in interface StatisticalSummary
Returns:
the maximum

getMin

public double getMin()
Returns the minimum of the values that have been added.

Double.NaN is returned if no values have been added.

Specified by:
getMin in interface StatisticalSummary
Returns:
the minimum

getGeometricMean

public double getGeometricMean()
Returns the geometric mean of the values that have been added.

Double.NaN is returned if no values have been added.

Returns:
the geometric mean

getSumOfLogs

public double getSumOfLogs()
Returns the sum of the logs of the values that have been added.

Double.NaN is returned if no values have been added.

Returns:
the sum of logs
Since:
1.2

getSecondMoment

public double getSecondMoment()
Returns a statistic related to the Second Central Moment. Specifically, what is returned is the sum of squared deviations from the sample mean among the values that have been added.

Returns Double.NaN if no data values have been added and returns 0 if there is just one value in the data set.

Returns:
second central moment statistic
Since:
2.0

toString

public String toString()
Generates a text report displaying summary statistics from values that have been added.

Overrides:
toString in class Object
Returns:
String with line feeds displaying statistics
Since:
1.2

clear

public void clear()
Resets all statistics and storage


equals

public boolean equals(Object object)
Returns true iff object is a SummaryStatistics instance and all statistics have the same values as this.

Overrides:
equals in class Object
Parameters:
object - the object to test equality against.
Returns:
true if object equals this

hashCode

public int hashCode()
Returns hash code based on values of statistics

Overrides:
hashCode in class Object
Returns:
hash code

getSumImpl

public StorelessUnivariateStatistic getSumImpl()
Returns the currently configured Sum implementation

Returns:
the StorelessUnivariateStatistic implementing the sum
Since:
1.2

setSumImpl

public void setSumImpl(StorelessUnivariateStatistic sumImpl)
                throws MathIllegalStateException

Sets the implementation for the Sum.

This method must be activated before any data has been added - i.e., before addValue has been used to add data; otherwise an IllegalStateException will be thrown.

Parameters:
sumImpl - the StorelessUnivariateStatistic instance to use for computing the Sum
Throws:
MathIllegalStateException - if data has already been added (i.e if n >0)
Since:
1.2

getSumsqImpl

public StorelessUnivariateStatistic getSumsqImpl()
Returns the currently configured sum of squares implementation

Returns:
the StorelessUnivariateStatistic implementing the sum of squares
Since:
1.2

setSumsqImpl

public void setSumsqImpl(StorelessUnivariateStatistic sumsqImpl)
                  throws MathIllegalStateException

Sets the implementation for the sum of squares.

This method must be activated before any data has been added - i.e., before addValue has been used to add data; otherwise an IllegalStateException will be thrown.

Parameters:
sumsqImpl - the StorelessUnivariateStatistic instance to use for computing the sum of squares
Throws:
MathIllegalStateException - if data has already been added (i.e if n > 0)
Since:
1.2

getMinImpl

public StorelessUnivariateStatistic getMinImpl()
Returns the currently configured minimum implementation

Returns:
the StorelessUnivariateStatistic implementing the minimum
Since:
1.2

setMinImpl

public void setMinImpl(StorelessUnivariateStatistic minImpl)
                throws MathIllegalStateException

Sets the implementation for the minimum.

This method must be activated before any data has been added - i.e., before addValue has been used to add data; otherwise an IllegalStateException will be thrown.

Parameters:
minImpl - the StorelessUnivariateStatistic instance to use for computing the minimum
Throws:
MathIllegalStateException - if data has already been added (i.e if n > 0)
Since:
1.2

getMaxImpl

public StorelessUnivariateStatistic getMaxImpl()
Returns the currently configured maximum implementation

Returns:
the StorelessUnivariateStatistic implementing the maximum
Since:
1.2

setMaxImpl

public void setMaxImpl(StorelessUnivariateStatistic maxImpl)
                throws MathIllegalStateException

Sets the implementation for the maximum.

This method must be activated before any data has been added - i.e., before addValue has been used to add data; otherwise an IllegalStateException will be thrown.

Parameters:
maxImpl - the StorelessUnivariateStatistic instance to use for computing the maximum
Throws:
MathIllegalStateException - if data has already been added (i.e if n > 0)
Since:
1.2

getSumLogImpl

public StorelessUnivariateStatistic getSumLogImpl()
Returns the currently configured sum of logs implementation

Returns:
the StorelessUnivariateStatistic implementing the log sum
Since:
1.2

setSumLogImpl

public void setSumLogImpl(StorelessUnivariateStatistic sumLogImpl)
                   throws MathIllegalStateException

Sets the implementation for the sum of logs.

This method must be activated before any data has been added - i.e., before addValue has been used to add data; otherwise an IllegalStateException will be thrown.

Parameters:
sumLogImpl - the StorelessUnivariateStatistic instance to use for computing the log sum
Throws:
MathIllegalStateException - if data has already been added (i.e if n > 0)
Since:
1.2

getGeoMeanImpl

public StorelessUnivariateStatistic getGeoMeanImpl()
Returns the currently configured geometric mean implementation

Returns:
the StorelessUnivariateStatistic implementing the geometric mean
Since:
1.2

setGeoMeanImpl

public void setGeoMeanImpl(StorelessUnivariateStatistic geoMeanImpl)
                    throws MathIllegalStateException

Sets the implementation for the geometric mean.

This method must be activated before any data has been added - i.e., before addValue has been used to add data; otherwise an IllegalStateException will be thrown.

Parameters:
geoMeanImpl - the StorelessUnivariateStatistic instance to use for computing the geometric mean
Throws:
MathIllegalStateException - if data has already been added (i.e if n > 0)
Since:
1.2

getMeanImpl

public StorelessUnivariateStatistic getMeanImpl()
Returns the currently configured mean implementation

Returns:
the StorelessUnivariateStatistic implementing the mean
Since:
1.2

setMeanImpl

public void setMeanImpl(StorelessUnivariateStatistic meanImpl)
                 throws MathIllegalStateException

Sets the implementation for the mean.

This method must be activated before any data has been added - i.e., before addValue has been used to add data; otherwise an IllegalStateException will be thrown.

Parameters:
meanImpl - the StorelessUnivariateStatistic instance to use for computing the mean
Throws:
MathIllegalStateException - if data has already been added (i.e if n > 0)
Since:
1.2

getVarianceImpl

public StorelessUnivariateStatistic getVarianceImpl()
Returns the currently configured variance implementation

Returns:
the StorelessUnivariateStatistic implementing the variance
Since:
1.2

setVarianceImpl

public void setVarianceImpl(StorelessUnivariateStatistic varianceImpl)
                     throws MathIllegalStateException

Sets the implementation for the variance.

This method must be activated before any data has been added - i.e., before addValue has been used to add data; otherwise an IllegalStateException will be thrown.

Parameters:
varianceImpl - the StorelessUnivariateStatistic instance to use for computing the variance
Throws:
MathIllegalStateException - if data has already been added (i.e if n > 0)
Since:
1.2

copy

public SummaryStatistics copy()
Returns a copy of this SummaryStatistics instance with the same internal state.

Returns:
a copy of this

copy

public static void copy(SummaryStatistics source,
                        SummaryStatistics dest)
                 throws NullArgumentException
Copies source to dest.

Neither source nor dest can be null.

Parameters:
source - SummaryStatistics to copy
dest - SummaryStatistics to copy to
Throws:
NullArgumentException - if either source or dest is null


Copyright © 2003-2012 The Apache Software Foundation. All Rights Reserved.