weka.experiment

## Class Stats

- java.lang.Object
- - weka.experiment.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: 11424 $
  Author:
    Len Trigg (trigg@cs.waikato.ac.nz)
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and 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 at the last calculateDerived() call
    `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 and Description
    `Stats()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 at the last calculateDerived() call

    - #### 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 mean and 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.