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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:31:06 +00:00
1 parent 4f1902d287
commit 72ffd8ec47
2 files changed
+325

No files matched your search

+207
View File
@@ -0,0 +1,207 @@
namespace Titano.Core.Mathematics;
/// <summary>Output of <see cref="LocalRegression.Smooth"/>; every array has one entry per input sample.</summary>
public sealed class LocalRegressionResult
{
internal LocalRegressionResult(double[] fitted, double[] robustWeights, double[] survivingFraction, int validCount)
{
Fitted = fitted;
RobustWeights = robustWeights;
SurvivingFraction = survivingFraction;
ValidCount = validCount;
}
/// <summary>Smoothed value at every position, including missing samples (interpolated from their neighbours).
/// NaN only when there is no valid sample at all.</summary>
public double[] Fitted { get; }
/// <summary>Tukey biweight each sample carried in the final fit (1 = full inlier, 0 = rejected or missing).</summary>
public double[] RobustWeights { get; }
/// <summary>
/// Σ 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.
/// </summary>
public double[] SurvivingFraction { get; }
public int ValidCount { get; }
}
/// <summary>
/// Robust locally weighted regression, LOWESS (Cleveland 1979). Each position is fitted by weighted least squares
/// of degree 1 or 2 over its <c>window</c> 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.
/// </summary>
public static class LocalRegression
{
/// <param name="y">Samples; NaN/±∞ mark missing values.</param>
/// <param name="window">Number of nearest valid samples in each local fit (clamped to the valid count).</param>
/// <param name="degree">Local polynomial degree, 1 (linear) or 2 (quadratic).</param>
/// <param name="robustIterations">Tukey reweighting passes after the initial fit (Cleveland uses 2–3).</param>
/// <param name="x">Non-decreasing positions (e.g. capture seconds); indices when empty.</param>
/// <param name="priorWeights">Optional non-negative sample weights; zero marks a sample as missing.</param>
public static LocalRegressionResult Smooth(
ReadOnlySpan<double> y,
int window,
int degree = 1,
int robustIterations = 2,
ReadOnlySpan<double> x = default,
ReadOnlySpan<double> 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<int>(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);
}
/// <summary>Start of the contiguous block of <paramref name="q"/> valid samples nearest to each position
/// (sliding k-nearest-neighbour window; total O(n + m)).</summary>
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);
}
/// <summary>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).</summary>
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;
}
}
@@ -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<int>();
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<ArgumentOutOfRangeException>(() => LocalRegression.Smooth([1.0], 0));
Assert.Throws<ArgumentException>(() => 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);
}
}
}