fix: improve modulation degradation cues

Author: itsDNNS

app/modules/modulation/engine.py

@@ -17,6 +17,10 @@
     ("us", "3.1"): 1024,   # log2 = 10
 }
 
+DEGRADED_QAM_THRESHOLDS = {
+    ("us", "3.1"): 256,
+}
+
 DISCLAIMER = (
     "Health indices and modulation statistics are estimates based on periodic "
     "polling samples and may not reflect every modulation change between polls."
@@ -132,6 +136,16 @@ def _group_channels_by_protocol(channels):
     return dict(groups)
 
 
+def _degraded_qam_threshold(direction, docsis_version, default_threshold):
+    """Return the modulation threshold that counts as degraded.
+
+    Most protocol groups keep the legacy threshold. US DOCSIS 3.1 is stricter
+    because 128QAM already represents a substantial drop from the normal
+    1024QAM operating point.
+    """
+    return DEGRADED_QAM_THRESHOLDS.get((direction, docsis_version), default_threshold)
+
+
 # ── Multi-day overview (distribution v2) ─────────────────────────────
 
 
@@ -265,7 +279,10 @@ def _build_protocol_group(version, direction, by_date, sorted_dates, threshold):
 
         # Count degraded channels for this day
         degraded = _count_degraded_channels_day(
-            by_date[date_str], version, direction, threshold
+            by_date[date_str],
+            version,
+            direction,
+            _degraded_qam_threshold(direction, version, threshold),
         )
 
         days.append({
@@ -285,7 +302,11 @@ def _build_protocol_group(version, direction, by_date, sorted_dates, threshold):
 
     # Overall degraded channels
     degraded_overall = _count_degraded_channels_overall(
-        by_date, sorted_dates, version, direction, threshold
+        by_date,
+        sorted_dates,
+        version,
+        direction,
+        _degraded_qam_threshold(direction, version, threshold),
     )
 
     return {
@@ -398,8 +419,9 @@ def compute_intraday(snapshots, direction, tz_name, date_str, low_qam_threshold=
             hi = _health_index_for_group(
                 [(l, q) for _, l, q in timeline], direction, version
             )
-            degraded = any(q is not None and q <= low_qam_threshold for _, _, q in timeline)
-            summary = _channel_summary(periods, max_qam, low_qam_threshold)
+            degraded_threshold = _degraded_qam_threshold(direction, version, low_qam_threshold)
+            degraded = any(q is not None and q <= degraded_threshold for _, _, q in timeline)
+            summary = _channel_summary(periods, max_qam, degraded_threshold)
 
             # Simplify timeline to transition points only
             simplified = _simplify_timeline(timeline)

app/modules/modulation/static/main.js

@@ -10,8 +10,10 @@ var QAM_COLORS = {
     '4QAM':    '#ef4444',
     '16QAM':   '#f97316',
     '64QAM':   '#eab308',
+    '128QAM':  '#84cc16',
     '256QAM':  '#22c55e',
-    '1024QAM': '#10b981',
+    '512QAM':  '#14b8a6',
+    '1024QAM': '#06b6d4',
     '4096QAM': '#3b82f6',
     'OFDM':    '#8b5cf6',
     'OFDMA':   '#8b5cf6',
@@ -521,7 +523,7 @@ function renderChannelTimeline(canvasId, timeline) {
     var dataPoints = timeline.map(function(t) { return modSortOrder(t.modulation); });
     var n = labels.length;
     var textColor = _cssVar('--text-secondary') || '#9ca3af';
-    var qamLabels = ['4QAM', '16QAM', '64QAM', '256QAM', '1024QAM', '4096QAM', 'OFDM', 'OFDMA', 'Unknown'];
+    var qamLabels = ['4QAM', '16QAM', '64QAM', '128QAM', '256QAM', '512QAM', '1024QAM', '4096QAM', 'OFDM', 'OFDMA', 'Unknown'];
 
     var xData = [];
     for (var i = 0; i < n; i++) xData.push(i);
@@ -533,7 +535,7 @@ function renderChannelTimeline(canvasId, timeline) {
         height: h,
         scales: {
             x: { time: false, range: function() { return [-0.5, n - 0.5]; } },
-            y: { range: [-0.5, 8.5] }
+            y: { range: [-0.5, 10.5] }
         },
         axes: [
             {
@@ -554,7 +556,7 @@ function renderChannelTimeline(canvasId, timeline) {
                 scale: 'y',
                 stroke: textColor,
                 grid: { stroke: 'rgba(255,255,255,0.04)', width: 1 },
-                splits: function() { return [0,1,2,3,4,5,6,7,8]; },
+                splits: function() { return [0,1,2,3,4,5,6,7,8,9,10]; },
                 values: function(u, vals) { return vals.map(function(v) { return qamLabels[v] || ''; }); },
                 font: '10px system-ui',
                 size: 60
@@ -607,8 +609,8 @@ function densityClass(v) {
     return 'critical';
 }
 function modSortOrder(mod) {
-    var order = { '4QAM': 0, '16QAM': 1, '64QAM': 2, '256QAM': 3, '1024QAM': 4, '4096QAM': 5, 'OFDM': 6, 'OFDMA': 7, 'Unknown': 8 };
-    return order[mod] !== undefined ? order[mod] : 9;
+    var order = { '4QAM': 0, '16QAM': 1, '64QAM': 2, '128QAM': 3, '256QAM': 4, '512QAM': 5, '1024QAM': 6, '4096QAM': 7, 'OFDM': 8, 'OFDMA': 9, 'Unknown': 10 };
+    return order[mod] !== undefined ? order[mod] : 11;
 }
 
 function destroyCharts() {

tests/test_modulation_engine.py

@@ -8,6 +8,7 @@
     _parse_qam_order,
     _canonical_label,
     _distribution_pct,
+    _degraded_qam_threshold,
     _health_index,
     _health_index_for_group,
     _low_qam_pct,
@@ -240,6 +241,15 @@ def test_mixed_qam_us_30(self):
         assert _health_index_for_group(obs, "us", "3.0") == 50.0
 
 
+class TestDegradedThresholds:
+    def test_default_threshold_unchanged(self):
+        assert _degraded_qam_threshold("us", "3.0", 16) == 16
+        assert _degraded_qam_threshold("ds", "3.0", 16) == 16
+
+    def test_us31_uses_higher_threshold(self):
+        assert _degraded_qam_threshold("us", "3.1", 16) == 256
+
+
 # ── _low_qam_pct ──
 
 class TestLowQamPct:
@@ -448,6 +458,26 @@ def test_mixed_protocol_groups(self):
         assert "3.0" in versions
         assert "3.1" in versions
 
+    def test_us31_128qam_counts_as_degraded(self):
+        us_channels = [
+            {"channel_id": 41, "modulation": "128QAM", "docsis_version": "3.1"},
+        ]
+        snaps = [_make_snapshot("2026-03-01T10:00:00Z", us_channels=us_channels)]
+        result = compute_distribution_v2(snaps, "us", "UTC")
+        pg = result["protocol_groups"][0]
+        assert pg["docsis_version"] == "3.1"
+        assert pg["degraded_channel_count"] == 1
+
+    def test_us31_512qam_not_counted_as_degraded(self):
+        us_channels = [
+            {"channel_id": 41, "modulation": "512QAM", "docsis_version": "3.1"},
+        ]
+        snaps = [_make_snapshot("2026-03-01T10:00:00Z", us_channels=us_channels)]
+        result = compute_distribution_v2(snaps, "us", "UTC")
+        pg = result["protocol_groups"][0]
+        assert pg["docsis_version"] == "3.1"
+        assert pg["degraded_channel_count"] == 0
+
     def test_per_day_data(self):
         snaps = [
             _make_snapshot("2026-03-01T10:00:00Z", us_channels=_make_channels(["64QAM"])),
@@ -619,6 +649,24 @@ def test_multi_protocol_groups(self):
         result = compute_intraday(snaps, "us", "UTC", "2026-03-01")
         assert len(result["protocol_groups"]) == 2
 
+    def test_us31_channel_summary_shows_128qam_degradation(self):
+        snaps = [
+            _make_snapshot("2026-03-01T10:00:00Z",
+                           us_channels=[{"channel_id": 41, "modulation": "1024QAM",
+                                         "docsis_version": "3.1", "frequency": "29.775 - 64.775"}]),
+            _make_snapshot("2026-03-01T14:00:00Z",
+                           us_channels=[{"channel_id": 41, "modulation": "128QAM",
+                                         "docsis_version": "3.1", "frequency": "29.775 - 64.775"}]),
+            _make_snapshot("2026-03-01T18:00:00Z",
+                           us_channels=[{"channel_id": 41, "modulation": "512QAM",
+                                         "docsis_version": "3.1", "frequency": "29.775 - 64.775"}]),
+        ]
+        result = compute_intraday(snaps, "us", "UTC", "2026-03-01")
+        pg = next(pg for pg in result["protocol_groups"] if pg["docsis_version"] == "3.1")
+        ch = pg["channels"][0]
+        assert ch["degraded"] is True
+        assert "128QAM" in ch["summary"]
+
 
 # ── Legacy compute_distribution (v1 compat) ──