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: 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

  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.