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

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, 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 and Description
Stats()

Method Summary

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, 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.