kumulant

CountMinSketchStat

class CountMinSketchStat(val depth: Int = StatDefaults.COUNT_MIN_SKETCH_DEPTH, val width: Int = StatDefaults.COUNT_MIN_SKETCH_WIDTH, val seed: Long = StatDefaults.COUNT_MIN_SKETCH_SEED, val hasher: LongHasher = SplitMix64, val concurrency: Concurrency = Concurrency.None) : DiscreteStat<CountMinSketchResult> (source)

CountStat-MinStat sketch - a probabilistic frequency estimator over a depth x width matrix of counters. Each update hashes the value with depth independent salts (derived from seed) through the hasher (default SplitMix64) and increments one counter per row; the estimated count for any value is the minimum counter across rows.

Estimates are one-sided overestimates: estimate(x) >= true count(x) always, with the overestimate bounded by 2 * totalSeen / width with high probability over the salt choice. Memory is depth * width Longs; mergeable element-wise when depth, width, and seed match.

width must be a power of two so that the hash maps to an index via masking.

Use cases: point-frequency estimation for heavy-hitter detection, per-key counters under bounded memory, top-k via paired SpaceSavingStat.

Memory: O(depth · width) Longs.

Update: O(depth) per observation; depth independent atomic adds.

Concurrency: Striped atomic adds on independent rows. Lock-free and exact under every Concurrency level; increments commute, and racing writers on the same value just bump the same cells.

Constructors

CountMinSketchStat

constructor(depth: Int = StatDefaults.COUNT_MIN_SKETCH_DEPTH, width: Int = StatDefaults.COUNT_MIN_SKETCH_WIDTH, seed: Long = StatDefaults.COUNT_MIN_SKETCH_SEED, hasher: LongHasher = SplitMix64, concurrency: Concurrency = Concurrency.None)(source)

Properties

concurrency

open override val concurrency: Concurrency(source)

Thread-safety mode fixed at construction. See Concurrency for the shared contract and the implementation's KDoc for its cell and lock strategy.

depth

hasher

Mixer applied to each value xor rowSalt; defaults to SplitMix64.

seed

width

Functions

create

open override fun create(concurrency: Concurrency? = null): CountMinSketchStat(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

open override fun merge(values: CountMinSketchResult, 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

open override fun read(timestampNanos: Long = currentTimeNanos()): CountMinSketchResult(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

open override fun reset()(source)

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

validateMerge

open override fun validateMerge(values: CountMinSketchResult)(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.

Link copied to clipboard
open fun update(value: Long, weight: Double = 1.0)

Record value with weight at the current monotonic time.

open override fun update(value: Long, timestampNanos: Long, weight: Double = 1.0)

Record value with weight at timestampNanos.

update

open override fun update(value: Long, timestampNanos: Long, weight: Double = 1.0)(source)

Record value with weight at timestampNanos.