Package 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:
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.

See Also:

  • Constructor Details

    • 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 Details

    • 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

    • getQuadraticMean

      public double getQuadraticMean()
      Returns the quadratic mean, a.k.a. root-mean-square of the available values
      Returns:
      The quadratic mean or Double.NaN if no values have been added.

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