public class Statistics extends Object implements DoubleConsumer, LongConsumer, Cloneable, Serializable
In addition to the statistics on the sample values, this class can optionally compute
statistics on the differences between consecutive sample values, i.e. the statistics on
y₁-y₀, y₂-y₁, y₃-y₂, etc…,
Those statistics can be fetched by a call to differences()
.
They are useful for verifying if the interval between sample values is approximatively constant.
If the samples are (at least conceptually) the result of some y=f(x)
function for x values increasing or decreasing at a constant interval Δx,
then one can get the statistics on the discrete derivatives by a call to
differences().scale(1/Δx)
.
Statistics are computed on the fly using the Kahan summation algorithm for reducing the numerical errors; the sample values are never stored in memory.
An instance of Statistics
is initially empty: the count of
values is set to zero, and all above-cited statistical values are set to NaN
.
The statistics are updated every time an accept(double)
method is invoked with a non-NaN
value.
Following example computes the statistics on the first and second derivatives in addition to the statistics on the sample values:Statistics stats = new Statistics("y"); for (int i=0; i<numberOfValues; i++) { stats.accept(f(i)); } System.out.println(stats);
final double x₀ = ...; // Put here the x value at i=0 final double Δx = ...; // Put here the interval between x values Statistics stats = Statistics.forSeries("y", "∂y/∂x", "∂²y/∂x²"); for (int i=0; i<numberOfValues; i++) { stats.accept(f(x₀ + i*Δx)); } stats.differences().scale(1/Δx); System.out.println(stats);
Defined in the sis-utility
module
Constructor and Description |
---|
Statistics(CharSequence name)
Constructs an initially empty set of statistics.
|
Modifier and Type | Method and Description |
---|---|
void |
accept(double sample)
Updates statistics for the specified floating-point sample value.
|
void |
accept(long sample)
Updates statistics for the specified integer sample value.
|
Statistics |
clone()
Returns a clone of this statistics.
|
void |
combine(Statistics stats)
Updates statistics with all samples from the specified
stats . |
int |
count()
Returns the number of samples, excluding
NaN values. |
int |
countNaN()
Returns the number of
NaN samples. |
Statistics |
differences()
Returns the statistics on the differences between sample values, or
null if none. |
boolean |
equals(Object object)
Compares this statistics with the specified object for equality.
|
static Statistics |
forSeries(CharSequence name,
CharSequence... differenceNames)
Constructs a new
Statistics object which will also compute finite differences
up to the given order. |
int |
hashCode()
Returns a hash code value for this statistics.
|
double |
maximum()
Returns the maximum sample value, or
NaN if none. |
double |
mean()
Returns the mean value, or
NaN if none. |
double |
minimum()
Returns the minimum sample value, or
NaN if none. |
InternationalString |
name()
Returns the name of the phenomenon for which this object is collecting statistics.
|
void |
reset()
Resets this object state as if it was just created.
|
double |
rms()
Returns the root mean square, or
NaN if none. |
void |
scale(double factor)
Multiplies the statistics by the given factor.
|
double |
span()
|
double |
standardDeviation(boolean allPopulation)
Returns the standard deviation.
|
double |
sum()
Returns the sum, or 0 if none.
|
String |
toString()
Returns a string representation of this statistics.
|
public Statistics(CharSequence name)
sum()
are initialized to zero
and all other statistical values are initialized to Double.NaN
.
Instances created by this constructor do not compute differences between sample values.
If differences or discrete derivatives are wanted, use the forSeries(…)
method instead.
name
- The phenomenon for which this object is collecting statistics, or null
if none. If non-null, then this name will be shown as column header in the table
formatted by StatisticsFormat
.public static Statistics forSeries(CharSequence name, CharSequence... differenceNames)
Statistics
object which will also compute finite differences
up to the given order. If the values to be given to the accept(…)
methods are
the y values of some y=f(x) function for
x values increasing or decreasing at a constant interval Δx,
then the finite differences are proportional to discrete derivatives.
The Statistics
object created by this method know nothing about the Δx
interval. In order to get the discrete derivatives, the following method needs to be invoked
after all sample values have been added:
The maximal "derivative" order is determined by the length of thestatistics.differences().scale(1/Δx);
differenceNames
array:
Statistics
object).name
- The phenomenon for which this object is collecting statistics, or null
if none. If non-null, then this name will be shown as column header in the table
formatted by StatisticsFormat
.differenceNames
- The names of the statistics on differences.
The given array can not be null, but can contain null elements.differences()
public InternationalString name()
StatisticsFormat
.null
if none.public void reset()
sum()
are set to zero
and all other statistical values are set to Double.NaN
.public void accept(double sample)
NaN
values increment the NaN count,
but are otherwise ignored.accept
in interface DoubleConsumer
sample
- The sample value (may be NaN).accept(long)
,
combine(Statistics)
public void accept(long sample)
accept(double)
version.accept
in interface LongConsumer
sample
- The sample value.accept(double)
,
combine(Statistics)
public void combine(Statistics stats)
stats
.
Invoking this method is equivalent (except for rounding errors) to invoking
accept(…)
for all samples that were added to stats
.stats
- The statistics to be added to this
.public void scale(double factor)
accept(…)
had been first multiplied by the given factor.
This method is useful for computing discrete derivatives from the differences between
sample values. See differences()
or forSeries(…)
for more
information.
factor
- The factor by which to multiply the statistics.public int countNaN()
NaN
samples.
NaN
samples are ignored in all other statistical computation.
This method count them for information purpose only.public int count()
NaN
values.public double minimum()
NaN
if none.public double maximum()
NaN
if none.public double span()
public double sum()
public double mean()
NaN
if none.public double rms()
NaN
if none.public double standardDeviation(boolean allPopulation)
accept(…)
methods have a uniform distribution, then the returned value should be close to
sqrt(span2 / 12)
. If they have a
Gaussian distribution (which is the most common case), then the returned value
is related to the error
function.
As a reminder, the table below gives the probability for a sample value to be inside the mean ± n × deviation range, assuming that the distribution is Gaussian (first column) or assuming that the distribution is uniform (second column).
n | Gaussian | uniform |
---|---|---|
0.5 | 69.1% | 28.9% |
1.0 | 84.2% | 57.7% |
1.5 | 93.3% | 86.6% |
2.0 | 97.7% | 100% |
3.0 | 99.9% | 100% |
allPopulation
- true
if sample values given to accept(…)
methods were the totality
of the population under study, or false
if they were only a sampling.public Statistics differences()
null
if none.
For example if the sample values given to the accept(…)
methods were y₀,
y₁, y₂ and y₃, then this method returns statistics on
y₁-y₀, y₂-y₁ and y₃-y₂.
The differences between sample values are related to the discrete derivatives as below, where Δx is the constant interval between the x values of the y=f(x) function:
This method returns a non-null value only if thisStatistics derivative = statistics.differences(); derivative.scale(1/Δx); // Shall be invoked only once. Statistics secondDerivative = derivative.differences(); // Do not invoke scale(1/Δx) again.
Statistics
instance has been created by a
call to the forSeries(…)
method with a non-empty differenceNames
array.
More generally, calls to this method can be chained up to differenceNames.length
times for
fetching second or higher order derivatives, as in the above example.null
if not calculated by this object.forSeries(CharSequence, CharSequence[])
,
scale(double)
public String toString()
Number of values: 8726 Minimum value: 6.853 Maximum value: 8.259 Mean value: 7.421 Root Mean Square: 7.846 Standard deviation: 6.489
toString
in class Object
StatisticsFormat
public Statistics clone()
public int hashCode()
Copyright © 2010–2014 The Apache Software Foundation. All rights reserved.