Class PairedStats
 java.lang.Object

 com.google.common.math.PairedStats

 All Implemented Interfaces:
Serializable
@Beta @GwtIncompatible public final class PairedStats extends Object implements Serializable
An immutable value object capturing some basic statistics about a collection of paired double values (e.g. points on a plane). Build instances withPairedStatsAccumulator.snapshot()
. Since:
 20.0
 Author:
 Pete Gillin
 See Also:
 Serialized Form


Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description long
count()
Returns the number of pairs in the dataset.boolean
equals(@Nullable Object obj)
Indicates whether some other object is "equal to" this one.static PairedStats
fromByteArray(byte[] byteArray)
Creates aPairedStats
instance from the given byte representation which was obtained bytoByteArray()
.int
hashCode()
Returns a hash code value for the object.LinearTransformation
leastSquaresFit()
Returns a linear transformation giving the best fit to the data according to Ordinary Least Squares linear regression ofy
as a function ofx
.double
pearsonsCorrelationCoefficient()
Returns the Pearson's or productmoment correlation coefficient of the values.double
populationCovariance()
Returns the population covariance of the values.double
sampleCovariance()
Returns the sample covariance of the values.byte[]
toByteArray()
Gets a byte array representation of this instance.String
toString()
Returns a string representation of the object.Stats
xStats()
Returns the statistics on thex
values alone.Stats
yStats()
Returns the statistics on they
values alone.



Method Detail

count
public long count()
Returns the number of pairs in the dataset.

populationCovariance
public double populationCovariance()
Returns the population covariance of the values. The count must be nonzero.This is guaranteed to return zero if the dataset contains a single pair of finite values. It is not guaranteed to return zero when the dataset consists of the same pair of values multiple times, due to numerical errors.
Nonfinite values
If the dataset contains any nonfinite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.NaN
. Throws:
IllegalStateException
 if the dataset is empty

sampleCovariance
public double sampleCovariance()
Returns the sample covariance of the values. The count must be greater than one.This is not guaranteed to return zero when the dataset consists of the same pair of values multiple times, due to numerical errors.
Nonfinite values
If the dataset contains any nonfinite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.NaN
. Throws:
IllegalStateException
 if the dataset is empty or contains a single pair of values

pearsonsCorrelationCoefficient
public double pearsonsCorrelationCoefficient()
Returns the Pearson's or productmoment correlation coefficient of the values. The count must greater than one, and thex
andy
values must both have nonzero population variance (i.e.xStats().populationVariance() > 0.0 && yStats().populationVariance() > 0.0
). The result is not guaranteed to be exactly +/1 even when the data are perfectly (anti)correlated, due to numerical errors. However, it is guaranteed to be in the inclusive range [1, +1].Nonfinite values
If the dataset contains any nonfinite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.NaN
. Throws:
IllegalStateException
 if the dataset is empty or contains a single pair of values, or either thex
andy
dataset has zero population variance

leastSquaresFit
public LinearTransformation leastSquaresFit()
Returns a linear transformation giving the best fit to the data according to Ordinary Least Squares linear regression ofy
as a function ofx
. The count must be greater than one, and either thex
ory
data must have a nonzero population variance (i.e.xStats().populationVariance() > 0.0  yStats().populationVariance() > 0.0
). The result is guaranteed to be horizontal if there is variance in thex
data but not they
data, and vertical if there is variance in they
data but not thex
data.This fit minimizes the rootmeansquare error in
y
as a function ofx
. This error is defined as the square root of the mean of the squares of the differences between the actualy
values of the data and the values predicted by the fit for thex
values (i.e. it is the square root of the mean of the squares of the vertical distances between the data points and the best fit line). For this fit, this error is a fractionsqrt(1  R*R)
of the population standard deviation ofy
, whereR
is the Pearson's correlation coefficient (as given bypearsonsCorrelationCoefficient()
).The corresponding rootmeansquare error in
x
as a function ofy
is a fractionsqrt(1/(R*R)  1)
of the population standard deviation ofx
. This fit does not normally minimize that error: to do that, you should swap the roles ofx
andy
.Nonfinite values
If the dataset contains any nonfinite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isLinearTransformation.forNaN()
. Throws:
IllegalStateException
 if the dataset is empty or contains a single pair of values, or both thex
andy
dataset must have zero population variance

equals
public boolean equals(@Nullable Object obj)
Indicates whether some other object is "equal to" this one.The
equals
method implements an equivalence relation on nonnull object references: It is reflexive: for any nonnull reference value
x
,x.equals(x)
should returntrue
.  It is symmetric: for any nonnull reference values
x
andy
,x.equals(y)
should returntrue
if and only ify.equals(x)
returnstrue
.  It is transitive: for any nonnull reference values
x
,y
, andz
, ifx.equals(y)
returnstrue
andy.equals(z)
returnstrue
, thenx.equals(z)
should returntrue
.  It is consistent: for any nonnull reference values
x
andy
, multiple invocations ofx.equals(y)
consistently returntrue
or consistently returnfalse
, provided no information used inequals
comparisons on the objects is modified.  For any nonnull reference value
x
,x.equals(null)
should returnfalse
.
The
equals
method for classObject
implements the most discriminating possible equivalence relation on objects; that is, for any nonnull reference valuesx
andy
, this method returnstrue
if and only ifx
andy
refer to the same object (x == y
has the valuetrue
).Note that it is generally necessary to override the
hashCode
method whenever this method is overridden, so as to maintain the general contract for thehashCode
method, which states that equal objects must have equal hash codes.Note: This tests exact equality of the calculated statistics, including the floating point values. Two instances are guaranteed to be considered equal if one is copied from the other using
second = new PairedStatsAccumulator().addAll(first).snapshot()
, if both were obtained by callingsnapshot()
on the samePairedStatsAccumulator
without adding any values in between the two calls, or if one is obtained from the other after roundtripping through java serialization. However, floating point rounding errors mean that it may be false for some instances where the statistics are mathematically equal, including instances constructed from the same values in a different order... or (in the general case) even in the same order. (It is guaranteed to return true for instances constructed from the same values in the same order ifstrictfp
is in effect, or if the system architecture guaranteesstrictfp
like semantics.) Overrides:
equals
in classObject
 Parameters:
obj
 the reference object with which to compare. Returns:
true
if this object is the same as the obj argument;false
otherwise. See Also:
Object.hashCode()
,HashMap
 It is reflexive: for any nonnull reference value

hashCode
public int hashCode()
Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided byHashMap
.The general contract of
hashCode
is: Whenever it is invoked on the same object more than once during
an execution of a Java application, the
hashCode
method must consistently return the same integer, provided no information used inequals
comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.  If two objects are equal according to the
equals(Object)
method, then calling thehashCode
method on each of the two objects must produce the same integer result.  It is not required that if two objects are unequal
according to the
Object.equals(java.lang.Object)
method, then calling thehashCode
method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
As much as is reasonably practical, the hashCode method defined by class
Object
does return distinct integers for distinct objects. (The hashCode may or may not be implemented as some function of an object's memory address at some point in time.)Note: This hash code is consistent with exact equality of the calculated statistics, including the floating point values. See the note on
equals(java.lang.Object)
for details. Overrides:
hashCode
in classObject
 Returns:
 a hash code value for this object.
 See Also:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
 Whenever it is invoked on the same object more than once during
an execution of a Java application, the

toString
public String toString()
Description copied from class:java.lang.Object
Returns a string representation of the object. In general, thetoString
method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.The
toString
method for classObject
returns a string consisting of the name of the class of which the object is an instance, the atsign character `@
', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:getClass().getName() + '@' + Integer.toHexString(hashCode())

toByteArray
public byte[] toByteArray()
Gets a byte array representation of this instance.Note: No guarantees are made regarding stability of the representation between versions.

fromByteArray
public static PairedStats fromByteArray(byte[] byteArray)
Creates aPairedStats
instance from the given byte representation which was obtained bytoByteArray()
.Note: No guarantees are made regarding stability of the representation between versions.

