Package weka.experiment

Class Stats

  • All Implemented Interfaces:
    java.io.Serializable, RevisionHandler
    public class Stats
extends java.lang.Object
implements java.io.Serializable, RevisionHandler
    A class to store simple statistics.

    Upon initialization the variables take the following values:

    count = sum = sumSq = 0
    mean = stdDev = min = max = Double.NaN

    This is called the initial state.

    For signaling that a Stats object has been provided with values that hint that something is either wrong with the data used or the algorithm used there is also the invalid state where the variables take the following values:

    count = sum = sumSq = mean = stdDev = min = max = Double.NaN

    Once a Stats object goes into the invalid state it can't change its state anymore.

    A Stats object assumes that only values are subtracted (by using the subtract(double) or subtract(double, double) methods) that have previously been added (by using the add(double) or add(double, double) methods) and the weights must be the same too.
    Otherwise the Stats object's fields' values are implementation defined.

    If the implementation detects a problem then the Stats object goes into the invalid state.

    The fields count, sum, sumSq, min and max are always updated whereas the field mean and stdDev are only guaranteed to be updated after a call to calculateDerived().

    For the fields min and max the following rules apply:

    min(values_added \ values_subtracted) >= min >= min(values_added)
    max(values_added \ values_subtracted) <= max <= max(values_added)

    Where \ is the set difference.

    For the field stdDev the following rules apply:

    1. If count <= 1 then stdDev=Double.NaN.
    2. Otherwise stdDev >= 0 and it should take on the value by best effort of the implementation.
    For the methods add(double), add(double, double), subtract(double) and subtract(double, double) the following rules apply:

    1. if weight < 0 then subtract(double, double) is used instead of add(double, double) with weight = -weight and vice versa.
    2. if weight = +-inf or weight = NaN then the Stats object goes into the invalid state.
    3. if value = +-inf or value = NaN then the Stats object goes into the invalid state.
    4. if weight = 0 then the value gets ignored.
    5. Otherwise the fields get updated by the implementation's best effort.
    For count the following rules apply

    1. If count goes below zero then all fields are set to Double.NaN except the count field which gets tracked normally.
    2. If count = 0 then the Stats object goes into the initial state.
    3. If count > 0 for the first time, then the Stats object goes into initial state and gets updated with the corresponding value and weight.
    Version:
    $Revision: 14074 $
    Author:
    Len Trigg (trigg@cs.waikato.ac.nz)
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      double count
      The number of values seen
      double max
      The maximum value seen, or Double.NaN if no values seen
      double mean
      The mean of values, or Double.NaN if no values seen
      double min
      The minimum value seen, or Double.NaN if no values seen
      double stdDev
      The std deviation of values at the last calculateDerived() call
      double sum
      The sum of values seen
      double sumSq
      The sum of values squared seen

    • Constructor Summary

      Constructors 
      Constructor Description
      Stats()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(double value)
      Adds a value to the observed values
      void add​(double value, double weight)
      Adds a weighted value to the observed values
      void calculateDerived()
      Tells the object to calculate any statistics that don't have their values automatically updated during add.
      java.lang.String getRevision()
      Returns the revision string.
      static void main​(java.lang.String[] args)
      Tests the paired stats object from the command line.
      void subtract​(double value)
      Removes a value to the observed values (no checking is done that the value being removed was actually added).
      void subtract​(double value, double weight)
      Subtracts a weighted value from the observed values
      java.lang.String toString()
      Returns a string summarising the stats so far.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • count

        public double count
        The number of values seen

      • sum

        public double sum
        The sum of values seen

      • sumSq

        public double sumSq
        The sum of values squared seen

      • stdDev

        public double stdDev
        The std deviation of values at the last calculateDerived() call

      • mean

        public double mean
        The mean of values, or Double.NaN if no values seen

      • min

        public double min
        The minimum value seen, or Double.NaN if no values seen

      • max

        public double max
        The maximum value seen, or Double.NaN if no values seen

    • Constructor Detail

      • Stats

        public Stats()

    • Method Detail

      • add

        public void add​(double value)
        Adds a value to the observed values

        It's equivalent to add(value, 1)

        Parameters:
        value - the observed value

      • add

        public void add​(double value,
                double weight)
        Adds a weighted value to the observed values
        Parameters:
        value - the observed value
        weight - the weight of the observed value

      • subtract

        public void subtract​(double value)
        Removes a value to the observed values (no checking is done that the value being removed was actually added).

        It's equivalent to subtract(value, 1)

        Parameters:
        value - the observed value

      • subtract

        public void subtract​(double value,
                     double weight)
        Subtracts a weighted value from the observed values
        Parameters:
        value - the observed value
        weight - the weight of the observed value

      • calculateDerived

        public void calculateDerived()
        Tells the object to calculate any statistics that don't have their values automatically updated during add. Currently updates the standard deviation.

      • toString

        public java.lang.String toString()
        Returns a string summarising the stats so far.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the summary string

      • getRevision

        public java.lang.String getRevision()
        Returns the revision string.
        Specified by:
        getRevision in interface RevisionHandler
        Returns:
        the revision

      • main

        public static void main​(java.lang.String[] args)
        Tests the paired stats object from the command line. reads line from stdin, expecting two values per line.
        Parameters:
        args - ignored.