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:
2 files changed
+325
No files matched your search
@@ -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);
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user