Stat
Base contract for statistical accumulators. Observations update mutable state; read returns a Result snapshot and merge folds a compatible snapshot into it.
Input shapes are defined by SeriesStat, DiscreteStat, PairedStat, VectorStat, and RegressionStat. Their update methods share these weight rules:
1.0is the unweighted case; other finite weights scale the observation's contribution.Zero and non-finite weights are no-ops.
Negative weights downdate statistics with an inverse. Other statistics reject or ignore them as documented by the implementation. Welford accumulators reject a downdate that would leave a non-positive total weight.
Non-finite observation values follow each statistic's arithmetic and comparisons: means can become NaN, extrema ignore NaN, and buckets may use a fallthrough bin. Domain restrictions still apply, such as non-negative histogram inputs. Classifiers ignore labels that are not exact integers in their configured class range. Use filterFinite to discard updates with non-finite inputs before they reach the accumulator.
Timestamps are nanoseconds from a consistent clock. Default timestamps use a process-local monotonic clock; replayed updates and reads must use a common origin. Time-independent statistics ignore timestamps.
Every built-in stat merges compatible snapshots. Exact formulas are used where sufficient state is available; implementations document approximations and any state omitted from snapshots. Thread safety follows concurrency.
Type Parameters
Snapshot type returned by read.
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.0Inheritors
Properties
concurrency
Thread-safety mode fixed at construction. See Concurrency for the shared contract and the implementation's KDoc for its cell and lock strategy.
Functions
create
Create an independent accumulator at the configured baseline. A null concurrency preserves this accumulator's mode; a non-null value overrides it. Modality subtypes narrow the return type to preserve the input shape.
merge
Fold a compatible snapshot values into this accumulator at timestampNanos. Implementations document whether the combine is exact or approximate and which state the snapshot omits. The source accumulator is unaffected.
Time-dependent statistics, such as windows, place the snapshot at timestampNanos, which must share the clock the caller uses for updates and reads. Time-independent statistics ignore it.
read
Return the current result evaluated at timestampNanos. Time-independent statistics ignore the timestamp. Reading does not add an observation.
Snapshot consistency depends on the implementation's synchronisation. Locks protect coupled state under Concurrency.Strict and Concurrency.HighWrite; independently updated cells and JVM striped adders can still yield a best-effort snapshot. Concurrency.Relaxed permits drift across coupled cells.
reset
Restore the configured baseline, including any prior seed. Preserves the configuration and concurrency.