Class Statistics
- All Implemented Interfaces:
- Serializable,- Cloneable,- DoubleConsumer,- LongConsumer
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 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.
Examples
The following examples assume that a y=f(x) function is defined. A simple usage is: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:
Defined in the sis-utility module
- 
Constructor SummaryConstructorsConstructorDescriptionStatistics(CharSequence name) Constructs an initially empty set of statistics.Statistics(CharSequence name, int countNaN, int count, double minimum, double maximum, double mean, double standardDeviation, boolean allPopulation) Constructs a set of statistics initialized to the given values.
- 
Method SummaryModifier and TypeMethodDescriptionvoidaccept(double sample) Updates statistics for the specified floating-point sample value.voidaccept(long sample) Updates statistics for the specified integer sample value.clone()Returns a clone of this statistics.voidcombine(Statistics stats) Updates statistics with all samples from the specifiedstats.intcount()Returns the number of samples, excludingNaNvalues.intReturns the number ofNaNsamples.Returns the statistics on the differences between sample values, ornullif none.booleanCompares this statistics with the specified object for equality.static StatisticsforSeries(CharSequence name, CharSequence... differenceNames) Constructs a newStatisticsobject which will also compute finite differences up to the given order.intReturns a hash code value for this statistics.doublemaximum()Returns the maximum sample value, orNaNif none.doublemean()Returns the mean value, orNaNif none.doubleminimum()Returns the minimum sample value, orNaNif none.name()Returns the name of the phenomenon for which this object is collecting statistics.voidreset()Resets this object state as if it was just created.doublerms()Returns the root mean square, orNaNif none.voidscale(double factor) Multiplies the statistics by the given factor.doublespan()doublestandardDeviation(boolean allPopulation) Returns the standard deviation.doublesum()Returns the sum, or 0 if none.Returns a string representation of this statistics.Methods inherited from interface DoubleConsumerandThenMethods inherited from interface LongConsumerandThen
- 
Constructor Details- 
StatisticsConstructs 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, or- nullif none. If non-null, it will be shown as column header in the table formatted by- StatisticsFormat.
 
- 
Statisticspublic Statistics(CharSequence name, int countNaN, int count, double minimum, double maximum, double mean, double standardDeviation, boolean allPopulation) Constructs a set of statistics initialized to the given values. ThecountNaNandcountarguments must be positive. Ifcountis 0, all followingdoublearguments are ignored. Otherwise the following restrictions apply:- minimumand- maximumarguments are mandatory and cannot be- NaN.
- meanargument is mandatory (cannot be NaN) if- standardDeviationis not NaN.
- meanand- standardDeviationarguments can be both- NaNif unknown, but statistics initialized that way will always return NaN from- sum(),- mean(),- rms()and- standardDeviation(boolean)methods.
 - Parameters:
- name- the phenomenon for which this object is collecting statistics, or- nullif none.
- countNaN- the number of- NaNsamples.
- count- the number of samples, excluding- NaNvalues.
- minimum- the minimum sample value. Ignored if- countis zero.
- maximum- the maximum sample value. Ignored if- countis zero.
- mean- the mean value. Ignored if- countis zero.
- standardDeviation- the standard deviation. Ignored if- countis zero.
- allPopulation-- trueif sample values were the totality of the population under study, or- falseif they were only a sampling.
- Since:
- 1.2
 
 
- 
- 
Method Details- 
forSeriesConstructs a newStatisticsobject 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 Statisticsobject 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); differenceNamesarray:- 0 if no differences are needed (equivalent to direct instantiation of a new
       Statisticsobject).
- 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, or- nullif 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 cannot be null, but can contain null elements.
- Returns:
- the newly constructed, initially empty, set of statistics.
- See Also:
 
- 0 if no differences are needed (equivalent to direct instantiation of a new
       
- 
nameReturns the name of the phenomenon for which this object is collecting statistics. If non-null, 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 nullif none.
 
- 
resetpublic 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.
- 
acceptpublic void accept(double sample) Updates statistics for the specified floating-point sample value.NaNvalues increment the NaN count, but are otherwise ignored.- Specified by:
- acceptin interface- DoubleConsumer
- Parameters:
- sample- the sample value (may be NaN).
- See Also:
 
- 
acceptpublic void accept(long sample) Updates statistics for the specified integer sample value. For very large integer values (greater than 252 in magnitude), this method may be more accurate than theaccept(double)version.- Specified by:
- acceptin interface- LongConsumer
- Parameters:
- sample- the sample value.
- See Also:
 
- 
combineUpdates 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 to- this.
 
- 
scalepublic 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.
 
- 
countNaNpublic int countNaN()Returns the number ofNaNsamples.NaNsamples are ignored in all other statistical computation. This method count them for information purpose only.- Returns:
- the number of NaN values.
 
- 
countpublic int count()Returns the number of samples, excludingNaNvalues.- Returns:
- the number of sample values, excluding NaN.
 
- 
minimumpublic double minimum()Returns the minimum sample value, orNaNif none.- Returns:
- the minimum sample value, or NaN if none.
 
- 
maximumpublic double maximum()Returns the maximum sample value, orNaNif none.- Returns:
- the maximum sample value, or NaN if none.
 
- 
spanpublic double span()- Returns:
- the span of sample values, or NaN if none.
 
- 
sumpublic double sum()Returns the sum, or 0 if none. May also be NaN if that value was explicitly specified to the constructor.- Returns:
- the sum, or 0 if none.
 
- 
meanpublic double mean()Returns the mean value, orNaNif none.- Returns:
- the mean value, or NaN if none.
 
- 
rmspublic double rms()Returns the root mean square, orNaNif none.- Returns:
- the root mean square, or NaN if none.
 
- 
standardDeviationpublic 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-- trueif sample values given to- accept(…)methods were the totality of the population under study, or- falseif they were only a sampling.
- Returns:
- the standard deviation.
 
- 
differencesReturns the statistics on the differences between sample values, ornullif 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 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. Statisticsinstance has been created by a call to theforSeries(…)method with a non-emptydifferenceNamesarray. More generally, calls to this method can be chained up todifferenceNames.lengthtimes for fetching second or higher order derivatives, as in the above example.- Returns:
- the statistics on the differences between consecutive sample values,
         or nullif not calculated by this object.
- See Also:
 
- 
toStringReturns 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 
- 
cloneReturns a clone of this statistics.
- 
hashCodepublic int hashCode()Returns a hash code value for this statistics.
- 
equalsCompares this statistics with the specified object for equality.
 
-