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);
}