kumulant

Stat

interface Stat<R : Result>(source)

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.0 is 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

R

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

Inheritors

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

abstract fun create(concurrency: Concurrency? = null): Stat<R>(source)

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

abstract fun merge(values: R, timestampNanos: Long = currentTimeNanos())(source)

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

abstract fun read(timestampNanos: Long = currentTimeNanos()): R(source)

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

abstract fun reset()(source)

Restore the configured baseline, including any prior seed. Preserves the configuration and concurrency.

validateMerge

open fun validateMerge(values: R)(source)

Validate values for merge without changing accumulator state. Containers validate every child before merging any of them. Successful validation checks compatibility; it does not make a concurrent merge transactional.