Stat

The base interface for all statistical accumulators. Implementations accumulate a streaming view of some input, expose the current state as an immutable Result via read, and merge another snapshot in via merge.

Five modality sub-interfaces refine the Stat contract by the shape of the input observation: SeriesStat / DiscreteStat / PairedStat / VectorStat / RegressionStat. Picking the right modality is the first design decision when adding a new stat; everything else falls out of it.

The full lifecycle (update / read / merge) is shown end-to-end below.

Every modality's update takes a per-observation weight, interpreted consistently with the stat's mathematical role: weighted means take it as the observation weight, sums multiply by it, histograms add it to the destination bin. A weight of 1 (the default) is the unweighted case.

Four guarantees hold across every stat:

• A weight of 0.0 is a no-op. The observation is not folded in and no state changes, whatever the modality. This is not a policy choice but an identity: every weighted recurrence in the library, evaluated at w = 0, reduces to the identity, so a stat that moved on a zero weight would simply be wrong.

• A weight of NaN is a no-op too, for a related reason: a weight is the multiplicity of an observation, and NaN is not a multiplicity. It carries no observation, so there is nothing to fold in.

• A weight of +Infinity or -Infinity is a no-op, by the same argument: an infinity is not a multiplicity either. +Infinity has a tempting reading, since the weighted-mean update tends to 1 and so the mean would tend to the observed value, but the recurrences reach that limit through Infinity / Infinity and report NaN rather than the limit. Pinning a stat to a value is a different operation and deserves to be asked for directly rather than encoded as an infinite weight. A non-finite value still propagates; see below.

• A negative weight carries whatever meaning is standard for that particular statistic. For the accumulating families that is a downdate: it removes an observation previously folded in. Where a statistic has no sensible inverse, or where the update would corrupt the accumulator rather than merely give a surprising answer, it throws IllegalArgumentException instead. Each stat's own KDoc says which applies; there is deliberately no library-wide answer, because subtraction is well defined for some statistics and not others.

A non-finite value - NaN or either infinity - is the opposite case, and the asymmetry is deliberate: it is not filtered. It is a real observation whose magnitude happens to be unusable, so it propagates into the accumulator exactly as IEEE-754 and the standard library propagate it, and the stat reads back a non-finite number from then on. No stat silently discards a value, because a stat that under-reported the data it was given would be lying about its own sample count, and none of them can know whether a caller's NaN means "no reading" or a bug in the caller's arithmetic.

Exactly one thing is guaranteed here, and it is worth being blunt about how narrow it is: a non-finite value never throws. That is the whole of it. Such a value is allowed to poison the stat permanently, and in the accumulating families it does - a NaN folded into a mean is reported for ever, and no later observation clears it. What is ruled out is a gap in the input becoming an outage in the caller. Beyond that, what a stat does with a non-finite value is the stat's own business, and the behaviour legitimately differs: an accumulator propagates it, a counting stat records an observation it cannot represent, and an extremum ignores it because NaN compares false against everything. That last property also means a NaN lands in whichever bucket a bucketing stat reaches by fallthrough.

A caller who needs more than the no-throw guarantee asks for it explicitly, with filterFinite. That drops any update carrying a non-finite input, across whichever inputs the modality has, and it is the supported way to keep such observations out of a stat. Note that it is stronger than filtering on NaN alone: an infinity passes every ordering comparison the expression AST can express, so !isNaN() lets one through.

Domain restrictions are a separate matter and still apply. HdrHistogramStat takes non-negative values only, so it refuses -Infinity for the same reason it refuses -5.0. That is the stat's domain, not a non-finiteness rule.

Callers who want NaN dropped should say so upstream, where the intent is explicit and reviewable, rather than relying on each stat to guess:

Mean.filter(!X.isNaN())

Class labels are a separate matter and not an exception to the above. A stat that indexes by label requires an exact non-negative integer in range, and NaN fails that requirement alongside 1.5 and -3; such observations are ignored, as those stats' own KDoc states.

Checks beyond that are the caller's responsibility. Stats validate only where the alternative is corrupted state, not to police inputs.

How that resolves per family, surveyed across the catalogue rather than assumed:

• Additive (sums, counts, rates, decayed sums): subtraction, exactly as you would expect. Nothing to guard.

• Welford (mean, variance, moments): a downdate that inverts the update exactly. The one rejected case is a downdate that would take the accumulated weight to zero or below, since every step divides by the new total and the accumulator would be left permanently non-finite.

• EWMA and decay: a downdate. Over-subtracting drives the accumulated weight negative, which is reported rather than hidden and recovers as soon as positive weight arrives. DecayingMeanStat reports NaN while the decayed weight is negative, since there is no meaningful mean of a negative amount of evidence; that is a sentinel, not a wedged state.

• Counting (histograms, threshold buckets): the bin is a signed accumulation rather than a population count, so subtraction can take a bin below zero. Guarding it would break the legitimate case of retracting an earlier observation.

• Monotone sketches (HyperLogLog, Bloom, MinHash): no inverse exists, since these only ever set bits or take maxima. They ignore non-positive weights.

NegativeWeightSemanticsTest pins each of these.

Type Parameters

Samples

val mean = MeanStat()
for (x in doubleArrayOf(1.0, 2.0, 3.0)) mean.update(x)
val snapshot = mean.read()
println(snapshot.mean) // 2.0

val peer = MeanStat()
for (x in doubleArrayOf(4.0, 5.0)) peer.update(x)
mean.merge(peer.read())
println(mean.read().mean) // 3.0

Inheritors