@Beta @GwtIncompatible public final class PairedStats extends java.lang.Object implements java.io.Serializable
PairedStatsAccumulator.snapshot()
.Modifier and Type | Field and Description |
---|---|
private static int |
BYTES
The size of byte array representaion in bytes.
|
private static long |
serialVersionUID |
private double |
sumOfProductsOfDeltas |
private Stats |
xStats |
private Stats |
yStats |
Constructor and Description |
---|
PairedStats(Stats xStats,
Stats yStats,
double sumOfProductsOfDeltas)
Internal constructor.
|
Modifier and Type | Method and Description |
---|---|
long |
count()
Returns the number of pairs in the dataset.
|
private static double |
ensureInUnitRange(double value) |
private static double |
ensurePositive(double value) |
boolean |
equals(java.lang.Object obj) |
static PairedStats |
fromByteArray(byte[] byteArray)
Creates a
PairedStats instance from the given byte representation which was obtained by
toByteArray() . |
int |
hashCode() |
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 . |
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.
|
(package private) double |
sumOfProductsOfDeltas() |
byte[] |
toByteArray()
Gets a byte array representation of this instance.
|
java.lang.String |
toString() |
Stats |
xStats()
Returns the statistics on the
x values alone. |
Stats |
yStats()
Returns the statistics on the
y values alone. |
private final Stats xStats
private final Stats yStats
private final double sumOfProductsOfDeltas
private static final int BYTES
private static final long serialVersionUID
PairedStats(Stats xStats, Stats yStats, double sumOfProductsOfDeltas)
PairedStatsAccumulator.snapshot()
.
To ensure that the created instance obeys its contract, the parameters should satisfy the following constraints. This is the callers responsibility and is not enforced here.
xStats
and yStats
must have the same .
count
is 1, sumOfProductsOfDeltas
must be exactly 0.0.
count
is more than 1, sumOfProductsOfDeltas
must be finite.
public long count()
public Stats xStats()
x
values alone.public Stats yStats()
y
values alone.public double populationCovariance()
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.
If the dataset contains any non-finite values (Double.POSITIVE_INFINITY
,
Double.NEGATIVE_INFINITY
, or Double.NaN
) then the result is Double.NaN
.
java.lang.IllegalStateException
- if the dataset is emptypublic double sampleCovariance()
This is not guaranteed to return zero when the dataset consists of the same pair of values multiple times, due to numerical errors.
If the dataset contains any non-finite values (Double.POSITIVE_INFINITY
,
Double.NEGATIVE_INFINITY
, or Double.NaN
) then the result is Double.NaN
.
java.lang.IllegalStateException
- if the dataset is empty or contains a single pair of valuespublic double pearsonsCorrelationCoefficient()
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].
If the dataset contains any non-finite values (Double.POSITIVE_INFINITY
,
Double.NEGATIVE_INFINITY
, or Double.NaN
) then the result is Double.NaN
.
java.lang.IllegalStateException
- if the dataset is empty or contains a single pair of values, or
either the x
and y
dataset has zero population variancepublic LinearTransformation leastSquaresFit()
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
.
If the dataset contains any non-finite values (Double.POSITIVE_INFINITY
,
Double.NEGATIVE_INFINITY
, or Double.NaN
) then the result is
LinearTransformation.forNaN()
.
java.lang.IllegalStateException
- if the dataset is empty or contains a single pair of values, or
both the x
and y
dataset must have zero population variancepublic boolean equals(@Nullable java.lang.Object obj)
Note: This tests exact equality of the calculated statistics, including the floating point values. It is definitely true for instances constructed from exactly the same values in the same order. It is also true for an instance round-tripped through java serialization. However, floating point rounding errors mean that it may be false for some instances where the statistics are mathematically equal, including the same values in a different order.
equals
in class java.lang.Object
public int hashCode()
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.
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
double sumOfProductsOfDeltas()
private static double ensurePositive(double value)
private static double ensureInUnitRange(double value)
public byte[] toByteArray()
Note: No guarantees are made regarding stability of the representation between versions.
public static PairedStats fromByteArray(byte[] byteArray)
PairedStats
instance from the given byte representation which was obtained by
toByteArray()
.
Note: No guarantees are made regarding stability of the representation between versions.