dohertj2/ScadaBridge
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(kpi): K10 — KpiSeriesBucketer last-per-bucket downsampler

Browse Source
This commit is contained in:
Joseph Doherty
2026-06-17 20:04:51 -04:00
parent e6c15250ce
commit 76f5ed72e4
2 changed files with 411 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ZB.MOM.WW.ScadaBridge.Commons/Types/Kpi/KpiSeriesBucketer.cs
+109
View File
@@ -0,0 +1,109 @@
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi;
/// <summary>
/// Pure, deterministic downsampling helper for KPI series charting (M6 "KPI History &amp; Trends").
/// Reduces a raw <see cref="KpiSeriesPoint"/> series to at most <c>maxPoints</c> points using
/// last-value-per-bucket / gauge semantics — suitable for step/area charts where the most
/// recent value in a window best represents that window.
/// </summary>
public static class KpiSeriesBucketer
{
/// <summary>
/// Reduces <paramref name="raw"/> to at most <paramref name="maxPoints"/> points by dividing
/// the window <c>[<paramref name="fromUtc"/>, <paramref name="toUtc"/>]</c> into equal-width
/// time buckets and keeping the <em>last</em> raw point (highest
/// <see cref="KpiSeriesPoint.BucketStartUtc"/>) within each non-empty bucket.
/// Empty buckets are omitted — no gap-filling.
/// </summary>
/// <param name="raw">
/// Input series, assumed to be sorted ascending by <see cref="KpiSeriesPoint.BucketStartUtc"/>.
/// If not sorted, the point with the largest timestamp within each bucket is selected.
/// If <c>null</c> or empty, an empty list is returned.
/// </param>
/// <param name="fromUtc">UTC start of the query window (inclusive).</param>
/// <param name="toUtc">UTC end of the query window (inclusive on the right edge).</param>
/// <param name="maxPoints">Maximum number of output points. Must be ≥ 2.</param>
/// <returns>
/// An <see cref="IReadOnlyList{T}"/> of at most <paramref name="maxPoints"/> bucketed points,
/// ordered by <see cref="KpiSeriesPoint.BucketStartUtc"/> ascending.
/// Returns <paramref name="raw"/> unchanged (same reference) when
/// <c>raw.Count &lt;= maxPoints</c>.
/// </returns>
/// <exception cref="ArgumentOutOfRangeException">
/// Thrown when <paramref name="maxPoints"/> &lt; 2 or
/// <paramref name="toUtc"/> &lt;= <paramref name="fromUtc"/>.
/// These are caller programming errors — a chart needs at least two points and a
/// non-degenerate window.
/// </exception>
public static IReadOnlyList<KpiSeriesPoint> Bucket(
IReadOnlyList<KpiSeriesPoint> raw,
DateTime fromUtc,
DateTime toUtc,
int maxPoints)
{
if (maxPoints < 2)
throw new ArgumentOutOfRangeException(nameof(maxPoints),
maxPoints, "maxPoints must be >= 2.");
if (toUtc <= fromUtc)
throw new ArgumentOutOfRangeException(nameof(toUtc),
toUtc, "toUtc must be strictly greater than fromUtc.");
// Normal runtime case — empty or short series: return as-is.
if (raw is null || raw.Count == 0)
return Array.Empty<KpiSeriesPoint>();
if (raw.Count <= maxPoints)
return raw;
// Divide the window into maxPoints equal-width buckets.
// Each bucket covers [bucketStart, bucketStart + bucketWidth).
// The right edge (toUtc) belongs to the last bucket to avoid overflow.
double windowTicks = (double)(toUtc.Ticks - fromUtc.Ticks);
double bucketWidthTicks = windowTicks / maxPoints;
// For each bucket, track the candidate point: the one with the
// maximum BucketStartUtc (last value within the bucket).
// We use a fixed-size array indexed by bucket number.
// Nullable KpiSeriesPoint[] with 'hasValue' flags is fine since the
// struct is small.
var best = new KpiSeriesPoint[maxPoints];
var occupied = new bool[maxPoints];
foreach (var point in raw)
{
long offsetTicks = point.BucketStartUtc.Ticks - fromUtc.Ticks;
// Skip points outside [fromUtc, toUtc].
if (offsetTicks < 0 || point.BucketStartUtc > toUtc)
continue;
// Compute bucket index; clamp to last bucket so toUtc itself
// doesn't overflow to index maxPoints.
int bucketIndex = (int)(offsetTicks / bucketWidthTicks);
if (bucketIndex >= maxPoints)
bucketIndex = maxPoints - 1;
// Keep the point with the highest timestamp in this bucket
// (last-value semantics; if ties, keep first encountered — stable).
if (!occupied[bucketIndex] ||
point.BucketStartUtc > best[bucketIndex].BucketStartUtc)
{
best[bucketIndex] = new KpiSeriesPoint(
fromUtc + TimeSpan.FromTicks((long)(bucketIndex * bucketWidthTicks)),
point.Value);
occupied[bucketIndex] = true;
}
}
// Collect non-empty buckets in order.
var result = new List<KpiSeriesPoint>(maxPoints);
for (int i = 0; i < maxPoints; i++)
{
if (occupied[i])
result.Add(best[i]);
}
return result;
}
}
tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/Kpi/KpiSeriesBucketerTests.cs
+302
View File
@@ -0,0 +1,302 @@
using ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi;
namespace ZB.MOM.WW.ScadaBridge.Commons.Tests.Kpi;
/// <summary>Tests for <see cref="KpiSeriesBucketer"/>.</summary>
public class KpiSeriesBucketerTests
{
// Fixed epoch used throughout so tests are fully deterministic.
private static readonly DateTime Epoch =
new(2026, 6, 15, 0, 0, 0, DateTimeKind.Utc);
private static DateTime T(int minutesFromEpoch) =>
Epoch.AddMinutes(minutesFromEpoch);
// -----------------------------------------------------------------------
// Guard / invalid-argument contracts
// -----------------------------------------------------------------------
[Fact]
public void Bucket_MaxPointsLessThan2_ThrowsArgumentOutOfRangeException()
{
var raw = new[] { new KpiSeriesPoint(T(0), 1.0) };
Assert.Throws<ArgumentOutOfRangeException>(() =>
KpiSeriesBucketer.Bucket(raw, T(0), T(60), maxPoints: 1));
}
[Fact]
public void Bucket_MaxPointsZero_ThrowsArgumentOutOfRangeException()
{
var raw = new[] { new KpiSeriesPoint(T(0), 1.0) };
Assert.Throws<ArgumentOutOfRangeException>(() =>
KpiSeriesBucketer.Bucket(raw, T(0), T(60), maxPoints: 0));
}
[Fact]
public void Bucket_ToUtcEqualFromUtc_ThrowsArgumentOutOfRangeException()
{
var raw = new[] { new KpiSeriesPoint(T(0), 1.0) };
Assert.Throws<ArgumentOutOfRangeException>(() =>
KpiSeriesBucketer.Bucket(raw, T(30), T(30), maxPoints: 5));
}
[Fact]
public void Bucket_ToUtcBeforeFromUtc_ThrowsArgumentOutOfRangeException()
{
var raw = new[] { new KpiSeriesPoint(T(0), 1.0) };
Assert.Throws<ArgumentOutOfRangeException>(() =>
KpiSeriesBucketer.Bucket(raw, T(60), T(0), maxPoints: 5));
}
// -----------------------------------------------------------------------
// Empty / null raw series
// -----------------------------------------------------------------------
[Fact]
public void Bucket_NullRaw_ReturnsEmptyList()
{
var result = KpiSeriesBucketer.Bucket(null!, T(0), T(60), maxPoints: 10);
Assert.Empty(result);
}
[Fact]
public void Bucket_EmptyRaw_ReturnsEmptyList()
{
var result = KpiSeriesBucketer.Bucket(
Array.Empty<KpiSeriesPoint>(), T(0), T(60), maxPoints: 10);
Assert.Empty(result);
}
// -----------------------------------------------------------------------
// raw.Count <= maxPoints → returned unchanged (same reference)
// -----------------------------------------------------------------------
[Fact]
public void Bucket_RawCountEqualsMaxPoints_ReturnsSameReference()
{
var raw = new[]
{
new KpiSeriesPoint(T(0), 1.0),
new KpiSeriesPoint(T(10), 2.0),
new KpiSeriesPoint(T(20), 3.0),
};
var result = KpiSeriesBucketer.Bucket(raw, T(0), T(60), maxPoints: 3);
Assert.Same(raw, result);
}
[Fact]
public void Bucket_RawCountLessThanMaxPoints_ReturnsSameReference()
{
var raw = new[]
{
new KpiSeriesPoint(T(0), 5.0),
new KpiSeriesPoint(T(5), 6.0),
};
var result = KpiSeriesBucketer.Bucket(raw, T(0), T(60), maxPoints: 10);
Assert.Same(raw, result);
}
[Fact]
public void Bucket_SinglePoint_ReturnsSameReference()
{
var raw = new[] { new KpiSeriesPoint(T(30), 42.0) };
var result = KpiSeriesBucketer.Bucket(raw, T(0), T(60), maxPoints: 5);
Assert.Same(raw, result);
}
// -----------------------------------------------------------------------
// Downsampling: correct bucket count and last-value selection
// -----------------------------------------------------------------------
[Fact]
public void Bucket_MorePointsThanMaxPoints_ReducesToMaxPointsBuckets()
{
// 60-minute window / 3 buckets → 20 min each.
// Plant exactly one point in each bucket; all three buckets occupied.
var raw = new[]
{
new KpiSeriesPoint(T(5), 10.0), // bucket 0: [0, 20)
new KpiSeriesPoint(T(25), 20.0), // bucket 1: [20, 40)
new KpiSeriesPoint(T(45), 30.0), // bucket 2: [40, 60]
};
var result = KpiSeriesBucketer.Bucket(raw, T(0), T(60), maxPoints: 3);
Assert.Equal(3, result.Count);
Assert.Equal(10.0, result[0].Value);
Assert.Equal(20.0, result[1].Value);
Assert.Equal(30.0, result[2].Value);
}
[Fact]
public void Bucket_MultiplePointsInSameBucket_LastValueWins()
{
// 60-minute window / 2 buckets → 30 min each.
// Three points all land in bucket 0; the last (T(25)) should win.
var raw = new[]
{
new KpiSeriesPoint(T(5), 1.0),
new KpiSeriesPoint(T(15), 2.0),
new KpiSeriesPoint(T(25), 99.0), // latest in bucket 0 → wins
new KpiSeriesPoint(T(35), 5.0), // bucket 1
};
var result = KpiSeriesBucketer.Bucket(raw, T(0), T(60), maxPoints: 2);
Assert.Equal(2, result.Count);
Assert.Equal(99.0, result[0].Value); // last in bucket 0
Assert.Equal(5.0, result[1].Value); // only point in bucket 1
}
[Fact]
public void Bucket_BucketStartUtc_IsSetToBucketStartNotRawPointTimestamp()
{
// 60-minute window / 3 buckets → 20 min each.
// Output BucketStartUtc must be the bucket boundary, not the raw point's time.
// raw.Count (4) > maxPoints (3) ensures the downsampling path runs.
var raw = new[]
{
new KpiSeriesPoint(T(7), 1.0), // inside bucket 0: [0, 20)
new KpiSeriesPoint(T(22), 2.0), // inside bucket 1: [20, 40)
new KpiSeriesPoint(T(35), 3.0), // inside bucket 1: later → wins bucket 1
new KpiSeriesPoint(T(55), 4.0), // inside bucket 2: [40, 60]
};
var result = KpiSeriesBucketer.Bucket(raw, T(0), T(60), maxPoints: 3);
// Bucket boundaries: 0 min, 20 min, 40 min
Assert.Equal(3, result.Count);
Assert.Equal(T(0), result[0].BucketStartUtc);
Assert.Equal(T(20), result[1].BucketStartUtc);
Assert.Equal(T(40), result[2].BucketStartUtc);
}
// -----------------------------------------------------------------------
// Right-edge: point exactly at toUtc lands in the last bucket
// -----------------------------------------------------------------------
[Fact]
public void Bucket_PointAtToUtc_LandsInLastBucket()
{
// 60-minute window / 3 buckets → 20 min each.
// A point exactly at T(60) = toUtc must go to bucket 2, not overflow.
var raw = new[]
{
new KpiSeriesPoint(T(10), 1.0),
new KpiSeriesPoint(T(30), 2.0),
new KpiSeriesPoint(T(60), 99.0), // right edge — must land in last bucket
};
// raw.Count (3) == maxPoints (3) so it normally returns as-is;
// use maxPoints=2 to force downsampling and expose the edge behaviour.
// Window: [T(0), T(60)], 2 buckets → 30 min each.
// T(10) → bucket 0, T(30) → bucket 1, T(60) → bucket 1 (last).
var raw2 = new[]
{
new KpiSeriesPoint(T(10), 5.0),
new KpiSeriesPoint(T(35), 6.0),
new KpiSeriesPoint(T(60), 7.0), // exactly toUtc → bucket 1
};
var result = KpiSeriesBucketer.Bucket(raw2, T(0), T(60), maxPoints: 2);
Assert.Equal(2, result.Count);
// Bucket 1 holds both T(35) and T(60); T(60) is later → wins.
Assert.Equal(7.0, result[1].Value);
}
// -----------------------------------------------------------------------
// Empty buckets omitted — no gap-filling
// -----------------------------------------------------------------------
[Fact]
public void Bucket_GapInRaw_EmptyBucketsOmitted()
{
// 60-minute window / 4 buckets → 15 min each.
// Populate only buckets 0 and 3; buckets 1 and 2 are empty.
// Expect 2 output points, not 4.
var raw = new[]
{
new KpiSeriesPoint(T(5), 10.0), // bucket 0: [0, 15)
new KpiSeriesPoint(T(50), 20.0), // bucket 3: [45, 60]
};
// raw.Count (2) < maxPoints (4), so normally returns same reference.
// To test the gap-omission path we need raw.Count > maxPoints and a gap.
var raw2 = new[]
{
new KpiSeriesPoint(T(5), 10.0),
new KpiSeriesPoint(T(6), 11.0),
new KpiSeriesPoint(T(50), 20.0),
new KpiSeriesPoint(T(51), 21.0),
};
// 4 raw points, maxPoints=4 → returns same reference (no downsampling).
// Use maxPoints=3 to trigger the downsampler.
// 60-minute window / 3 buckets → 20 min each.
// T(5) → bucket 0, T(6) → bucket 0, T(50) → bucket 2, T(51) → bucket 2.
// Bucket 1 is empty → 2 output points.
var result = KpiSeriesBucketer.Bucket(raw2, T(0), T(60), maxPoints: 3);
Assert.Equal(2, result.Count);
Assert.Equal(11.0, result[0].Value); // last in bucket 0
Assert.Equal(21.0, result[1].Value); // last in bucket 2
}
// -----------------------------------------------------------------------
// Points outside [fromUtc, toUtc] are ignored
// -----------------------------------------------------------------------
[Fact]
public void Bucket_PointsOutsideWindow_AreIgnored()
{
// Window [T(10), T(50)], 2 buckets.
// Points at T(0) and T(60) are outside — should not appear in output.
var raw = new[]
{
new KpiSeriesPoint(T(0), 999.0), // before window
new KpiSeriesPoint(T(20), 1.0), // inside bucket 0: [T(10), T(30))
new KpiSeriesPoint(T(40), 2.0), // inside bucket 1: [T(30), T(50)]
new KpiSeriesPoint(T(60), 999.0), // after window
};
var result = KpiSeriesBucketer.Bucket(raw, T(10), T(50), maxPoints: 2);
Assert.Equal(2, result.Count);
Assert.Equal(1.0, result[0].Value);
Assert.Equal(2.0, result[1].Value);
}
// -----------------------------------------------------------------------
// Two-point minimum — maxPoints == 2 works correctly
// -----------------------------------------------------------------------
[Fact]
public void Bucket_MaxPointsExactly2_ProducesAtMostTwoBuckets()
{
var raw = Enumerable
.Range(0, 10)
.Select(i => new KpiSeriesPoint(T(i * 6), (double)i))
.ToArray();
// 60-minute window / 2 buckets → 30 min each.
var result = KpiSeriesBucketer.Bucket(raw, T(0), T(60), maxPoints: 2);
Assert.Equal(2, result.Count);
// Bucket 0: T(0)–T(29) → last is T(24) (value 4); bucket 1: T(30)–T(60) → last is T(54) (value 9).
Assert.Equal(4.0, result[0].Value);
Assert.Equal(9.0, result[1].Value);
}
}