Package weka.experiment

Class Stats

java.lang.Object
weka.experiment.Stats
All Implemented Interfaces:
Serializable, RevisionHandler
public class Stats extends Object implements 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: 14072 $
Author:
Len Trigg (trigg@cs.waikato.ac.nz)
See Also:

  • 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

    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.
    String
    getRevision()
    Returns the revision string.
    static void
    main(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
    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 Details

    • 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 Details

    • Stats

      public Stats()

  • Method Details

    • 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 String toString()
      Returns a string summarising the stats so far.
      Overrides:
      toString in class Object
      Returns:
      the summary string

    • getRevision

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

    • main

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