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)
Where \ is the set difference.
For the field
#stdDev the following rules apply:
- If count
- 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:
- if weight < 0 then
#subtract(double,double) is used instead of
#add(double,double) with weight = -weight and vice versa.
- if weight = +-inf or weight = NaN then the Stats object goes into the
invalid state.
- if value = +-inf or value = NaN then the Stats object goes into the
invalid state.
- if weight = 0 then the value gets ignored.
- Otherwise the fields get updated by the implementation's best effort.
For
#count the following rules apply
- If
#count goes below zero then all fields are set to
Double.NaN
except the
#count field which gets tracked
normally.
- If
#count = 0 then the Stats object goes into the initial state.
- If
#count > 0 for the first time, then the Stats object goes into
initial state and gets updated with the corresponding value and weight.