org.apache.commons.math3.stat.descriptive

## Class SummaryStatistics

- java.lang.Object
- - org.apache.commons.math3.stat.descriptive.SummaryStatistics

All Implemented Interfaces:
  java.io.Serializable, StatisticalSummary

Direct Known Subclasses:
  AggregateSummaryStatistics.AggregatingSummaryStatistics, SynchronizedSummaryStatistics

    public class SummaryStatistics
    extends java.lang.Object
    implements StatisticalSummary, java.io.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

### Field Summary

Fields
`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 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

Constructors
Constructor and Description
`SummaryStatistics()` Construct a SummaryStatistics instance
`SummaryStatistics(SummaryStatistics original)` A copy constructor.

### Method Summary

Methods
`void` `addValue(double value)` Add a value to the data
`private void` `checkEmpty()` Throws IllegalStateException if n > 0.
`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(java.lang.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.
`java.lang.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`

### Field Detail

#### serialVersionUID

    private static final long serialVersionUID

Serialization UID

See Also:
  Constant Field Values

#### n

    private long n

count of values that have been added

#### secondMoment

    private SecondMoment secondMoment

SecondMoment is used to compute the mean and variance

#### sum

    private Sum sum

sum of values that have been added

#### sumsq

    private SumOfSquares sumsq

sum of the square of each value that has been added

#### min

    private Min min

min of values that have been added

#### max

    private Max max

max of values that have been added

#### sumLog

    private SumOfLogs sumLog

sumLog of values that have been added

#### geoMean

    private GeometricMean geoMean

geoMean of values that have been added

#### mean

    private Mean mean

mean of values that have been added

#### variance

    private Variance variance

variance of values that have been added

#### sumImpl

    private StorelessUnivariateStatistic sumImpl

Sum statistic implementation - can be reset by setter.

#### sumsqImpl

    private StorelessUnivariateStatistic sumsqImpl

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

#### minImpl

    private StorelessUnivariateStatistic minImpl

Minimum statistic implementation - can be reset by setter.

#### maxImpl

    private StorelessUnivariateStatistic maxImpl

Maximum statistic implementation - can be reset by setter.

#### sumLogImpl

    private StorelessUnivariateStatistic sumLogImpl

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

#### geoMeanImpl

    private StorelessUnivariateStatistic geoMeanImpl

Geometric mean statistic implementation - can be reset by setter.

#### meanImpl

    private StorelessUnivariateStatistic meanImpl

Mean statistic implementation - can be reset by setter.

#### varianceImpl

    private StorelessUnivariateStatistic varianceImpl

Variance statistic implementation - can be reset by setter.

### 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 java.lang.String toString()

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

Overrides:
  `toString` in class `java.lang.Object`
Returns:
  String with line feeds displaying statistics
Since:
  1.2

#### clear

    public void clear()

Resets all statistics and storage

#### equals

    public boolean equals(java.lang.Object object)

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

Overrides:
  `equals` in class `java.lang.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 `java.lang.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

#### checkEmpty

    private void checkEmpty()
                     throws MathIllegalStateException

Throws IllegalStateException if n > 0.

Throws:
  `MathIllegalStateException` - if data has been added

#### 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