org.apache.commons.math3.stat.descriptive

## Class SummaryStatistics

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

- All Implemented Interfaces:
    Serializable, StatisticalSummary
  Direct Known Subclasses:
    AggregateSummaryStatistics.AggregatingSummaryStatistics, 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

- - ### Field Summary

    Fields
    Modifier and Type | Field 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 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
    Modifier and Type | Method and Description
    --- | ---
    `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(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`

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

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

Copyright (c) 2003-2013 Apache Software Foundation