Class PairedStatsAccumulator
- java.lang.Object
-
- com.google.common.math.PairedStatsAccumulator
-
@GwtIncompatible public final class PairedStatsAccumulator extends java.lang.Object
A mutable object which accumulates paired double values (e.g. points on a plane) and tracks some basic statistics over all the values added so far. This class is not thread safe.- Since:
- 20.0
- Author:
- Pete Gillin
-
-
Constructor Summary
Constructors Constructor Description PairedStatsAccumulator()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
add(double x, double y)
Adds the given pair of values to the dataset.void
addAll(PairedStats values)
Adds the given statistics to the dataset, as if the individual values used to compute the statistics had been added directly.long
count()
Returns the number of pairs in the dataset.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 product-moment correlation coefficient of the values.double
populationCovariance()
Returns the population covariance of the values.double
sampleCovariance()
Returns the sample covariance of the values.PairedStats
snapshot()
Returns an immutable snapshot of the current statistics.Stats
xStats()
Returns an immutable snapshot of the statistics on thex
values alone.Stats
yStats()
Returns an immutable snapshot of the statistics on they
values alone.
-
-
-
Constructor Detail
-
PairedStatsAccumulator
public PairedStatsAccumulator()
-
-
Method Detail
-
add
public void add(double x, double y)
Adds the given pair of values to the dataset.
-
addAll
public void addAll(PairedStats values)
Adds the given statistics to the dataset, as if the individual values used to compute the statistics had been added directly.
-
snapshot
public PairedStats snapshot()
Returns an immutable snapshot of the current statistics.
-
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 non-zero.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.
Non-finite values
If the dataset contains any non-finite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.NaN
.- Throws:
java.lang.IllegalStateException
- if the dataset is empty
-
sampleCovariance
public final 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.
Non-finite values
If the dataset contains any non-finite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.NaN
.- Throws:
java.lang.IllegalStateException
- if the dataset is empty or contains a single pair of values
-
pearsonsCorrelationCoefficient
public final double pearsonsCorrelationCoefficient()
Returns the Pearson's or product-moment correlation coefficient of the values. The count must greater than one, and thex
andy
values must both have non-zero 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].Non-finite values
If the dataset contains any non-finite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.NaN
.- Throws:
java.lang.IllegalStateException
- if the dataset is empty or contains a single pair of values, or either thex
andy
dataset has zero population variance
-
leastSquaresFit
public final 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 non-zero 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 root-mean-square 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 root-mean-square 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
.Non-finite values
If the dataset contains any non-finite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isLinearTransformation.forNaN()
.- Throws:
java.lang.IllegalStateException
- if the dataset is empty or contains a single pair of values, or both thex
andy
dataset have zero population variance
-
-