1 package org.djutils.stats.summarizers;
2
3 import org.djutils.stats.ConfidenceInterval;
4
5 /**
6 * The Tally interface defines the methods to be implemented by a tally object, which ingests a series of values and provides
7 * mean, standard deviation, etc. of the ingested values.
8 * <p>
9 * Copyright (c) 2002-2021 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
10 * for project information <a href="https://simulation.tudelft.nl/" target="_blank"> https://simulation.tudelft.nl</a>. The DSOL
11 * project is distributed under a three-clause BSD-style license, which can be found at
12 * <a href="https://simulation.tudelft.nl/dsol/3.0/license.html" target="_blank">
13 * https://simulation.tudelft.nl/dsol/3.0/license.html</a>. <br>
14 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank"> Alexander Verbraeck</a>
15 * @author <a href="https://www.linkedin.com/in/peterhmjacobs">Peter Jacobs </a>
16 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
17 */
18 public interface TallyInterface extends BasicTallyInterface
19 {
20 /**
21 * Process one observed value.
22 * @param value double; the value to process
23 * @return double; the value
24 */
25 double ingest(double value);
26
27 /**
28 * Return the sum of the values of the observations.
29 * @return double; sum
30 */
31 double getSum();
32
33 /**
34 * Returns the sample mean of all observations since the initialization.
35 * @return double; the sample mean
36 */
37 double getSampleMean();
38
39 /**
40 * Returns the population mean of all observations since the initialization.
41 * @return double; the population mean
42 */
43 default double getPopulationMean()
44 {
45 return getSampleMean();
46 }
47
48 /**
49 * Returns the current (unbiased) sample standard deviation of all observations since the initialization. The sample
50 * standard deviation is defined as the square root of the sample variance.
51 * @return double; the sample standard deviation
52 */
53 double getSampleStDev();
54
55 /**
56 * Returns the current (biased) population standard deviation of all observations since the initialization. The population
57 * standard deviation is defined as the square root of the population variance.
58 * @return double; the population standard deviation
59 */
60 double getPopulationStDev();
61
62 /**
63 * Returns the current (unbiased) sample variance of all observations since the initialization. The calculation of the
64 * sample variance in relation to the population variance is undisputed. The formula is:<br>
65 * <i>S<sup>2</sup> = (1 / (n - 1)) * [ Σx<sup>2</sup> - (Σx)<sup>2</sup> / n ] </i><br>
66 * which can be calculated on the basis of the calculated population variance <i>σ<sup>2</sup></i> as follows:<br>
67 * <i>S<sup>2</sup> = σ<sup>2</sup> * n / (n - 1)</i><br>
68 * @return double; the current sample variance of this tally
69 */
70 double getSampleVariance();
71
72 /**
73 * Returns the current (biased) population variance of all observations since the initialization. The population variance is
74 * defined as:<br>
75 * <i>σ<sup>2</sup> = (1 / n) * [ Σx<sup>2</sup> - (Σx)<sup>2</sup> / n ] </i>
76 * @return double; the current population variance of this tally
77 */
78 double getPopulationVariance();
79
80 /**
81 * Return the (unbiased) sample skewness of the ingested data. There are different formulas to calculate the unbiased
82 * (sample) skewness from the biased (population) skewness. Minitab, for instance calculates unbiased skewness as:<br>
83 * <i>Skew<sub>unbiased</sub> = Skew<sub>biased</sub> [ ( n - 1) / n ]<sup> 3/2</sup></i> <br>
84 * whereas SAS, SPSS and Excel calculate it as:<br>
85 * <i>Skew<sub>unbiased</sub> = Skew<sub>biased</sub> √[ n ( n - 1)] / (n - 2)</i> <br>
86 * Here we follow the last mentioned formula. All formulas converge to the same value with larger n.
87 * @return double; the sample skewness of the ingested data
88 */
89 double getSampleSkewness();
90
91 /**
92 * Return the (biased) population skewness of the ingested data. The population skewness is defined as:<br>
93 * <i>Skew<sub>biased</sub> = [ Σ ( x - μ ) <sup>3</sup> ] / [ n . S<sup>3</sup> ]</i><br>
94 * where <i>S<sup>2</sup></i> is the <b>sample</b> variance. So the denominator is equal to <i>[ n .
95 * sample_var<sup>3/2</sup> ]</i> .
96 * @return double; the skewness of the ingested data
97 */
98 double getPopulationSkewness();
99
100 /**
101 * Return the sample kurtosis of the ingested data. The sample kurtosis can be defined in multiple ways. Here, we choose the
102 * following formula:<br>
103 * <i>Kurt<sub>unbiased</sub> = [ Σ ( x - μ ) <sup>4</sup> ] / [ ( n - 1 ) . S<sup>4</sup> ]</i><br>
104 * where <i>S<sup>2</sup></i> is the <u>sample</u> variance. So the denominator is equal to <i>[ ( n - 1 ) .
105 * sample_var<sup>2</sup> ]</i> .
106 * @return double; the sample kurtosis of the ingested data
107 */
108 double getSampleKurtosis();
109
110 /**
111 * Return the (biased) population kurtosis of the ingested data. The population kurtosis is defined as:<br>
112 * <i>Kurt<sub>biased</sub> = [ Σ ( x - μ ) <sup>4</sup> ] / [ n . σ<sup>4</sup> ]</i><br>
113 * where <i>σ<sup>2</sup></i> is the <u>population</u> variance. So the denominator is equal to <i>[ n .
114 * pop_var<sup>2</sup> ]</i> .
115 * @return double; the population kurtosis of the ingested data
116 */
117 double getPopulationKurtosis();
118
119 /**
120 * Return the sample excess kurtosis of the ingested data. The sample excess kurtosis is the sample-corrected value of the
121 * excess kurtosis. Several formulas exist to calculate the sample excess kurtosis from the population kurtosis. Here we
122 * use:<br>
123 * <i>ExcessKurt<sub>unbiased</sub> = ( n - 1 ) / [( n - 2 ) * ( n - 3 )] [ ( n + 1 ) *
124 * ExcessKurt<sub>biased</sub> + 6]</i> <br>
125 * This is the excess kurtosis that is calculated by, for instance, SAS, SPSS and Excel.
126 * @return double; the sample excess kurtosis of the ingested data
127 */
128 double getSampleExcessKurtosis();
129
130 /**
131 * Return the population excess kurtosis of the ingested data. The kurtosis value of the normal distribution is 3. The
132 * excess kurtosis is the kurtosis value shifted by -3 to be 0 for the normal distribution.
133 * @return double; the population excess kurtosis of the ingested data
134 */
135 double getPopulationExcessKurtosis();
136
137 /**
138 * Compute the quantile for the given probability.
139 * @param probability double; the probability for which the quantile is to be computed. The value should be between 0 and 1,
140 * inclusive.
141 * @return double; the quantile for the probability
142 * @throws IllegalArgumentException when the probability is less than 0 or larger than 1
143 */
144 double getQuantile(double probability);
145
146 /**
147 * Get, or estimate fraction of ingested values between -infinity up to and including a given quantile.
148 * @param quantile double; the given quantile
149 * @return double; the estimated or observed fraction of ingested values between -infinity up to and including the given
150 * quantile. When this TallyInterface has ingested zero values; this method shall return NaN.
151 * @throws IllegalArgumentException when quantile is NaN
152 */
153 double getCumulativeProbability(double quantile) throws IllegalArgumentException;
154
155 /**
156 * returns the confidence interval on either side of the mean.
157 * @param alpha double; Alpha is the significance level used to compute the confidence level. The confidence level equals
158 * 100*(1 - alpha)%, or in other words, an alpha of 0.05 indicates a 95 percent confidence level.
159 * @return double[]; the confidence interval of this tally
160 * @throws IllegalArgumentException when alpha is less than 0 or larger than 1
161 */
162 double[] getConfidenceInterval(double alpha);
163
164 /**
165 * returns the confidence interval based of the mean.
166 * @param alpha double; Alpha is the significance level used to compute the confidence level. The confidence level equals
167 * 100*(1 - alpha)%, or in other words, an alpha of 0.05 indicates a 95 percent confidence level.
168 * @param side ConfidenceInterval; the side of the confidence interval with respect to the mean
169 * @return double[]; the confidence interval of this tally
170 * @throws IllegalArgumentException when alpha is less than 0 or larger than 1
171 * @throws NullPointerException when side is null
172 */
173 double[] getConfidenceInterval(double alpha, ConfidenceInterval side);
174
175 }