kumulant/com.eignex.kumulant.stat.anomaly/HalfSpaceTreesStat

HalfSpaceTreesStat

class HalfSpaceTreesStat(val featureSize: Int, val featureRanges: List<FeatureRange>, val numTrees: Int = 25, val height: Int = 8, val windowSize: Int = 250, val randomSeed: Int = 0, val concurrency: Concurrency = Concurrency.None) : VectorStat<HalfSpaceTreesResult> (source)

Online Half-Space-Trees anomaly detector (Tan, Ting & Liu 2011). An ensemble of pre-built random half-space trees of fixed depth height; each internal node picks a random feature and a random threshold from featureRanges at construction. Trees do not grow; the algorithm tracks two mass profiles per leaf; a reference window and the latest window; and swaps them every windowSize observations. The anomaly score is computed from the reference profile.

Use cases: non-parametric multivariate anomaly detection on streams where the data distribution may shift slowly (reference window keeps the recent profile fresh). Cheap, fully parallel across trees.

Memory: O(numTrees * 2^height); two per-leaf mass arrays plus the immutable tree structure.

Update: O(numTrees * height) per observation (one tree-walk per tree, no growth).

Concurrency: Per-leaf mass updates are striped atomic adds and commute. The periodic window swap (reference <- latest; latest <- 0) takes a single lock fired once every windowSize observations.

Constructors

HalfSpaceTreesStat

constructor(featureSize: Int, featureRanges: List<FeatureRange>, numTrees: Int = 25, height: Int = 8, windowSize: Int = 250, randomSeed: Int = 0, concurrency: Concurrency = Concurrency.None)

Properties

concurrency

open override val concurrency: Concurrency

The thread-safety contract this stat was constructed with. Each stat picks the cell-encoding and lock strategy that honours this contract for its mathematical structure:

featureRanges

val featureRanges: List<FeatureRange>

Per-feature value ranges used to draw random split thresholds at tree build time.

featureSize

val featureSize: Int

Number of input features.

height

val height: Int

Depth of each tree; each tree has 2^height leaves.

numTrees

val numTrees: Int

Number of trees in the ensemble.

randomSeed

val randomSeed: Int

PRNG seed for reproducible tree construction.

windowSize

val windowSize: Int

Observations per window before the reference profile rotates.

Functions

create

open override fun create(concurrency: Concurrency? = null): HalfSpaceTreesStat

Spawn a fresh accumulator with the same configuration. Optionally override the Concurrency; useful for materialising a wire spec at a different concurrency level than the source.

merge

open override fun merge(values: HalfSpaceTreesResult)

Merge folds another snapshot's reference-window masses into this stat's latest window. Tree structures must match exactly; if they don't (e.g. different seeds), the merge throws.

read

open override fun read(timestampNanos: Long = currentTimeNanos()): HalfSpaceTreesResult

Materialise the current state as an immutable Result. Reads never mutate, so the caller can read as often as it likes without affecting the stream.

reset

open override fun reset()

Reset the stat to its prior-seeded baseline. Equivalent to constructing a fresh stat with the same configuration, but in place; keeps the same Concurrency and any per-stat tunables.

update

open fun update(vector: VectorView, weight: Double = 1.0)

Record a vector observation with the given weight at the current time.

open fun update(vector: DoubleArray, weight: Double = 1.0)

Convenience overload that wraps vector as a DenseVector.

open fun update(vector: DoubleArray, timestampNanos: Long, weight: Double = 1.0)

Timestamped convenience overload that wraps vector as a DenseVector.

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

Record a vector observation at timestampNanos with the given weight.

HalfSpaceTreesStat

constructor(featureSize: Int, featureRanges: List<FeatureRange>, numTrees: Int = 25, height: Int = 8, windowSize: Int = 250, randomSeed: Int = 0, concurrency: Concurrency = Concurrency.None)(source)

concurrency

open override val concurrency: Concurrency(source)

The thread-safety contract this stat was constructed with. Each stat picks the cell-encoding and lock strategy that honours this contract for its mathematical structure:

Concurrency.None: single-threaded; no synchronisation. Cheapest path.
Concurrency.Relaxed: lock-free best-effort. Multi-cell stats (Welford-style MeanStat, VarianceStat, MomentsStat) may drift under contention but never throw.
Concurrency.Strict: serialised when needed for full correctness across coupled cells. Sketches always self-serialise; Welford stats lock per update.
Concurrency.HighWrite: optimised for many concurrent writers; JVM uses striped adders for naively additive stats.

Picked at construction; immutable after.

create

open override fun create(concurrency: Concurrency? = null): HalfSpaceTreesStat(source)

Spawn a fresh accumulator with the same configuration. Optionally override the Concurrency; useful for materialising a wire spec at a different concurrency level than the source.

The returned stat is independent: its state starts at the configured baseline, not at the source's current state. Each modality subtype narrows the return type so chaining doesn't lose the modality.

featureRanges

val featureRanges: List<FeatureRange>(source)

Per-feature value ranges used to draw random split thresholds at tree build time.

featureSize

val featureSize: Int(source)

Number of input features.

height

val height: Int(source)

Depth of each tree; each tree has 2^height leaves.

merge

open override fun merge(values: HalfSpaceTreesResult)(source)

Merge folds another snapshot's reference-window masses into this stat's latest window. Tree structures must match exactly; if they don't (e.g. different seeds), the merge throws.

numTrees

val numTrees: Int(source)

Number of trees in the ensemble.

randomSeed

val randomSeed: Int(source)

PRNG seed for reproducible tree construction.

read

open override fun read(timestampNanos: Long = currentTimeNanos()): HalfSpaceTreesResult(source)

Materialise the current state as an immutable Result. Reads never mutate, so the caller can read as often as it likes without affecting the stream.

Snapshot consistency depends on the configured Concurrency. Under Concurrency.Strict / Concurrency.HighWrite a read locks against writers so coupled cells stay consistent. Under Concurrency.Relaxed the cells race and the snapshot may drift by ULPs of the workload under heavy contention; the drift is bounded and the read never throws.

timestampNanos is the read timestamp. Stats that don't care about time silently drop it; stats that do (rates, decay families, recency, windowed wrappers) use it as the ordering signal.