com.eignex.kumulant/stat/regression/glm/DiagonalRegressionStat

DiagonalRegressionStat

class DiagonalRegressionStat(val featureSize: Int, val priorPrecision: Double = 1.0, val learningRate: ScalarExpr = ConstantRate(1.0), val penalty: Penalty = Penalty.None, val link: Link = Link.Identity, val concurrency: Concurrency = Concurrency.None) : RegressionStat<DiagonalRegressionResult> (source)

Generalised linear regression with a factorised Gaussian posterior - each coefficient gets its own running precision, but cross-coefficient correlations are dropped.

Update rule (Newton-style with diagonal Hessian, canonical Link):

eta               = bias + Sum w_i * x_i
mu                = link.invMean(eta)
curvature         = link.curvature(eta)
precision_i      += weight * curvature * x_i^2
w_i              -= eta_t(step) * weight * grad_i / precision_i
biasPrecision    += weight * curvature
bias             += eta_t(step) * weight * (y - mu) / biasPrecision

where grad_i = (mu - y) * x_i plus any penalty-specific term. Reduces to the Gaussian / MSE case when link = Link.Identity (then curvature = 1, mu = eta).

Posterior samples are independent per coordinate: w_i ~ N(weights[i], 1/precision[i]).

Sparse-aware: precision and weight updates only fire where x_i != 0 (matching the diagonal-Hessian semantics; coordinates absent from this observation contribute no curvature). Penalty handling:

Penalty.None: no regularisation.
Penalty.L2: grad_i += lambda * w_i on touched coords (coordinate-descent style).
Penalty.L1: proximal soft-thresholding on touched coords after the gradient step, threshold scaled by eta * weight * lambda / precision_i.

Use cases: high-dimensional online regression where marginal posteriors suffice (per-coordinate uncertainty without joint covariance); sparse feature spaces, click-prediction style models. Reach for BayesianRegressionStat when feature correlations matter; for StochasticRegressionStat when SGD's even-cheaper per-update cost is required.

Memory: O(featureSize); weights + per-coord precisions + bias pair.

Update: O(nnz(x)) per observation; sparse-aware over the touched coordinates of x rather than the full feature width.

Concurrency: Body serialised by an internal lock under any concurrent Concurrency level (no-op under Concurrency.None). Exact under every level up to floating-point reorder ULPs.

Constructors

DiagonalRegressionStat

constructor(featureSize: Int, priorPrecision: Double = 1.0, learningRate: ScalarExpr = ConstantRate(1.0), penalty: Penalty = Penalty.None, link: Link = Link.Identity, concurrency: Concurrency = Concurrency.None)(source)

Properties

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.

featureSize

open override val featureSize: Int(source)

Number of features expected in x on each update. Mismatched lengths throw.

learningRate

val learningRate: ScalarExpr(source)

Per-step learning-rate schedule applied to coefficient updates.

link

val link: Link(source)

Canonical GLM link; Link.Identity is the classical Gaussian factorised posterior.

penalty

val penalty: Penalty(source)

Regularisation applied during the gradient step; defaults to plain Newton-SGD.

priorPrecision

val priorPrecision: Double(source)

Initial per-coordinate precision (inverse variance) seeded into every weight.

Functions

create

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

Coefficient-wise precision-weighted combine (the standard formula for independent normals). Cross-feature correlations are dropped, consistent with the diagonal model.

read

open override fun read(timestampNanos: Long = currentTimeNanos()): DiagonalRegressionResult(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(x: VectorView, y: Double, weight: Double = 1.0)

Record an (x, y) observation with the given weight at the current time.

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

Convenience overload that wraps x as a DenseVector.

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

Timestamped convenience overload that wraps x as a DenseVector.

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

Record an (x, y) observation at timestampNanos with the given weight.

update

open override fun update(x: VectorView, y: Double, timestampNanos: Long, weight: Double = 1.0)(source)

Record an (x, y) observation at timestampNanos with the given weight.