Package org.djutils.stats.summarizers

Class Tally

java.lang.Object
org.djutils.stats.summarizers.Tally
All Implemented Interfaces:
Serializable, Statistic, TallyStatistic
Direct Known Subclasses:
EventBasedTally
public class Tally extends Object implements TallyStatistic
The Tally class registers a series of values and provides mean, standard deviation, etc. of the registered values.

Copyright (c) 2002-2024 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, Peter Jacobs , Peter Knoppers
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Object
    semaphore
    the synchronized lock.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Tally(String description)
    Convenience constructor that uses a NoStorageAccumulator to estimate quantiles.
    Tally(String description, QuantileAccumulator quantileAccumulator)
    Constructs a new Tally.

  • Method Summary

    Modifier and Type
    Method
    Description
    double[]
    getConfidenceInterval(double alpha)
    returns the confidence interval on either side of the mean.
    double[]
    getConfidenceInterval(double alpha, ConfidenceInterval side)
    returns the confidence interval based of the mean.
    double
    getCumulativeProbability(double quantile)
    Get, or estimate fraction of registered values between -infinity up to and including a given quantile.
    String
    getDescription()
    Returns the description of the statistic.
    double
    getMax()
    Returns the maximum value of any given observation, or NaN when no observations were registered.
    double
    getMin()
    Returns the minimum value of any given observation, or NaN when no observations were registered.
    long
    getN()
    Return the current number of observations.
    double
    getPopulationExcessKurtosis()
    Return the population excess kurtosis of the registered data.
    double
    getPopulationKurtosis()
    Return the (biased) population kurtosis of the registered data.
    double
    getPopulationMean()
    Returns the population mean of all observations since the initialization.
    double
    getPopulationSkewness()
    Return the (biased) population skewness of the registered data.
    double
    getPopulationStDev()
    Returns the current (biased) population standard deviation of all observations since the initialization.
    double
    getPopulationVariance()
    Returns the current (biased) population variance of all observations since the initialization.
    double
    getQuantile(double probability)
    Compute the quantile for the given probability.
    double
    getSampleExcessKurtosis()
    Return the sample excess kurtosis of the registered data.
    double
    getSampleKurtosis()
    Return the sample kurtosis of the registered data.
    double
    getSampleMean()
    Returns the sample mean of all observations since the initialization.
    double
    getSampleSkewness()
    Return the (unbiased) sample skewness of the registered data.
    double
    getSampleStDev()
    Returns the current (unbiased) sample standard deviation of all observations since the initialization.
    double
    getSampleVariance()
    Returns the current (unbiased) sample variance of all observations since the initialization.
    double
    getSum()
    Return the sum of the values of the observations.
    void
    initialize()
    Initialize the statistic.
    double
    register(double value)
    Process one observed value.
    void
    register(double... values)
    Ingest an array of values.
    static String
    reportFooter()
    Return a string representing a footer for a textual table with a monospaced font that can contain multiple statistics.
    static String
    reportHeader()
    Return a string representing a header for a textual table with a monospaced font that can contain multiple statistics.
    String
    reportLine()
    Return a string representing a line with important statistics values for this statistic, for a textual table with a monospaced font that can contain multiple statistics.
    String
    toString()

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.djutils.stats.summarizers.Statistic

    formatFixed

  • Field Details

    • semaphore

      protected Object semaphore
      the synchronized lock.

  • Constructor Details

    • Tally

      public Tally(String description)
      Convenience constructor that uses a NoStorageAccumulator to estimate quantiles.
      Parameters:
      description - String; the description of this tally

    • Tally

      public Tally(String description, QuantileAccumulator quantileAccumulator)
      Constructs a new Tally.
      Parameters:
      description - String; the description of this tally
      quantileAccumulator - QuantileAccumulator; the input series accumulator that can approximate or compute quantiles.

  • Method Details

    • initialize

      public void initialize()
      Initialize the statistic.
      Specified by:
      initialize in interface Statistic

    • register

      public void register(double... values)
      Ingest an array of values.
      Parameters:
      values - double...; the values to register

    • register

      public double register(double value)
      Process one observed value.
      Parameters:
      value - double; the value to process
      Returns:
      double; the value

    • getDescription

      public String getDescription()
      Returns the description of the statistic.
      Specified by:
      getDescription in interface Statistic
      Returns:
      String; the description of the statistic

    • getMax

      public double getMax()
      Returns the maximum value of any given observation, or NaN when no observations were registered.
      Specified by:
      getMax in interface TallyStatistic
      Returns:
      double; the maximum value of any given observation

    • getMin

      public double getMin()
      Returns the minimum value of any given observation, or NaN when no observations were registered.
      Specified by:
      getMin in interface TallyStatistic
      Returns:
      double; the minimum value of any given observation

    • getN

      public long getN()
      Return the current number of observations.
      Specified by:
      getN in interface Statistic
      Returns:
      long; the number of observations

    • getSum

      public double getSum()
      Return the sum of the values of the observations.
      Returns:
      double; the sum of the values of the observations

    • getSampleMean

      public double getSampleMean()
      Returns the sample mean of all observations since the initialization.
      Returns:
      double; the sample mean

    • getPopulationMean

      public double getPopulationMean()
      Returns the population mean of all observations since the initialization.
      Returns:
      double; the population mean

    • getSampleStDev

      public double getSampleStDev()
      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.
      Returns:
      double; the sample standard deviation

    • getPopulationStDev

      public double getPopulationStDev()
      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.
      Returns:
      double; the population standard deviation

    • getSampleVariance

      public double getSampleVariance()
      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)
      Returns:
      double; the current sample variance of this tally

    • getPopulationVariance

      public double getPopulationVariance()
      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 ]
      Returns:
      double; the current population variance of this tally

    • getSampleSkewness

      public double getSampleSkewness()
      Return the (unbiased) sample skewness of the registered 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.
      Returns:
      double; the sample skewness of the registered data

    • getPopulationSkewness

      public double getPopulationSkewness()
      Return the (biased) population skewness of the registered 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 ] .
      Returns:
      double; the skewness of the registered data

    • getSampleKurtosis

      public double getSampleKurtosis()
      Return the sample kurtosis of the registered 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 ] .
      Returns:
      double; the sample kurtosis of the registered data

    • getPopulationKurtosis

      public double getPopulationKurtosis()
      Return the (biased) population kurtosis of the registered 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 ] .
      Returns:
      double; the population kurtosis of the registered data

    • getSampleExcessKurtosis

      public double getSampleExcessKurtosis()
      Return the sample excess kurtosis of the registered 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.
      Returns:
      double; the sample excess kurtosis of the registered data

    • getPopulationExcessKurtosis

      public double getPopulationExcessKurtosis()
      Return the population excess kurtosis of the registered 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.
      Returns:
      double; the population excess kurtosis of the registered data

    • getQuantile

      public double getQuantile(double probability)
      Compute the quantile for the given probability.
      Parameters:
      probability - double; the probability for which the quantile is to be computed. The value should be between 0 and 1, inclusive.
      Returns:
      double; the quantile for the probability
      Throws:
      IllegalArgumentException - when the probability is less than 0 or larger than 1

    • getCumulativeProbability

      public double getCumulativeProbability(double quantile)
      Get, or estimate fraction of registered values between -infinity up to and including a given quantile.
      Parameters:
      quantile - double; the given quantile
      Returns:
      double; the estimated or observed fraction of registered values between -infinity up to and including the given quantile. When this TallyInterface has registered zero values; this method shall return NaN.
      Throws:
      IllegalArgumentException - when quantile is NaN

    • getConfidenceInterval

      public double[] getConfidenceInterval(double alpha)
      returns the confidence interval on either side of the mean.
      Parameters:
      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.
      Returns:
      double[]; the confidence interval of this tally
      Throws:
      IllegalArgumentException - when alpha is less than 0 or larger than 1

    • getConfidenceInterval

      public double[] getConfidenceInterval(double alpha, ConfidenceInterval side)
      returns the confidence interval based of the mean.
      Parameters:
      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.
      side - ConfidenceInterval; the side of the confidence interval with respect to the mean
      Returns:
      double[]; the confidence interval of this tally
      Throws:
      IllegalArgumentException - when alpha is less than 0 or larger than 1
      NullPointerException - when side is null

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • reportHeader

      public static String reportHeader()
      Return a string representing a header for a textual table with a monospaced font that can contain multiple statistics.
      Returns:
      String; header for the textual table.

    • reportLine

      public String reportLine()
      Return a string representing a line with important statistics values for this statistic, for a textual table with a monospaced font that can contain multiple statistics.
      Specified by:
      reportLine in interface Statistic
      Returns:
      String; line with most important values of the statistic

    • reportFooter

      public static String reportFooter()
      Return a string representing a footer for a textual table with a monospaced font that can contain multiple statistics.
      Returns:
      String; footer for the textual table