package org.djutils.stats.summarizers; import org.djutils.stats.ConfidenceInterval; /** * The Tally interface defines the methods to be implemented by a tally object, which ingests a series of values and provides * mean, standard deviation, etc. of the ingested values. *

* Copyright (c) 2002-2021 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See * for project information https://simulation.tudelft.nl. The DSOL * project is distributed under a three-clause BSD-style license, which can be found at * * https://simulation.tudelft.nl/dsol/3.0/license.html.
* @author Alexander Verbraeck * @author Peter Jacobs * @author Peter Knoppers */ public interface TallyInterface extends BasicTallyInterface { /** * Process one observed value. * @param value double; the value to process * @return double; the value */ double ingest(double value); /** * Return the sum of the values of the observations. * @return double; sum */ double getSum(); /** * Returns the sample mean of all observations since the initialization. * @return double; the sample mean */ double getSampleMean(); /** * Returns the population mean of all observations since the initialization. * @return double; the population mean */ default double getPopulationMean() { return getSampleMean(); } /** * Returns the current (unbiased) sample standard deviation of all observations since the initialization. The sample * standard deviation is defined as the square root of the sample variance. * @return double; the sample standard deviation */ double getSampleStDev(); /** * Returns the current (biased) population standard deviation of all observations since the initialization. The population * standard deviation is defined as the square root of the population variance. * @return double; the population standard deviation */ double getPopulationStDev(); /** * Returns the current (unbiased) sample variance of all observations since the initialization. The calculation of the * sample variance in relation to the population variance is undisputed. The formula is:
*   S2 = (1 / (n - 1)) * [ Σx2 - (Σx)2 / n ]
* which can be calculated on the basis of the calculated population variance σ2 as follows:
*   S2 = σ2 * n / (n - 1)
* @return double; the current sample variance of this tally */ double getSampleVariance(); /** * Returns the current (biased) population variance of all observations since the initialization. The population variance is * defined as:
* σ2 = (1 / n) * [ Σx2 - (Σx)2 / n ] * @return double; the current population variance of this tally */ double getPopulationVariance(); /** * Return the (unbiased) sample skewness of the ingested data. There are different formulas to calculate the unbiased * (sample) skewness from the biased (population) skewness. Minitab, for instance calculates unbiased skewness as:
*   Skewunbiased = Skewbiased [ ( n - 1) / n ] 3/2
* whereas SAS, SPSS and Excel calculate it as:
*   Skewunbiased = Skewbiased √[ n ( n - 1)] / (n - 2)
* Here we follow the last mentioned formula. All formulas converge to the same value with larger n. * @return double; the sample skewness of the ingested data */ double getSampleSkewness(); /** * Return the (biased) population skewness of the ingested data. The population skewness is defined as:
*   Skewbiased = [ Σ ( x - μ ) 3 ] / [ n . S3 ]
* where S2 is the sample variance. So the denominator is equal to [ n . * sample_var3/2 ] . * @return double; the skewness of the ingested data */ double getPopulationSkewness(); /** * Return the sample kurtosis of the ingested data. The sample kurtosis can be defined in multiple ways. Here, we choose the * following formula:
*   Kurtunbiased = [ Σ ( x - μ ) 4 ] / [ ( n - 1 ) . S4 ]
* where S2 is the sample variance. So the denominator is equal to [ ( n - 1 ) . * sample_var2 ] . * @return double; the sample kurtosis of the ingested data */ double getSampleKurtosis(); /** * Return the (biased) population kurtosis of the ingested data. The population kurtosis is defined as:
*   Kurtbiased = [ Σ ( x - μ ) 4 ] / [ n . σ4 ]
* where σ2 is the population variance. So the denominator is equal to [ n . * pop_var2 ] . * @return double; the population kurtosis of the ingested data */ double getPopulationKurtosis(); /** * Return the sample excess kurtosis of the ingested data. The sample excess kurtosis is the sample-corrected value of the * excess kurtosis. Several formulas exist to calculate the sample excess kurtosis from the population kurtosis. Here we * use:
*   ExcessKurtunbiased = ( n - 1 ) / [( n - 2 ) * ( n - 3 )] [ ( n + 1 ) * * ExcessKurtbiased + 6]
* This is the excess kurtosis that is calculated by, for instance, SAS, SPSS and Excel. * @return double; the sample excess kurtosis of the ingested data */ double getSampleExcessKurtosis(); /** * Return the population excess kurtosis of the ingested data. The kurtosis value of the normal distribution is 3. The * excess kurtosis is the kurtosis value shifted by -3 to be 0 for the normal distribution. * @return double; the population excess kurtosis of the ingested data */ double getPopulationExcessKurtosis(); /** * Compute the quantile for the given probability. * @param probability double; the probability for which the quantile is to be computed. The value should be between 0 and 1, * inclusive. * @return double; the quantile for the probability * @throws IllegalArgumentException when the probability is less than 0 or larger than 1 */ double getQuantile(double probability); /** * returns the confidence interval on either side of the mean. * @param alpha double; Alpha is the significance level used to compute the confidence level. The confidence level equals * 100*(1 - alpha)%, or in other words, an alpha of 0.05 indicates a 95 percent confidence level. * @return double[]; the confidence interval of this tally * @throws IllegalArgumentException when alpha is less than 0 or larger than 1 */ double[] getConfidenceInterval(double alpha); /** * returns the confidence interval based of the mean. * @param alpha double; Alpha is the significance level used to compute the confidence level. The confidence level equals * 100*(1 - alpha)%, or in other words, an alpha of 0.05 indicates a 95 percent confidence level. * @param side ConfidenceInterval; the side of the confidence interval with respect to the mean * @return double[]; the confidence interval of this tally * @throws IllegalArgumentException when alpha is less than 0 or larger than 1 * @throws NullPointerException when side is null */ double[] getConfidenceInterval(double alpha, ConfidenceInterval side); }