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.

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

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

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