Class Statistics
 Object

 Statistics

 All Implemented Interfaces:
Serializable
,Cloneable
,DoubleConsumer
,LongConsumer
public class Statistics extends Object implements DoubleConsumer, LongConsumer, Cloneable, Serializable
Holds some statistics derived from a series of sample values. Given a series of y₀, y₁, y₂, y₃, etc… samples, this class computes the minimum, maximum, mean, root mean square and standard deviation of the given samples.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 approximately 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 abovecited statistical values are set toNaN
. The statistics are updated every time anaccept(double)
method is invoked with a nonNaN value.ExamplesThe following examples assume that a y=f(x) function is defined. A simple usage is:
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);
 Since:
 0.3
 See Also:
 Serialized Form
Defined in the
sisutility
module


Constructor Summary
Constructors Constructor Description Statistics(CharSequence name)
Constructs an initially empty set of statistics.

Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
accept(double sample)
Updates statistics for the specified floatingpoint 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 specifiedstats
.int
count()
Returns the number of samples, excludingNaN
values.int
countNaN()
Returns the number ofNaN
samples.Statistics
differences()
Returns the statistics on the differences between sample values, ornull
if none.boolean
equals(Object object)
Compares this statistics with the specified object for equality.static Statistics
forSeries(CharSequence name, CharSequence... differenceNames)
Constructs a newStatistics
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, orNaN
if none.double
mean()
Returns the mean value, orNaN
if none.double
minimum()
Returns the minimum sample value, orNaN
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, orNaN
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.
Methods inherited from interface DoubleConsumer
andThen

Methods inherited from interface LongConsumer
andThen




Constructor Detail

Statistics
public Statistics(CharSequence name)
Constructs an initially empty set of statistics. The count() and thesum()
are initialized to zero and all other statistical values are initialized toDouble.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. Parameters:
name
 the phenomenon for which this object is collecting statistics, ornull
if none. If nonnull, then this name will be shown as column header in the table formatted byStatisticsFormat
.


Method Detail

forSeries
public static Statistics forSeries(CharSequence name, CharSequence... differenceNames)
Constructs a newStatistics
object which will also compute finite differences up to the given order. If the values to be given to theaccept(…)
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: 0 if no differences are needed (equivalent to direct instantiation of a new
Statistics
object).  1 for computing the statistics on the differences between consecutive samples (proportional to the statistics on the first discrete derivatives) in addition to the sample statistics.
 2 for computing also the statistics on the differences between consecutive differences (proportional to the statistics on the second discrete derivatives) in addition to the above.
 etc.
 Parameters:
name
 the phenomenon for which this object is collecting statistics, ornull
if none. If nonnull, then this name will be shown as column header in the table formatted byStatisticsFormat
.differenceNames
 the names of the statistics on differences. The given array can not be null, but can contain null elements. Returns:
 the newly constructed, initially empty, set of statistics.
 See Also:
differences()
 0 if no differences are needed (equivalent to direct instantiation of a new

name
public InternationalString name()
Returns the name of the phenomenon for which this object is collecting statistics. If nonnull, then this name will be shown as column header in the table formatted byStatisticsFormat
. Returns:
 the phenomenon for which this object is collecting statistics, or
null
if none.

reset
public void reset()
Resets this object state as if it was just created. The count() and thesum()
are set to zero and all other statistical values are set toDouble.NaN
.

accept
public void accept(double sample)
Updates statistics for the specified floatingpoint sample value.NaN
values increment the NaN count, but are otherwise ignored. Specified by:
accept
in interfaceDoubleConsumer
 Parameters:
sample
 the sample value (may be NaN). See Also:
accept(long)
,combine(Statistics)

accept
public void accept(long sample)
Updates statistics for the specified integer sample value. For very large integer values (greater than 2^{52} in magnitude), this method may be more accurate than theaccept(double)
version. Specified by:
accept
in interfaceLongConsumer
 Parameters:
sample
 the sample value. See Also:
accept(double)
,combine(Statistics)

combine
public void combine(Statistics stats)
Updates statistics with all samples from the specifiedstats
. Invoking this method is equivalent (except for rounding errors) to invokingaccept(…)
for all samples that were added tostats
. Parameters:
stats
 the statistics to be added tothis
.

scale
public void scale(double factor)
Multiplies the statistics by the given factor. The given scale factory is also applied recursively on the differences statistics, if any. Invoking this method transforms the statistics as if every values given to theaccept(…)
had been first multiplied by the given factor.This method is useful for computing discrete derivatives from the differences between sample values. See
differences()
orforSeries(…)
for more information. Parameters:
factor
 the factor by which to multiply the statistics.

countNaN
public int countNaN()
Returns the number ofNaN
samples.NaN
samples are ignored in all other statistical computation. This method count them for information purpose only. Returns:
 the number of NaN values.

count
public int count()
Returns the number of samples, excludingNaN
values. Returns:
 the number of sample values, excluding NaN.

minimum
public double minimum()
Returns the minimum sample value, orNaN
if none. Returns:
 the minimum sample value, or NaN if none.

maximum
public double maximum()
Returns the maximum sample value, orNaN
if none. Returns:
 the maximum sample value, or NaN if none.

span
public double span()
 Returns:
 the span of sample values, or NaN if none.

sum
public double sum()
Returns the sum, or 0 if none. Returns:
 the sum, or 0 if none.

mean
public double mean()
Returns the mean value, orNaN
if none. Returns:
 the mean value, or NaN if none.

rms
public double rms()
Returns the root mean square, orNaN
if none. Returns:
 the root mean square, or NaN if none.

standardDeviation
public double standardDeviation(boolean allPopulation)
Returns the standard deviation. If the sample values given to theaccept(…)
methods have a uniform distribution, then the returned value should be close tosqrt(span² / 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).
Probability values for some standard deviations 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%  Parameters:
allPopulation
true
if sample values given toaccept(…)
methods were the totality of the population under study, orfalse
if they were only a sampling. Returns:
 the standard deviation.

differences
public Statistics differences()
Returns the statistics on the differences between sample values, ornull
if none. For example if the sample values given to theaccept(…)
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 nonnull 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 theforSeries(…)
method with a nonemptydifferenceNames
array. More generally, calls to this method can be chained up todifferenceNames.length
times for fetching second or higher order derivatives, as in the above example. Returns:
 the statistics on the differences between consecutive sample values,
or
null
if not calculated by this object.  See Also:
forSeries(CharSequence, CharSequence[])
,scale(double)

toString
public String toString()
Returns a string representation of this statistics. This string will span multiple lines, one for each statistical value. For example: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
 Overrides:
toString
in classObject
 Returns:
 a string representation of this statistics object.
 See Also:
StatisticsFormat

clone
public Statistics clone()
Returns a clone of this statistics.

hashCode
public int hashCode()
Returns a hash code value for this statistics.

