Top Description Fields Constructors Methods
org.apache.commons.math3.stat.descriptive

public Class SummaryStatistics

extends Object
implements StatisticalSummary, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, org.apache.commons.math3.stat.descriptive.StatisticalSummary
Known Direct Subclasses
org.apache.commons.math3.stat.descriptive.SynchronizedSummaryStatistics, org.apache.commons.math3.stat.descriptive.AggregateSummaryStatistics.AggregatingSummaryStatistics
Imports
java.io.Serializable, org.apache.commons.math3.exception.MathIllegalStateException, .NullArgumentException, org.apache.commons.math3.exception.util.LocalizedFormats, org.apache.commons.math3.stat.descriptive.moment.GeometricMean, .Mean, .SecondMoment, .Variance, org.apache.commons.math3.stat.descriptive.rank.Max, .Min, org.apache.commons.math3.stat.descriptive.summary.Sum, .SumOfLogs, .SumOfSquares, org.apache.commons.math3.util.MathUtils, .Precision, .FastMath

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.

Field Summary

Modifier and TypeField and Description
private GeometricMean
geoMean

geoMean of values that have been added

private StorelessUnivariateStatistic
geoMeanImpl

Geometric mean statistic implementation - can be reset by setter.

private Max
max

max of values that have been added

private StorelessUnivariateStatistic
maxImpl

Maximum statistic implementation - can be reset by setter.

private Mean
mean

mean of values that have been added

private StorelessUnivariateStatistic
meanImpl

Mean statistic implementation - can be reset by setter.

private Min
min

min of values that have been added

private StorelessUnivariateStatistic
minImpl

Minimum statistic implementation - can be reset by setter.

private long
n

count of values that have been added

private SecondMoment
secondMoment

SecondMoment is used to compute the mean and variance

private static final long
serialVersionUID

Serialization UID

private Sum
sum

sum of values that have been added

private StorelessUnivariateStatistic
sumImpl

Sum statistic implementation - can be reset by setter.

private SumOfLogs
sumLog

sumLog of values that have been added

private StorelessUnivariateStatistic
sumLogImpl

Sum of log statistic implementation - can be reset by setter.

private SumOfSquares
sumsq

sum of the square of each value that has been added

private StorelessUnivariateStatistic
sumsqImpl

Sum of squares statistic implementation - can be reset by setter.

private Variance
variance

variance of values that have been added

private StorelessUnivariateStatistic
varianceImpl

Variance statistic implementation - can be reset by setter.

Constructor Summary

AccessConstructor and Description
public
SummaryStatistics()

Construct a SummaryStatistics instance

public
SummaryStatistics(SummaryStatistics
the SummaryStatistics instance to copy
original)

A copy constructor.

Method Summary

Modifier and TypeMethod and Description
public void
addValue(double
the value to add
value)

Add a value to the data

private void
checkEmpty()

Throws IllegalStateException if n > 0.

public void
clear()

Resets all statistics and storage

public SummaryStatistics

Returns:

a copy of this
copy()

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

public static void
copy(SummaryStatistics
SummaryStatistics to copy
source, SummaryStatistics
SummaryStatistics to copy to
dest)

Copies source to dest.

public boolean

Returns:

true if object equals this
equals(Object
the object to test equality against.
object)

Overrides java.lang.Object.equals.

Returns true iff object is a SummaryStatistics instance and all statistics have the same values as this.

public StorelessUnivariateStatistic

Returns:

the StorelessUnivariateStatistic implementing the geometric mean
getGeoMeanImpl()

Returns the currently configured geometric mean implementation

public double

Returns:

the geometric mean
getGeometricMean()

Returns the geometric mean of the values that have been added.

public double

Returns:

the maximum
getMax()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getMax.

Returns the maximum of the values that have been added.

public StorelessUnivariateStatistic

Returns:

the StorelessUnivariateStatistic implementing the maximum
getMaxImpl()

Returns the currently configured maximum implementation

public double

Returns:

the mean
getMean()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getMean.

Returns the mean of the values that have been added.

public StorelessUnivariateStatistic

Returns:

the StorelessUnivariateStatistic implementing the mean
getMeanImpl()

Returns the currently configured mean implementation

public double

Returns:

the minimum
getMin()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getMin.

Returns the minimum of the values that have been added.

public StorelessUnivariateStatistic

Returns:

the StorelessUnivariateStatistic implementing the minimum
getMinImpl()

Returns the currently configured minimum implementation

public long

Returns:

The number of available values
getN()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getN.

Returns the number of available values

public double

Returns:

the population variance
getPopulationVariance()

Returns the population variance of the values that have been added.

public double

Returns:

The quadratic mean or Double.NaN if no values have been added.
getQuadraticMean()

Returns the quadratic mean, a.k.a. root-mean-square of the available values

public double

Returns:

second central moment statistic
getSecondMoment()

Returns a statistic related to the Second Central Moment.

public double

Returns:

the standard deviation
getStandardDeviation()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getStandardDeviation.

Returns the standard deviation of the values that have been added.

public double

Returns:

The sum or Double.NaN if no values have been added
getSum()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getSum.

Returns the sum of the values that have been added

public StorelessUnivariateStatistic

Returns:

the StorelessUnivariateStatistic implementing the sum
getSumImpl()

Returns the currently configured Sum implementation

public StorelessUnivariateStatistic

Returns:

the StorelessUnivariateStatistic implementing the log sum
getSumLogImpl()

Returns the currently configured sum of logs implementation

public StatisticalSummary

Returns:

Current values of statistics
getSummary()

Return a StatisticalSummaryValues instance reporting current statistics.

public double

Returns:

the sum of logs
getSumOfLogs()

Returns the sum of the logs of the values that have been added.

public double

Returns:

The sum of squares
getSumsq()

Returns the sum of the squares of the values that have been added.

public StorelessUnivariateStatistic

Returns:

the StorelessUnivariateStatistic implementing the sum of squares
getSumsqImpl()

Returns the currently configured sum of squares implementation

public double

Returns:

the variance
getVariance()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getVariance.

Returns the (sample) variance of the available values.

public StorelessUnivariateStatistic

Returns:

the StorelessUnivariateStatistic implementing the variance
getVarianceImpl()

Returns the currently configured variance implementation

public int

Returns:

hash code
hashCode()

Overrides java.lang.Object.hashCode.

Returns hash code based on values of statistics

public void
setGeoMeanImpl(StorelessUnivariateStatistic
the StorelessUnivariateStatistic instance to use for computing the geometric mean
geoMeanImpl)

Sets the implementation for the geometric mean.

public void
setMaxImpl(StorelessUnivariateStatistic
the StorelessUnivariateStatistic instance to use for computing the maximum
maxImpl)

Sets the implementation for the maximum.

public void
setMeanImpl(StorelessUnivariateStatistic
the StorelessUnivariateStatistic instance to use for computing the mean
meanImpl)

Sets the implementation for the mean.

public void
setMinImpl(StorelessUnivariateStatistic
the StorelessUnivariateStatistic instance to use for computing the minimum
minImpl)

Sets the implementation for the minimum.

public void
setSumImpl(StorelessUnivariateStatistic
the StorelessUnivariateStatistic instance to use for computing the Sum
sumImpl)

Sets the implementation for the Sum.

public void
setSumLogImpl(StorelessUnivariateStatistic
the StorelessUnivariateStatistic instance to use for computing the log sum
sumLogImpl)

Sets the implementation for the sum of logs.

public void
setSumsqImpl(StorelessUnivariateStatistic
the StorelessUnivariateStatistic instance to use for computing the sum of squares
sumsqImpl)

Sets the implementation for the sum of squares.

public void
setVarianceImpl(StorelessUnivariateStatistic
the StorelessUnivariateStatistic instance to use for computing the variance
varianceImpl)

Sets the implementation for the variance.

public String

Returns:

String with line feeds displaying statistics
toString()

Overrides java.lang.Object.toString.

Generates a text report displaying summary statistics from values that have been added.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

geoMeanback to summary
private GeometricMean geoMean

geoMean of values that have been added

geoMeanImplback to summary
private StorelessUnivariateStatistic geoMeanImpl

Geometric mean statistic implementation - can be reset by setter.

maxback to summary
private Max max

max of values that have been added

maxImplback to summary
private StorelessUnivariateStatistic maxImpl

Maximum statistic implementation - can be reset by setter.

meanback to summary
private Mean mean

mean of values that have been added

meanImplback to summary
private StorelessUnivariateStatistic meanImpl

Mean statistic implementation - can be reset by setter.

minback to summary
private Min min

min of values that have been added

minImplback to summary
private StorelessUnivariateStatistic minImpl

Minimum statistic implementation - can be reset by setter.

nback to summary
private long n

count of values that have been added

secondMomentback to summary
private SecondMoment secondMoment

SecondMoment is used to compute the mean and variance

serialVersionUIDback to summary
private static final long serialVersionUID

Serialization UID

sumback to summary
private Sum sum

sum of values that have been added

sumImplback to summary
private StorelessUnivariateStatistic sumImpl

Sum statistic implementation - can be reset by setter.

sumLogback to summary
private SumOfLogs sumLog

sumLog of values that have been added

sumLogImplback to summary
private StorelessUnivariateStatistic sumLogImpl

Sum of log statistic implementation - can be reset by setter.

sumsqback to summary
private SumOfSquares sumsq

sum of the square of each value that has been added

sumsqImplback to summary
private StorelessUnivariateStatistic sumsqImpl

Sum of squares statistic implementation - can be reset by setter.

varianceback to summary
private Variance variance

variance of values that have been added

varianceImplback to summary
private StorelessUnivariateStatistic varianceImpl

Variance statistic implementation - can be reset by setter.

Constructor Detail

SummaryStatisticsback to summary
public SummaryStatistics()

Construct a SummaryStatistics instance

SummaryStatisticsback to summary
public SummaryStatistics(SummaryStatistics original) throws NullArgumentException

A copy constructor. Creates a deep-copy of the original.

Parameters
original:SummaryStatistics

the SummaryStatistics instance to copy

Exceptions
NullArgumentException:
if original is null

Method Detail

addValueback to summary
public void addValue(double value)

Add a value to the data

Parameters
value:double

the value to add

checkEmptyback to summary
private void checkEmpty() throws MathIllegalStateException

Throws IllegalStateException if n > 0.

Exceptions
MathIllegalStateException:
if data has been added
clearback to summary
public void clear()

Resets all statistics and storage

copyback to summary
public SummaryStatistics copy()

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

Returns:SummaryStatistics

a copy of this

copyback to summary
public static void copy(SummaryStatistics source, SummaryStatistics dest) throws NullArgumentException

Copies source to dest.

Neither source nor dest can be null.

Parameters
source:SummaryStatistics

SummaryStatistics to copy

dest:SummaryStatistics

SummaryStatistics to copy to

Exceptions
NullArgumentException:
if either source or dest is null
equalsback to summary
public boolean equals(Object object)

Overrides java.lang.Object.equals.

Returns true iff object is a SummaryStatistics instance and all statistics have the same values as this.

Parameters
object:Object

the object to test equality against.

Returns:boolean

true if object equals this

Annotations
@Override
getGeoMeanImplback to summary
public StorelessUnivariateStatistic getGeoMeanImpl()

Returns the currently configured geometric mean implementation

Returns:StorelessUnivariateStatistic

the StorelessUnivariateStatistic implementing the geometric mean

Since
1.2
getGeometricMeanback to summary
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:double

the geometric mean

getMaxback to summary
public double getMax()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getMax.

Returns the maximum of the values that have been added.

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

Returns:double

the maximum

getMaxImplback to summary
public StorelessUnivariateStatistic getMaxImpl()

Returns the currently configured maximum implementation

Returns:StorelessUnivariateStatistic

the StorelessUnivariateStatistic implementing the maximum

Since
1.2
getMeanback to summary
public double getMean()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getMean.

Returns the mean of the values that have been added.

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

Returns:double

the mean

getMeanImplback to summary
public StorelessUnivariateStatistic getMeanImpl()

Returns the currently configured mean implementation

Returns:StorelessUnivariateStatistic

the StorelessUnivariateStatistic implementing the mean

Since
1.2
getMinback to summary
public double getMin()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getMin.

Returns the minimum of the values that have been added.

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

Returns:double

the minimum

getMinImplback to summary
public StorelessUnivariateStatistic getMinImpl()

Returns the currently configured minimum implementation

Returns:StorelessUnivariateStatistic

the StorelessUnivariateStatistic implementing the minimum

Since
1.2
getNback to summary
public long getN()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getN.

Returns the number of available values

Returns:long

The number of available values

getPopulationVarianceback to summary
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:double

the population variance

getQuadraticMeanback to summary
public double getQuadraticMean()

Returns the quadratic mean, a.k.a. root-mean-square of the available values

Returns:double

The quadratic mean or Double.NaN if no values have been added.

getSecondMomentback to summary
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:double

second central moment statistic

Since
2.0
getStandardDeviationback to summary
public double getStandardDeviation()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getStandardDeviation.

Returns the standard deviation of the values that have been added.

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

Returns:double

the standard deviation

getSumback to summary
public double getSum()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.getSum.

Returns the sum of the values that have been added

Returns:double

The sum or Double.NaN if no values have been added

getSumImplback to summary
public StorelessUnivariateStatistic getSumImpl()

Returns the currently configured Sum implementation

Returns:StorelessUnivariateStatistic

the StorelessUnivariateStatistic implementing the sum

Since
1.2
getSumLogImplback to summary
public StorelessUnivariateStatistic getSumLogImpl()

Returns the currently configured sum of logs implementation

Returns:StorelessUnivariateStatistic

the StorelessUnivariateStatistic implementing the log sum

Since
1.2
getSummaryback to summary
public StatisticalSummary getSummary()

Return a StatisticalSummaryValues instance reporting current statistics.

Returns:StatisticalSummary

Current values of statistics

getSumOfLogsback to summary
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:double

the sum of logs

Since
1.2
getSumsqback to summary
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:double

The sum of squares

getSumsqImplback to summary
public StorelessUnivariateStatistic getSumsqImpl()

Returns the currently configured sum of squares implementation

Returns:StorelessUnivariateStatistic

the StorelessUnivariateStatistic implementing the sum of squares

Since
1.2
getVarianceback to summary
public double getVariance()

Implements org.apache.commons.math3.stat.descriptive.StatisticalSummary.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.

Returns:double

the variance

getVarianceImplback to summary
public StorelessUnivariateStatistic getVarianceImpl()

Returns the currently configured variance implementation

Returns:StorelessUnivariateStatistic

the StorelessUnivariateStatistic implementing the variance

Since
1.2
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Returns hash code based on values of statistics

Returns:int

hash code

Annotations
@Override
setGeoMeanImplback to summary
public void setGeoMeanImpl(StorelessUnivariateStatistic geoMeanImpl) throws MathIllegalStateException

Sets the implementation for the geometric mean.

This method cannot be activated after data has been added - i.e., after addValue has been used to add data. If it is activated after data has been added, an IllegalStateException will be thrown.

Parameters
geoMeanImpl:StorelessUnivariateStatistic

the StorelessUnivariateStatistic instance to use for computing the geometric mean

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
Since
1.2
setMaxImplback to summary
public void setMaxImpl(StorelessUnivariateStatistic maxImpl) throws MathIllegalStateException

Sets the implementation for the maximum.

This method cannot be activated after data has been added - i.e., after addValue has been used to add data. If it is activated after data has been added, an IllegalStateException will be thrown.

Parameters
maxImpl:StorelessUnivariateStatistic

the StorelessUnivariateStatistic instance to use for computing the maximum

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
Since
1.2
setMeanImplback to summary
public void setMeanImpl(StorelessUnivariateStatistic meanImpl) throws MathIllegalStateException

Sets the implementation for the mean.

This method cannot be activated after data has been added - i.e., after addValue has been used to add data. If it is activated after data has been added, an IllegalStateException will be thrown.

Parameters
meanImpl:StorelessUnivariateStatistic

the StorelessUnivariateStatistic instance to use for computing the mean

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
Since
1.2
setMinImplback to summary
public void setMinImpl(StorelessUnivariateStatistic minImpl) throws MathIllegalStateException

Sets the implementation for the minimum.

This method cannot be activated after data has been added - i.e., after addValue has been used to add data. If it is activated after data has been added, an IllegalStateException will be thrown.

Parameters
minImpl:StorelessUnivariateStatistic

the StorelessUnivariateStatistic instance to use for computing the minimum

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
Since
1.2
setSumImplback to summary
public void setSumImpl(StorelessUnivariateStatistic sumImpl) throws MathIllegalStateException

Sets the implementation for the Sum.

This method cannot be activated after data has been added - i.e., after addValue has been used to add data. If it is activated after data has been added, an IllegalStateException will be thrown.

Parameters
sumImpl:StorelessUnivariateStatistic

the StorelessUnivariateStatistic instance to use for computing the Sum

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n >0)
Since
1.2
setSumLogImplback to summary
public void setSumLogImpl(StorelessUnivariateStatistic sumLogImpl) throws MathIllegalStateException

Sets the implementation for the sum of logs.

This method cannot be activated after data has been added - i.e., after addValue has been used to add data. If it is activated after data has been added, an IllegalStateException will be thrown.

Parameters
sumLogImpl:StorelessUnivariateStatistic

the StorelessUnivariateStatistic instance to use for computing the log sum

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
Since
1.2
setSumsqImplback to summary
public void setSumsqImpl(StorelessUnivariateStatistic sumsqImpl) throws MathIllegalStateException

Sets the implementation for the sum of squares.

This method cannot be activated after data has been added - i.e., after addValue has been used to add data. If it is activated after data has been added, an IllegalStateException will be thrown.

Parameters
sumsqImpl:StorelessUnivariateStatistic

the StorelessUnivariateStatistic instance to use for computing the sum of squares

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
Since
1.2
setVarianceImplback to summary
public void setVarianceImpl(StorelessUnivariateStatistic varianceImpl) throws MathIllegalStateException

Sets the implementation for the variance.

This method cannot be activated after data has been added - i.e., after addValue has been used to add data. If it is activated after data has been added, an IllegalStateException will be thrown.

Parameters
varianceImpl:StorelessUnivariateStatistic

the StorelessUnivariateStatistic instance to use for computing the variance

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
Since
1.2
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Generates a text report displaying summary statistics from values that have been added.

Returns:String

String with line feeds displaying statistics

Annotations
@Override
Since
1.2