From 72ffd8ec47d9282f936e7b2624f55f943dac5b0d Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:31:06 +0000 Subject: [PATCH] feat(math): add robust LOWESS local regression Cleveland 1979: tricube-weighted local linear/quadratic fits over the k nearest valid samples (asymmetric at edges), Tukey biweight robustness on residuals scaled by 6 MAD, per-point surviving weight fraction, missing-sample interpolation, index or time positions. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Core/Math/LocalRegression.cs | 207 ++++++++++++++++++ .../Math/LocalRegressionTests.cs | 118 ++++++++++ 2 files changed, 325 insertions(+) create mode 100644 src/Titano.Core/Math/LocalRegression.cs create mode 100644 tests/Titano.Core.Tests/Math/LocalRegressionTests.cs diff --git a/src/Titano.Core/Math/LocalRegression.cs b/src/Titano.Core/Math/LocalRegression.cs new file mode 100644 index 00000000..6f2386a6 --- /dev/null +++ b/src/Titano.Core/Math/LocalRegression.cs @@ -0,0 +1,207 @@ +namespace Titano.Core.Mathematics; + +/// Output of ; every array has one entry per input sample. +public sealed class LocalRegressionResult +{ + internal LocalRegressionResult(double[] fitted, double[] robustWeights, double[] survivingFraction, int validCount) + { + Fitted = fitted; + RobustWeights = robustWeights; + SurvivingFraction = survivingFraction; + ValidCount = validCount; + } + + /// Smoothed value at every position, including missing samples (interpolated from their neighbours). + /// NaN only when there is no valid sample at all. + public double[] Fitted { get; } + + /// Tukey biweight each sample carried in the final fit (1 = full inlier, 0 = rejected or missing). + public double[] RobustWeights { get; } + + /// + /// Σ wᵢⱼ·ρⱼ / Σ wᵢⱼ over the window of each position: the share of its distance (tricube × prior) weight + /// that survived robustness. Near 1 for clean windows, lower where samples were rejected. + /// + public double[] SurvivingFraction { get; } + + public int ValidCount { get; } +} + +/// +/// Robust locally weighted regression, LOWESS (Cleveland 1979). Each position is fitted by weighted least squares +/// of degree 1 or 2 over its window nearest valid samples (asymmetric at the edges, so the count stays +/// constant), with tricube distance weights. Robustness iterations reweight samples with Tukey's biweight of the +/// residuals scaled by 6·MAD. Cost O(n·window) per iteration. +/// +public static class LocalRegression +{ + /// Samples; NaN/±∞ mark missing values. + /// Number of nearest valid samples in each local fit (clamped to the valid count). + /// Local polynomial degree, 1 (linear) or 2 (quadratic). + /// Tukey reweighting passes after the initial fit (Cleveland uses 2–3). + /// Non-decreasing positions (e.g. capture seconds); indices when empty. + /// Optional non-negative sample weights; zero marks a sample as missing. + public static LocalRegressionResult Smooth( + ReadOnlySpan y, + int window, + int degree = 1, + int robustIterations = 2, + ReadOnlySpan x = default, + ReadOnlySpan priorWeights = default) + { + ArgumentOutOfRangeException.ThrowIfLessThan(window, 1); + if (degree is not (1 or 2)) throw new ArgumentOutOfRangeException(nameof(degree), "Degree must be 1 or 2."); + ArgumentOutOfRangeException.ThrowIfNegative(robustIterations); + var n = y.Length; + if (!x.IsEmpty && x.Length != n) throw new ArgumentException("x and y lengths differ.", nameof(x)); + if (!priorWeights.IsEmpty && priorWeights.Length != n) throw new ArgumentException("Weight and y lengths differ.", nameof(priorWeights)); + + var pos = new double[n]; + for (var i = 0; i < n; i++) + { + pos[i] = x.IsEmpty ? i : x[i]; + if (!double.IsFinite(pos[i])) throw new ArgumentException("Positions must be finite.", nameof(x)); + if (i > 0 && pos[i] < pos[i - 1]) throw new ArgumentException("Positions must be non-decreasing.", nameof(x)); + } + + var valid = new List(n); + for (var i = 0; i < n; i++) + { + var w = priorWeights.IsEmpty ? 1 : priorWeights[i]; + if (double.IsFinite(y[i]) && w > 0 && double.IsFinite(w)) valid.Add(i); + } + var m = valid.Count; + var fitted = new double[n]; + var robust = new double[n]; + var surviving = new double[n]; + if (m == 0) + { + Array.Fill(fitted, double.NaN); + return new LocalRegressionResult(fitted, robust, surviving, 0); + } + + var vx = new double[m]; + var vy = new double[m]; + var prior = new double[m]; + for (var j = 0; j < m; j++) + { + var i = valid[j]; + vx[j] = pos[i]; + vy[j] = y[i]; + prior[j] = priorWeights.IsEmpty ? 1 : priorWeights[i]; + } + + var q = Math.Min(window, m); + var p = Math.Min(degree, q - 1); + var windows = BuildWindows(pos, vx, q); + var rho = new double[m]; + Array.Fill(rho, 1.0); + var residual = new double[m]; + var scaleFloor = 1e-12 * (1 + Math.Abs(Statistics.Median(vy))); + + for (var iteration = 0; ; iteration++) + { + FitAll(pos, windows, q, vx, vy, prior, rho, p, fitted, surviving); + if (iteration == robustIterations) break; + for (var j = 0; j < m; j++) residual[j] = vy[j] - fitted[valid[j]]; + var mad = Statistics.MedianAbsoluteDeviation(residual, 0); + if (!(mad > scaleFloor)) break; + var c = 6 * mad; + for (var j = 0; j < m; j++) + { + var u = residual[j] / c; + rho[j] = Math.Abs(u) < 1 ? (1 - u * u) * (1 - u * u) : 0; + } + } + + for (var j = 0; j < m; j++) robust[valid[j]] = rho[j]; + return new LocalRegressionResult(fitted, robust, surviving, m); + } + + /// Start of the contiguous block of valid samples nearest to each position + /// (sliding k-nearest-neighbour window; total O(n + m)). + private static int[] BuildWindows(double[] pos, double[] vx, int q) + { + var starts = new int[pos.Length]; + var s = 0; + for (var i = 0; i < pos.Length; i++) + { + var xi = pos[i]; + while (s + q < vx.Length && xi - vx[s] > vx[s + q] - xi) s++; + starts[i] = s; + } + return starts; + } + + private static void FitAll(double[] pos, int[] starts, int q, double[] vx, double[] vy, double[] prior, double[] rho, int degree, double[] fitted, double[] surviving) + { + for (var i = 0; i < pos.Length; i++) + fitted[i] = FitAt(pos[i], starts[i], q, vx, vy, prior, rho, degree, out surviving[i]); + } + + private static double FitAt(double xi, int start, int q, double[] vx, double[] vy, double[] prior, double[] rho, int degree, out double surviving) + { + var end = start + q - 1; + var dMax = Math.Max(xi - vx[start], vx[end] - xi); + // One mean sample spacing beyond the farthest neighbour, so every sample in the window keeps a positive weight. + var h = dMax + (q > 1 ? (vx[end] - vx[start]) / (q - 1) : 0); + if (!(h > 0)) h = 1; + + double s0 = 0, s1 = 0, s2 = 0, s3 = 0, s4 = 0, t0 = 0, t1 = 0, t2 = 0; + double distanceSum = 0, survivingSum = 0; + double r0 = 0, r1 = 0, r2 = 0, r3 = 0, r4 = 0, rt0 = 0, rt1 = 0, rt2 = 0; + for (var j = start; j <= end; j++) + { + var u = (vx[j] - xi) / h; + var a = 1 - Math.Abs(u * u * u); + var wd = a <= 0 ? 0 : a * a * a * prior[j]; + distanceSum += wd; + var w = wd * rho[j]; + survivingSum += w; + var uu = u * u; + s0 += w; + s1 += w * u; + s2 += w * uu; + t0 += w * vy[j]; + t1 += w * u * vy[j]; + r0 += wd; + r1 += wd * u; + r2 += wd * uu; + rt0 += wd * vy[j]; + rt1 += wd * u * vy[j]; + if (degree == 2) + { + s3 += w * uu * u; + s4 += w * uu * uu; + t2 += w * uu * vy[j]; + r3 += wd * uu * u; + r4 += wd * uu * uu; + rt2 += wd * uu * vy[j]; + } + } + surviving = distanceSum > 0 ? survivingSum / distanceSum : 0; + // A window whose every sample was rejected falls back to plain distance weights. + return s0 > 1e-12 * distanceSum + ? Solve(degree, s0, s1, s2, s3, s4, t0, t1, t2) + : Solve(degree, r0, r1, r2, r3, r4, rt0, rt1, rt2); + } + + /// Intercept of the weighted polynomial fit in centred coordinates, degrading to a lower degree when + /// the normal equations are ill-conditioned (e.g. all weight on one sample). + private static double Solve(int degree, double s0, double s1, double s2, double s3, double s4, double t0, double t1, double t2) + { + if (!(s0 > 0)) return double.NaN; + if (degree == 2) + { + var c00 = s2 * s4 - s3 * s3; + var c01 = s1 * s4 - s2 * s3; + var c02 = s1 * s3 - s2 * s2; + var det = s0 * c00 - s1 * c01 + s2 * c02; + if (det > 1e-10 * s0 * s2 * s4) + return (t0 * c00 - s1 * (t1 * s4 - s3 * t2) + s2 * (t1 * s3 - s2 * t2)) / det; + } + var det1 = s0 * s2 - s1 * s1; + if (det1 > 1e-10 * s0 * s2) return (s2 * t0 - s1 * t1) / det1; + return t0 / s0; + } +} diff --git a/tests/Titano.Core.Tests/Math/LocalRegressionTests.cs b/tests/Titano.Core.Tests/Math/LocalRegressionTests.cs new file mode 100644 index 00000000..66b7d158 --- /dev/null +++ b/tests/Titano.Core.Tests/Math/LocalRegressionTests.cs @@ -0,0 +1,118 @@ +using Titano.Core.Mathematics; +using Titano.Testing; + +namespace Titano.Core.Tests.Mathematics; + +public sealed class LocalRegressionTests +{ + [Theory] + [Case(1)] + [Case(2)] + public void ReproducesPolynomialsOfItsDegreeIncludingEdges(int degree) + { + var y = Enumerable.Range(0, 60).Select(i => degree == 1 ? 3 - 0.2 * i : 1 + 0.1 * i - 0.004 * i * i).ToArray(); + var result = LocalRegression.Smooth(y, window: 11, degree: degree, robustIterations: 2); + for (var i = 0; i < y.Length; i++) Assert.Approximately(y[i], result.Fitted[i], 1e-9); + Assert.True(result.SurvivingFraction.All(f => Math.Abs(f - 1) < 1e-12)); + } + + [Test] + public void TimeSpaceWindowsHandleUnevenSpacing() + { + var random = new Random(4); + var x = new double[80]; + for (var i = 1; i < x.Length; i++) x[i] = x[i - 1] + 1 + 9 * random.NextDouble(); + var y = x.Select(v => 5 + 0.01 * v).ToArray(); + var result = LocalRegression.Smooth(y, window: 9, x: x); + for (var i = 0; i < y.Length; i++) Assert.Approximately(y[i], result.Fitted[i], 1e-9); + } + + [Test] + public void TwentyPercentOutliersBarelyMoveTheRobustFit() + { + var random = new Random(21); + var n = 300; + var clean = Enumerable.Range(0, n).Select(i => Math.Sin(i / 40.0) + 0.02 * (random.NextDouble() - 0.5)).ToArray(); + var truth = Enumerable.Range(0, n).Select(i => Math.Sin(i / 40.0)).ToArray(); + var contaminated = (double[])clean.Clone(); + var outliers = new HashSet(); + while (outliers.Count < n / 5) outliers.Add(random.Next(n)); + foreach (var i in outliers) contaminated[i] += (random.NextDouble() < 0.5 ? -1 : 1) * (1 + 2 * random.NextDouble()); + + var reference = LocalRegression.Smooth(clean, window: 31, robustIterations: 3); + var robust = LocalRegression.Smooth(contaminated, window: 31, robustIterations: 3); + var plain = LocalRegression.Smooth(contaminated, window: 31, robustIterations: 0); + + var robustShift = Enumerable.Range(0, n).Max(i => Math.Abs(robust.Fitted[i] - reference.Fitted[i])); + var plainShift = Enumerable.Range(0, n).Max(i => Math.Abs(plain.Fitted[i] - reference.Fitted[i])); + var robustError = Enumerable.Range(0, n).Max(i => Math.Abs(robust.Fitted[i] - truth[i])); + Assert.Less(robustShift, 0.03, "robust fit moved by the outliers"); + Assert.Less(robustError, 0.04); + Assert.Greater(plainShift, 10 * robustShift); + + // Outliers are rejected; their windows report the lost weight. + Assert.True(outliers.All(i => robust.RobustWeights[i] < 0.05)); + var inlierWeight = Enumerable.Range(0, n).Where(i => !outliers.Contains(i)).Average(i => robust.RobustWeights[i]); + Assert.Greater(inlierWeight, 0.8); + Assert.InRange(robust.SurvivingFraction.Average(), 0.6, 0.9); + } + + [Test] + public void MissingSamplesAreInterpolatedAndReportedAsRejected() + { + var y = Enumerable.Range(0, 40).Select(i => 0.5 * i).ToArray(); + y[0] = double.NaN; + y[10] = double.NaN; + y[11] = double.PositiveInfinity; + y[39] = double.NaN; + var result = LocalRegression.Smooth(y, window: 7); + Assert.Equal(36, result.ValidCount); + foreach (var i in new[] { 0, 10, 11, 39 }) + { + Assert.Approximately(0.5 * i, result.Fitted[i], 1e-9); + Assert.Equal(0.0, result.RobustWeights[i]); + } + } + + [Test] + public void PriorWeightsExcludeSamples() + { + var y = Enumerable.Range(0, 30).Select(i => (double)i).ToArray(); + y[15] = 1000; + var weights = Enumerable.Repeat(1.0, 30).ToArray(); + weights[15] = 0; + var result = LocalRegression.Smooth(y, window: 5, robustIterations: 0, priorWeights: weights); + Assert.Approximately(15, result.Fitted[15], 1e-9); + } + + [Test] + public void DegenerateInputs() + { + Assert.True(double.IsNaN(LocalRegression.Smooth([double.NaN, double.NaN], 3).Fitted[1])); + Assert.Equal(4.0, LocalRegression.Smooth([4.0], 5).Fitted[0]); + var two = LocalRegression.Smooth([1.0, 3.0, double.NaN], 5); + Assert.Approximately(5, two.Fitted[2], 1e-12); + Assert.Throws(() => LocalRegression.Smooth([1.0], 0)); + Assert.Throws(() => LocalRegression.Smooth([1.0, 2.0], 3, x: [1.0, 0.0])); + } + + [Test] + public void RandomInputsGiveFiniteDeterministicOutputs() + { + var random = new Random(99); + for (var trial = 0; trial < 20; trial++) + { + var n = 1 + random.Next(400); + var y = Enumerable.Range(0, n).Select(_ => random.NextDouble() < 0.15 ? double.NaN : 100 * (random.NextDouble() - 0.5)).ToArray(); + if (y.All(double.IsNaN)) y[0] = 1; + var window = 1 + random.Next(60); + var degree = 1 + random.Next(2); + var a = LocalRegression.Smooth(y, window, degree, robustIterations: 3); + var b = LocalRegression.Smooth(y, window, degree, robustIterations: 3); + Assert.True(a.Fitted.All(double.IsFinite), $"trial {trial}"); + Assert.True(a.SurvivingFraction.All(f => f is >= 0 and <= 1 + 1e-12)); + Assert.SequenceEqual(a.Fitted, b.Fitted); + Assert.SequenceEqual(a.RobustWeights, b.RobustWeights); + } + } +}