Top Description Fields Constructors Methods
com.google.common.math

public final Class PairedStatsAccumulator

extends Object
Class Inheritance
Annotations
@J2ktIncompatible
@GwtIncompatible
@ElementTypesAreNonnullByDefault
Static Imports
com.google.common.base.Preconditions.checkState, com.google.common.primitives.Doubles.isFinite, java.lang.Double.NaN, .Double.isNaN
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.
Author
Pete Gillin
Since
20.0

Field Summary

Modifier and TypeField and Description
private double
sumOfProductsOfDeltas

private final StatsAccumulator
xStats

private final StatsAccumulator
yStats

Constructor Summary

AccessConstructor and Description
public
PairedStatsAccumulator()

Method Summary

Modifier and TypeMethod and Description
public void
add(double x, double y)

Adds the given pair of values to the dataset.

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.

public long
count()

Returns the number of pairs in the dataset.

private static double
ensureInUnitRange(double value)

private double
ensurePositive(double value)

public final LinearTransformation
leastSquaresFit()

Returns a linear transformation giving the best fit to the data according to Ordinary Least Squares linear regression of y as a function of x.

public final double
pearsonsCorrelationCoefficient()

Returns the Pearson's or product-moment correlation coefficient of the values.

public double
populationCovariance()

Returns the population covariance of the values.

public final double
sampleCovariance()

Returns the sample covariance of the values.

public PairedStats
snapshot()

Returns an immutable snapshot of the current statistics.

public Stats
xStats()

Returns an immutable snapshot of the statistics on the x values alone.

public Stats
yStats()

Returns an immutable snapshot of the statistics on the y values alone.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

sumOfProductsOfDeltasback to summary
private double sumOfProductsOfDeltas
xStatsback to summary
private final StatsAccumulator xStats
yStatsback to summary
private final StatsAccumulator yStats

Constructor Detail

PairedStatsAccumulatorback to summary
public PairedStatsAccumulator()

Method Detail

addback to summary
public void add(double x, double y)

Adds the given pair of values to the dataset.

addAllback to summary
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.

countback to summary
public long count()

Returns the number of pairs in the dataset.

ensureInUnitRangeback to summary
private static double ensureInUnitRange(double value)
ensurePositiveback to summary
private double ensurePositive(double value)
leastSquaresFitback to summary
public final LinearTransformation leastSquaresFit()

Returns a linear transformation giving the best fit to the data according to Ordinary Least Squares linear regression of y as a function of x. The count must be greater than one, and either the x or y 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 the x data but not the y data, and vertical if there is variance in the y data but not the x data.

This fit minimizes the root-mean-square error in y as a function of x. This error is defined as the square root of the mean of the squares of the differences between the actual y values of the data and the values predicted by the fit for the x 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 fraction sqrt(1 - R*R) of the population standard deviation of y, where R is the Pearson's correlation coefficient (as given by pearsonsCorrelationCoefficient()).

The corresponding root-mean-square error in x as a function of y is a fraction sqrt(1/(R*R) - 1) of the population standard deviation of x. This fit does not normally minimize that error: to do that, you should swap the roles of x and y.

Non-finite values

If the dataset contains any non-finite values (Double#POSITIVE_INFINITY, Double#NEGATIVE_INFINITY, or Double#NaN) then the result is LinearTransformation#forNaN().

Exceptions
IllegalStateException:
if the dataset is empty or contains a single pair of values, or both the x and y dataset have zero population variance
pearsonsCorrelationCoefficientback to summary
public final double pearsonsCorrelationCoefficient()

Returns the Pearson's or product-moment correlation coefficient of the values. The count must greater than one, and the x and y 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, or Double#NaN) then the result is Double#NaN.

Exceptions
IllegalStateException:
if the dataset is empty or contains a single pair of values, or either the x and y dataset has zero population variance
populationCovarianceback to summary
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, or Double#NaN) then the result is Double#NaN.

Exceptions
IllegalStateException:
if the dataset is empty
sampleCovarianceback to summary
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, or Double#NaN) then the result is Double#NaN.

Exceptions
IllegalStateException:
if the dataset is empty or contains a single pair of values
snapshotback to summary
public PairedStats snapshot()

Returns an immutable snapshot of the current statistics.

xStatsback to summary
public Stats xStats()

Returns an immutable snapshot of the statistics on the x values alone.

yStatsback to summary
public Stats yStats()

Returns an immutable snapshot of the statistics on the y values alone.