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

public Class MultivariateSummaryStatistics

extends Object
implements StatisticalMultivariateSummary, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary
Known Direct Subclasses
org.apache.commons.math3.stat.descriptive.SynchronizedMultivariateSummaryStatistics
Imports
java.io.Serializable, java.util.Arrays, org.apache.commons.math3.exception.util.LocalizedFormats, org.apache.commons.math3.exception.DimensionMismatchException, .MathIllegalStateException, org.apache.commons.math3.linear.RealMatrix, org.apache.commons.math3.stat.descriptive.moment.GeometricMean, .Mean, .VectorialCovariance, 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, .MathArrays, .Precision, .FastMath

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

Field Summary

Modifier and TypeField and Description
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 final 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

AccessConstructor and Description
public
MultivariateSummaryStatistics(int
dimension of the data
k, boolean
if true, the unbiased sample covariance is computed, otherwise the biased population covariance is computed
isCovarianceBiasCorrected)

Construct a MultivariateSummaryStatistics instance

Method Summary

Modifier and TypeMethod and Description
public void
addValue(double[]
the n-tuple to add
value)

Add an n-tuple to the data

private void
append(StringBuilder
buffer to fill
buffer, double[]
data array
data, String
text prefix
prefix, String
elements separator
separator, String
text suffix
suffix)

Append a text representation of an array to a buffer.

private void
checkDimension(int
dimension to check
dimension)

Throws DimensionMismatchException if dimension != k.

private void
checkEmpty()

Throws MathIllegalStateException if the statistic is not empty.

public void
clear()

Resets all statistics and storage

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 MultivariateSummaryStatistics instance and all statistics have the same values as this.

public RealMatrix

Returns:

the covariance matrix
getCovariance()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.getCovariance.

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

public int

Returns:

The dimension of the data
getDimension()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.getDimension.

Returns the dimension of the data

public StorelessUnivariateStatistic[]

Returns:

the StorelessUnivariateStatistic implementing the geometric mean
getGeoMeanImpl()

Returns the currently configured geometric mean implementation

public double[]

Returns:

the array of component geometric means
getGeometricMean()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.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[])

public double[]

Returns:

the array of component maxima
getMax()

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

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

public StorelessUnivariateStatistic[]

Returns:

the StorelessUnivariateStatistic implementing the maximum
getMaxImpl()

Returns the currently configured maximum implementation

public double[]

Returns:

the array of component means
getMean()

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

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

public StorelessUnivariateStatistic[]

Returns:

the StorelessUnivariateStatistic implementing the mean
getMeanImpl()

Returns the currently configured mean implementation

public double[]

Returns:

the array of component minima
getMin()

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

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

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.StatisticalMultivariateSummary.getN.

Returns the number of available values

private double[]

Returns:

results array
getResults(StorelessUnivariateStatistic[]
univariate statistic array
stats)

Returns an array of the results of a statistic.

public double[]

Returns:

the array of component standard deviations
getStandardDeviation()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.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[])

public double[]

Returns:

the array of component sums
getSum()

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

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

public StorelessUnivariateStatistic[]

Returns:

the StorelessUnivariateStatistic implementing the sum
getSumImpl()

Returns the currently configured Sum implementation

public double[]

Returns:

the array of component log sums
getSumLog()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.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[])

public StorelessUnivariateStatistic[]

Returns:

the StorelessUnivariateStatistic implementing the log sum
getSumLogImpl()

Returns the currently configured sum of logs implementation

public double[]

Returns:

the array of component sums of squares
getSumSq()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.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[])

public StorelessUnivariateStatistic[]

Returns:

the StorelessUnivariateStatistic implementing the sum of squares
getSumsqImpl()

Returns the currently configured sum of squares 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.

private void
setImpl(StorelessUnivariateStatistic[]
new implementations for statistics
newImpl, StorelessUnivariateStatistic[]
old implementations for statistics
oldImpl)

Sets statistics implementations.

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

covarianceImplback to summary
private VectorialCovariance covarianceImpl

Covariance statistic implementation - cannot be reset.

geoMeanImplback to summary
private StorelessUnivariateStatistic[] geoMeanImpl

Geometric mean statistic implementation - can be reset by setter.

kback to summary
private int k

Dimension of the data.

maxImplback to summary
private StorelessUnivariateStatistic[] maxImpl

Maximum statistic implementation - can be reset by setter.

meanImplback to summary
private StorelessUnivariateStatistic[] meanImpl

Mean statistic implementation - can be reset by setter.

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

serialVersionUIDback to summary
private static final long serialVersionUID

Serialization UID

sumImplback to summary
private StorelessUnivariateStatistic[] sumImpl

Sum statistic implementation - can be reset by setter.

sumLogImplback to summary
private StorelessUnivariateStatistic[] sumLogImpl

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

sumSqImplback to summary
private StorelessUnivariateStatistic[] sumSqImpl

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

Constructor Detail

MultivariateSummaryStatisticsback to summary
public MultivariateSummaryStatistics(int k, boolean isCovarianceBiasCorrected)

Construct a MultivariateSummaryStatistics instance

Parameters
k:int

dimension of the data

isCovarianceBiasCorrected:boolean

if true, the unbiased sample covariance is computed, otherwise the biased population covariance is computed

Method Detail

addValueback to summary
public void addValue(double[] value) throws DimensionMismatchException

Add an n-tuple to the data

Parameters
value:double[]

the n-tuple to add

Exceptions
DimensionMismatchException:
if the length of the array does not match the one used at construction
appendback to summary
private void append(StringBuilder buffer, double[] data, String prefix, String separator, String suffix)

Append a text representation of an array to a buffer.

Parameters
buffer:StringBuilder

buffer to fill

data:double[]

data array

prefix:String

text prefix

separator:String

elements separator

suffix:String

text suffix

checkDimensionback to summary
private void checkDimension(int dimension) throws DimensionMismatchException

Throws DimensionMismatchException if dimension != k.

Parameters
dimension:int

dimension to check

Exceptions
DimensionMismatchException:
if dimension != k
checkEmptyback to summary
private void checkEmpty() throws MathIllegalStateException

Throws MathIllegalStateException if the statistic is not empty.

Exceptions
MathIllegalStateException:
if n > 0.
clearback to summary
public void clear()

Resets all statistics and storage

equalsback to summary
public boolean equals(Object object)

Overrides java.lang.Object.equals.

Returns true iff object is a MultivariateSummaryStatistics 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
getCovarianceback to summary
public RealMatrix getCovariance()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.getCovariance.

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

Returns:RealMatrix

the covariance matrix

getDimensionback to summary
public int getDimension()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.getDimension.

Returns the dimension of the data

Returns:int

The dimension of the data

getGeoMeanImplback to summary
public StorelessUnivariateStatistic[] getGeoMeanImpl()

Returns the currently configured geometric mean implementation

Returns:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic implementing the geometric mean

getGeometricMeanback to summary
public double[] getGeometricMean()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.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[])

Returns:double[]

the array of component geometric means

getMaxback to summary
public double[] getMax()

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

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

Returns:double[]

the array of component maxima

getMaxImplback to summary
public StorelessUnivariateStatistic[] getMaxImpl()

Returns the currently configured maximum implementation

Returns:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic implementing the maximum

getMeanback to summary
public double[] getMean()

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

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

Returns:double[]

the array of component means

getMeanImplback to summary
public StorelessUnivariateStatistic[] getMeanImpl()

Returns the currently configured mean implementation

Returns:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic implementing the mean

getMinback to summary
public double[] getMin()

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

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

Returns:double[]

the array of component minima

getMinImplback to summary
public StorelessUnivariateStatistic[] getMinImpl()

Returns the currently configured minimum implementation

Returns:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic implementing the minimum

getNback to summary
public long getN()

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

Returns the number of available values

Returns:long

The number of available values

getResultsback to summary
private double[] getResults(StorelessUnivariateStatistic[] stats)

Returns an array of the results of a statistic.

Parameters
stats:StorelessUnivariateStatistic[]

univariate statistic array

Returns:double[]

results array

getStandardDeviationback to summary
public double[] getStandardDeviation()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.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[])

Returns:double[]

the array of component standard deviations

getSumback to summary
public double[] getSum()

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

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

Returns:double[]

the array of component sums

getSumImplback to summary
public StorelessUnivariateStatistic[] getSumImpl()

Returns the currently configured Sum implementation

Returns:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic implementing the sum

getSumLogback to summary
public double[] getSumLog()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.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[])

Returns:double[]

the array of component log sums

getSumLogImplback to summary
public StorelessUnivariateStatistic[] getSumLogImpl()

Returns the currently configured sum of logs implementation

Returns:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic implementing the log sum

getSumSqback to summary
public double[] getSumSq()

Implements org.apache.commons.math3.stat.descriptive.StatisticalMultivariateSummary.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[])

Returns:double[]

the array of component sums 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

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, 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:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic instance to use for computing the geometric mean

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
DimensionMismatchException:
if the array dimension does not match the one used at construction
setImplback to summary
private void setImpl(StorelessUnivariateStatistic[] newImpl, StorelessUnivariateStatistic[] oldImpl) throws MathIllegalStateException, DimensionMismatchException

Sets statistics implementations.

Parameters
newImpl:StorelessUnivariateStatistic[]

new implementations for statistics

oldImpl:StorelessUnivariateStatistic[]

old implementations for statistics

Exceptions
MathIllegalStateException:
if data has already been added (i.e. if n > 0)
DimensionMismatchException:
if the array dimension does not match the one used at construction
setMaxImplback to summary
public void setMaxImpl(StorelessUnivariateStatistic[] maxImpl) throws MathIllegalStateException, 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:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic instance to use for computing the maximum

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
DimensionMismatchException:
if the array dimension does not match the one used at construction
setMeanImplback to summary
public void setMeanImpl(StorelessUnivariateStatistic[] meanImpl) throws MathIllegalStateException, 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:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic instance to use for computing the mean

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
DimensionMismatchException:
if the array dimension does not match the one used at construction
setMinImplback to summary
public void setMinImpl(StorelessUnivariateStatistic[] minImpl) throws MathIllegalStateException, 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:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic instance to use for computing the minimum

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
DimensionMismatchException:
if the array dimension does not match the one used at construction
setSumImplback to summary
public void setSumImpl(StorelessUnivariateStatistic[] sumImpl) throws MathIllegalStateException, 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:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic instance to use for computing the Sum

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
DimensionMismatchException:
if the array dimension does not match the one used at construction
setSumLogImplback to summary
public void setSumLogImpl(StorelessUnivariateStatistic[] sumLogImpl) throws MathIllegalStateException, 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:StorelessUnivariateStatistic[]

the StorelessUnivariateStatistic instance to use for computing the log sum

Exceptions
MathIllegalStateException:
if data has already been added (i.e if n > 0)
DimensionMismatchException:
if the array dimension does not match the one used at construction
setSumsqImplback to summary
public void setSumsqImpl(StorelessUnivariateStatistic[] sumsqImpl) throws MathIllegalStateException, 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: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)
DimensionMismatchException:
if the array dimension does not match the one used at construction
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