kumulant API reference

Multi-armed and contextual bandits built on the same Stat / Result foundation as the rest of the library.

Contextual bandits: each round comes with a feature vector, and the reward depends on both the chosen arm and the context. Three families, covering linear / non-linear / non-parametric reward models plus the adversarial-expert case.

Indexless multi-armed bandits. Each round, the bandit picks one of K arms via choose(), the caller observes a reward, and update(arm, value, weight) folds it back into that arm's accumulator. No per-round feature vector; for that, see com.eignex.kumulant.bandit.contextual.

Foundation types every other package builds on. Everything else in the library imports from here: the modality interfaces, the result hierarchy, the cross-cutting result traits, and the concurrency contract.

Typed, named, wire-portable schemas for declaring bags of stats. A StatSchema does three things:

Concrete accumulators grouped by family. Each family lives in its own subpackage; this page is the navigation index.

Online anomaly detectors. All three primitives produce a score(x) method on their result so the same downstream pipeline can consume "how anomalous is this observation?" regardless of which detector generated it.

Probability calibration: diagnosing when a classifier's predicted probabilities are out of step with the empirical positive rate, and two complementary mappings that fix it.

Approximate distinct-count estimators. Both entries take a stream of opaque Long keys (com.eignex.kumulant.core.DiscreteStat) and answer "how many distinct keys have I seen?" in bounded memory. The right pre-step is to hash domain-specific keys through com.eignex.kumulant.math.hash64 / com.eignex.kumulant.math.Hasher64 so the input has uniform 64-bit entropy; value.hashCode().toLong() only provides 32 bits and skews the estimators on low-cardinality domains.

Drift detectors. Each member tracks a running statistic, applies a configurable threshold, and exposes an alarm flag on its result. The three differ in what they assume about the in-control state and how they decide a shift has occurred.

Time-weighted moments. Each observation enters the accumulator with a weight that shrinks toward zero with age, so older observations contribute less. Two parallel sub-families: timestamp-based decay (the Decaying* stats) and step-based EWMA (the Ewma* stats).

Stats whose output is discrete-temporal in shape: state transitions, dwell times, last-seen timestamps, level crossings, peak excursions. They share the streaming-stats discipline but their results carry counts of state changes and timestamps rather than numeric aggregates.

Predictive recurrences with multi-cell state. Their results expose forecast(steps) projections, distinguishing them from the decay family's running-moment shape.

Bounded-memory quantile estimators and histograms. Every entry trades a different precision-versus-cost knob: relative error guarantees, fixed-precision over a known range, reservoir sampling for raw values back, or constant memory at the cost of accuracy.

Throughput estimators. All three implement com.eignex.kumulant.core.HasRate, so a downstream consumer can pull rate (events per second) or per(duration) through one trait regardless of which underlying estimator produced the snapshot.

Family root for the regression-modality stats and the cross-cutting infrastructure they share. The single-output linear-model family lives in glm, the decision-tree and random-forest family in tree. What sits directly in this package is the small set of stats that don't fit either subfamily, plus the strategy types both rely on.

Generalised linear models; the linear-predictor-plus-link family. Every model in this package shares the shape eta = bias + x . weights followed by mu = link.invMean(eta); they differ in how the posterior over weights is maintained.

Online VFDT decision trees and random forests, plus the shared machinery they're built on. The package covers both regression (continuous y) and classification (y in [0, numClasses)) under one consistent shape.

Online evaluation metrics. Inputs are paired (prediction, truth) observations (or richer shapes for distributional metrics) and outputs are accuracy / discrimination / calibration / distributional summaries.

Structural queries on a stream that aren't shaped like a cardinality or a quantile. Four members; each answers a different question.

Exact running aggregates over a stream of scalars. Memory is constant in the stream length; updates are O(1); every entry merges cleanly across parallel workers via Chan-style parallel formulas or commuting cell arithmetic.