## org.apache.commons.math.stat.descriptive
Class MultivariateSummaryStatistics

    java.lang.Object
      org.apache.commons.math.stat.descriptive.MultivariateSummaryStatistics

All Implemented Interfaces:
  java.io.Serializable, StatisticalMultivariateSummary

Direct Known Subclasses:
  SynchronizedMultivariateSummaryStatistics

    public class MultivariateSummaryStatistics

extends java.lang.Object
implements StatisticalMultivariateSummary, java.io.Serializable

Computes summary statistics for a stream of n-tuples 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 n-tuple streams.

The `StorelessUnivariateStatistic` instances used to maintain summary state and compute statistics are configurable via setters. For example, the default implementation for the mean can be overridden by calling `setMeanImpl(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.

To compute statistics for a stream of n-tuples, construct a MultivariateStatistics instance with dimension n and then use `addValue(double[])` to add n-tuples. The `getXxx` methods where Xxx is a statistic return an array of `double` values, where for `i = 0,...,n-1` the ith array element is the value of the given statistic for data range consisting of the ith element of each of the input n-tuples. For example, if `addValue` is called with actual parameters {0, 1, 2}, then {3, 4, 5} and finally {6, 7, 8}, `getSum` will return a three-element array with values {0+3+6, 1+4+7, 2+5+8}

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

Since:
  1.2
Version:
  $Revision: 811833 $ $Date: 2009-09-06 12:27:50 -0400 (Sun, 06 Sep 2009) $
See Also:
  Serialized Form

Field Summary
`private VectorialCovariance` `covarianceImpl` Covariance statistic implementation - cannot be reset.
`private StorelessUnivariateStatistic[]` `geoMeanImpl` Geometric mean statistic implementation - can be reset by setter.
`private int` `k` Dimension of the data.
`private StorelessUnivariateStatistic[]` `maxImpl` Maximum statistic implementation - can be reset by setter.
`private StorelessUnivariateStatistic[]` `meanImpl` Mean statistic implementation - can be reset by setter.
`private StorelessUnivariateStatistic[]` `minImpl` Minimum statistic implementation - can be reset by setter.
`private long` `n` Count of values that have been added
`private static long` `serialVersionUID` Serialization UID
`private StorelessUnivariateStatistic[]` `sumImpl` Sum statistic implementation - can be reset by setter.
`private StorelessUnivariateStatistic[]` `sumLogImpl` Sum of log statistic implementation - can be reset by setter.
`private StorelessUnivariateStatistic[]` `sumSqImpl` Sum of squares statistic implementation - can be reset by setter.

Constructor Summary
`MultivariateSummaryStatistics(int k, boolean isCovarianceBiasCorrected)` Construct a MultivariateSummaryStatistics instance

Method Summary
`void` `addValue(double[] value)` Add an n-tuple to the data
`private void` `append(java.lang.StringBuffer buffer, double[] data, java.lang.String prefix, java.lang.String separator, java.lang.String suffix)` Append a text representation of an array to a buffer.
`private void` `checkDimension(int dimension)` Throws DimensionMismatchException if dimension != k.
`private void` `checkEmpty()` Throws IllegalStateException if n > 0.
`void` `clear()` Resets all statistics and storage
`boolean` `equals(java.lang.Object object)` Returns true iff `object` is a `SummaryStatistics` instance and all statistics have the same values as this.
`RealMatrix` `getCovariance()` Returns the covariance matrix of the values that have been added.
`int` `getDimension()` Returns the dimension of the data
`StorelessUnivariateStatistic[]` `getGeoMeanImpl()` Returns the currently configured geometric mean implementation
`double[]` `getGeometricMean()` Returns an array whose ith entry is the geometric mean of the ith entries of the arrays that have been added using `addValue(double[])`
`double[]` `getMax()` Returns an array whose ith entry is the maximum of the ith entries of the arrays that have been added using `addValue(double[])`
`StorelessUnivariateStatistic[]` `getMaxImpl()` Returns the currently configured maximum implementation
`double[]` `getMean()` Returns an array whose ith entry is the mean of the ith entries of the arrays that have been added using `addValue(double[])`
`StorelessUnivariateStatistic[]` `getMeanImpl()` Returns the currently configured mean implementation
`double[]` `getMin()` Returns an array whose ith entry is the minimum of the ith entries of the arrays that have been added using `addValue(double[])`
`StorelessUnivariateStatistic[]` `getMinImpl()` Returns the currently configured minimum implementation
`long` `getN()` Returns the number of available values
`private double[]` `getResults(StorelessUnivariateStatistic[] stats)` Returns an array of the results of a statistic.
`double[]` `getStandardDeviation()` Returns an array whose ith entry is the standard deviation of the ith entries of the arrays that have been added using `addValue(double[])`
`double[]` `getSum()` Returns an array whose ith entry is the sum of the ith entries of the arrays that have been added using `addValue(double[])`
`StorelessUnivariateStatistic[]` `getSumImpl()` Returns the currently configured Sum implementation
`double[]` `getSumLog()` Returns an array whose ith entry is the sum of logs of the ith entries of the arrays that have been added using `addValue(double[])`
`StorelessUnivariateStatistic[]` `getSumLogImpl()` Returns the currently configured sum of logs implementation
`double[]` `getSumSq()` Returns an array whose ith entry is the sum of squares of the ith entries of the arrays that have been added using `addValue(double[])`
`StorelessUnivariateStatistic[]` `getSumsqImpl()` Returns the currently configured sum of squares implementation
`int` `hashCode()` Returns hash code based on values of statistics
`void` `setGeoMeanImpl(StorelessUnivariateStatistic[] geoMeanImpl)` Sets the implementation for the geometric mean.
`private void` `setImpl(StorelessUnivariateStatistic[] newImpl, StorelessUnivariateStatistic[] oldImpl)` Sets statistics implementations.
`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.
`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

### k

    private int k

  Dimension of the data.

### n

    private long n

  Count 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.

### covarianceImpl

    private VectorialCovariance covarianceImpl

  Covariance statistic implementation - cannot be reset.

Constructor Detail

### MultivariateSummaryStatistics

    public MultivariateSummaryStatistics(int k,
                                         boolean isCovarianceBiasCorrected)

  Construct a MultivariateSummaryStatistics instance

  Parameters:
    `k` - dimension of the data
    `isCovarianceBiasCorrected` - if true, the unbiased sample covariance is computed, otherwise the biased population covariance is computed

Method Detail

### addValue

    public void addValue(double[] value)
                  throws DimensionMismatchException

  Add an n-tuple to the data

  Parameters:
    `value` - the n-tuple to add
  Throws:
    `DimensionMismatchException` - if the length of the array does not match the one used at construction

### getDimension

    public int getDimension()

  Returns the dimension of the data

  Specified by:
    `getDimension` in interface `StatisticalMultivariateSummary`
  Returns:
    The dimension of the data

### getN

    public long getN()

  Returns the number of available values

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

### getResults

    private double[] getResults(StorelessUnivariateStatistic[] stats)

  Returns an array of the results of a statistic.

  Parameters:
    `stats` - univariate statistic array
  Returns:
    results array

### getSum

    public double[] getSum()

  Returns an array whose ith entry is the sum of the ith entries of the arrays that have been added using `addValue(double[])`

  Specified by:
    `getSum` in interface `StatisticalMultivariateSummary`
  Returns:
    the array of component sums

### getSumSq

    public double[] getSumSq()

  Returns an array whose ith entry is the sum of squares of the ith entries of the arrays that have been added using `addValue(double[])`

  Specified by:
    `getSumSq` in interface `StatisticalMultivariateSummary`
  Returns:
    the array of component sums of squares

### getSumLog

    public double[] getSumLog()

  Returns an array whose ith entry is the sum of logs of the ith entries of the arrays that have been added using `addValue(double[])`

  Specified by:
    `getSumLog` in interface `StatisticalMultivariateSummary`
  Returns:
    the array of component log sums

### getMean

    public double[] getMean()

  Returns an array whose ith entry is the mean of the ith entries of the arrays that have been added using `addValue(double[])`

  Specified by:
    `getMean` in interface `StatisticalMultivariateSummary`
  Returns:
    the array of component means

### getStandardDeviation

    public double[] getStandardDeviation()

  Returns an array whose ith entry is the standard deviation of the ith entries of the arrays that have been added using `addValue(double[])`

  Specified by:
    `getStandardDeviation` in interface `StatisticalMultivariateSummary`
  Returns:
    the array of component standard deviations

### getCovariance

    public RealMatrix getCovariance()

  Returns the covariance matrix of the values that have been added.

  Specified by:
    `getCovariance` in interface `StatisticalMultivariateSummary`
  Returns:
    the covariance matrix

### getMax

    public double[] getMax()

  Returns an array whose ith entry is the maximum of the ith entries of the arrays that have been added using `addValue(double[])`

  Specified by:
    `getMax` in interface `StatisticalMultivariateSummary`
  Returns:
    the array of component maxima

### getMin

    public double[] getMin()

  Returns an array whose ith entry is the minimum of the ith entries of the arrays that have been added using `addValue(double[])`

  Specified by:
    `getMin` in interface `StatisticalMultivariateSummary`
  Returns:
    the array of component minima

### getGeometricMean

    public double[] getGeometricMean()

  Returns an array whose ith entry is the geometric mean of the ith entries of the arrays that have been added using `addValue(double[])`

  Specified by:
    `getGeometricMean` in interface `StatisticalMultivariateSummary`
  Returns:
    the array of component geometric means

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

### append

    private void append(java.lang.StringBuffer buffer,
                        double[] data,
                        java.lang.String prefix,
                        java.lang.String separator,
                        java.lang.String suffix)

  Append a text representation of an array to a buffer.

  Parameters:
    `buffer` - buffer to fill
    `data` - data array
    `prefix` - text prefix
    `separator` - elements separator
    `suffix` - text suffix

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

### setImpl

    private void setImpl(StorelessUnivariateStatistic[] newImpl,
                         StorelessUnivariateStatistic[] oldImpl)
                  throws DimensionMismatchException,
                         java.lang.IllegalStateException

  Sets statistics implementations.

  Parameters:
    `newImpl` - new implementations for statistics
    `oldImpl` - old implementations for statistics
  Throws:
    `DimensionMismatchException` - if the array dimension does not match the one used at construction
    `java.lang.IllegalStateException` - if data has already been added (i.e if n > 0)

### getSumImpl

    public StorelessUnivariateStatistic[] getSumImpl()

  Returns the currently configured Sum implementation

  Returns:
    the StorelessUnivariateStatistic implementing the sum

### setSumImpl

    public void setSumImpl(StorelessUnivariateStatistic[] sumImpl)
                    throws DimensionMismatchException

  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:
    `DimensionMismatchException` - if the array dimension does not match the one used at construction
    `java.lang.IllegalStateException` - if data has already been added (i.e if n > 0)

### getSumsqImpl

    public StorelessUnivariateStatistic[] getSumsqImpl()

  Returns the currently configured sum of squares implementation

  Returns:
    the StorelessUnivariateStatistic implementing the sum of squares

### setSumsqImpl

    public void setSumsqImpl(StorelessUnivariateStatistic[] sumsqImpl)
                      throws DimensionMismatchException

  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:
    `DimensionMismatchException` - if the array dimension does not match the one used at construction
    `java.lang.IllegalStateException` - if data has already been added (i.e if n > 0)

### getMinImpl

    public StorelessUnivariateStatistic[] getMinImpl()

  Returns the currently configured minimum implementation

  Returns:
    the StorelessUnivariateStatistic implementing the minimum

### setMinImpl

    public void setMinImpl(StorelessUnivariateStatistic[] minImpl)
                    throws DimensionMismatchException

  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:
    `DimensionMismatchException` - if the array dimension does not match the one used at construction
    `java.lang.IllegalStateException` - if data has already been added (i.e if n > 0)

### getMaxImpl

    public StorelessUnivariateStatistic[] getMaxImpl()

  Returns the currently configured maximum implementation

  Returns:
    the StorelessUnivariateStatistic implementing the maximum

### setMaxImpl

    public void setMaxImpl(StorelessUnivariateStatistic[] maxImpl)
                    throws DimensionMismatchException

  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:
    `DimensionMismatchException` - if the array dimension does not match the one used at construction
    `java.lang.IllegalStateException` - if data has already been added (i.e if n > 0)

### getSumLogImpl

    public StorelessUnivariateStatistic[] getSumLogImpl()

  Returns the currently configured sum of logs implementation

  Returns:
    the StorelessUnivariateStatistic implementing the log sum

### setSumLogImpl

    public void setSumLogImpl(StorelessUnivariateStatistic[] sumLogImpl)
                       throws DimensionMismatchException

  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:
    `DimensionMismatchException` - if the array dimension does not match the one used at construction
    `java.lang.IllegalStateException` - if data has already been added (i.e if n > 0)

### getGeoMeanImpl

    public StorelessUnivariateStatistic[] getGeoMeanImpl()

  Returns the currently configured geometric mean implementation

  Returns:
    the StorelessUnivariateStatistic implementing the geometric mean

### setGeoMeanImpl

    public void setGeoMeanImpl(StorelessUnivariateStatistic[] geoMeanImpl)
                        throws DimensionMismatchException

  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:
    `DimensionMismatchException` - if the array dimension does not match the one used at construction
    `java.lang.IllegalStateException` - if data has already been added (i.e if n > 0)

### getMeanImpl

    public StorelessUnivariateStatistic[] getMeanImpl()

  Returns the currently configured mean implementation

  Returns:
    the StorelessUnivariateStatistic implementing the mean

### setMeanImpl

    public void setMeanImpl(StorelessUnivariateStatistic[] meanImpl)
                     throws DimensionMismatchException

  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:
    `DimensionMismatchException` - if the array dimension does not match the one used at construction
    `java.lang.IllegalStateException` - if data has already been added (i.e if n > 0)

### checkEmpty

    private void checkEmpty()

  Throws IllegalStateException if n > 0.

### checkDimension

    private void checkDimension(int dimension)
                         throws DimensionMismatchException

  Throws DimensionMismatchException if dimension != k.

  Parameters:
    `dimension` - dimension to check
  Throws:
    `DimensionMismatchException` - if dimension != k

Copyright (c) 2003-2011 Apache Software Foundation