com.eignex.kumulant/stat/forecast/SeasonalSmoothingStat

SeasonalSmoothingStat

class SeasonalSmoothingStat(val alphaWeighting: DecayWeighting.Alpha, val betaWeighting: DecayWeighting.Alpha, val gammaWeighting: DecayWeighting.Alpha, val period: Int, val mode: SeasonalMode = SeasonalMode.Additive, val phi: Double = 1.0, val concurrency: Concurrency = Concurrency.None) : SeriesStat<SeasonalSmoothingResult> (source)

Triple exponential smoothing (Holt-Winters): adds a seasonal component of period to HoltStat's level/trend recurrence. Supports additive and multiplicative seasonality.

Additive recurrence (with a = correction(alpha, weight) and analogous b, g, and k the current seasonal-slot index):

sOld   = seasons[k]
prev   = level
level  = a * (value - sOld) + (1 - a) * (prev + phi * trend)
trend  = b * (level - prev) + (1 - b) * phi * trend
seasons[k] = g * (value - level) + (1 - g) * sOld
k      = (k + 1) mod period

Multiplicative is the same shape with subtraction replaced by division and addition by multiplication. The first period updates seed the seasonal vector (additive: from the residual value - level; multiplicative: from value / level, falling back to 1.0 if level == 0.0).

Use cases: short-horizon forecasting of streams with a recurring cycle on top of a level and trend; pairs with HoltStat when no seasonal component is present.

Memory: O(period); three scalar cells plus a season array plus a lock.

Update: O(1); single seasonal slot touched per update.

Concurrency: Order-dependent recurrence, same model as HoltStat and com.eignex.kumulant.stat.decay.EwmaMeanStat. Concurrency.Strict and Concurrency.HighWrite lock the body so each update is atomic; Concurrency.Relaxed drops the lock and the level/trend/seasonal cells race independently with bounded drift; never throws.

Constructors

SeasonalSmoothingStat

constructor(alphaWeighting: DecayWeighting.Alpha, betaWeighting: DecayWeighting.Alpha, gammaWeighting: DecayWeighting.Alpha, period: Int, mode: SeasonalMode = SeasonalMode.Additive, phi: Double = 1.0, concurrency: Concurrency = Concurrency.None)(source)

constructor(alpha: Double, beta: Double, gamma: Double, period: Int, mode: SeasonalMode = SeasonalMode.Additive, phi: Double = 1.0, concurrency: Concurrency = Concurrency.None)(source)

Properties

alpha

val alpha: Double(source)

Level smoothing factor.

alphaWeighting

val alphaWeighting: DecayWeighting.Alpha(source)

Per-observation smoothing schedule for the level.

beta

val beta: Double(source)

Trend smoothing factor.

betaWeighting

val betaWeighting: DecayWeighting.Alpha(source)

Per-observation smoothing schedule for the trend.

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.

gamma

val gamma: Double(source)

Seasonal smoothing factor.

gammaWeighting

val gammaWeighting: DecayWeighting.Alpha(source)

Per-observation smoothing schedule for the seasonal vector.

mode

val mode: SeasonalMode(source)

Seasonal coupling; defaults to SeasonalMode.Additive.

period

val period: Int(source)

Length of the seasonal cycle in updates.

phi

val phi: Double(source)

Trend damping factor in (0, 1]; 1.0 is plain Holt-Winters.

Functions

create

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

merge

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

Fold another accumulator's snapshot into this one. The unit of merge is the immutable Result; not a live Stat; which is what lets the merge cross a process boundary. Many workers track slices of the same stream, call read periodically, ship snapshots to a coordinator, and the coordinator merges them in.

Most stat families implement merge exactly (Chan-style parallel formulas for Welford, cell-wise additions for histograms, cell-wise max for HLL). SGD-based regressors merge approximately; they have no second-moment information for the principled combine. Each stat's KDoc documents its merge semantics.

read

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

reset

open override fun reset()(source)

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(value: Double, weight: Double = 1.0)

Record an observation with the given weight, stamped at the current time.

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

Record an observation at timestampNanos with the given weight. Stats that consume time (rates, decay, windowing) use this as the ordering signal; pass a monotonic stamp when feeding from a replay log.

update

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