fix: correct DOCSIS 3.1 modulation charts

itsDNNS · itsDNNS · commit 441073e480ce · 2026-03-10T22:46:43.000+01:00
diff --git a/app/modules/modulation/engine.py b/app/modules/modulation/engine.py
@@ -250,6 +250,8 @@ def _weighted_avg(values_weights):
 
 def _build_protocol_group(version, direction, by_date, sorted_dates, threshold):
     """Build a single protocol group result dict."""
+    effective_threshold = _degraded_qam_threshold(direction, version, threshold)
+
     # Collect observations per day, only for channels of this version
     all_observations = []
     channel_ids = set()
@@ -275,14 +277,14 @@ def _build_protocol_group(version, direction, by_date, sorted_dates, threshold):
 
         all_observations.extend(day_observations)
         hi = _health_index_for_group(day_observations, direction, version)
-        lq = _low_qam_pct(day_observations, threshold)
+        lq = _low_qam_pct(day_observations, effective_threshold)
 
         # Count degraded channels for this day
         degraded = _count_degraded_channels_day(
             by_date[date_str],
             version,
             direction,
-            _degraded_qam_threshold(direction, version, threshold),
+            effective_threshold,
         )
 
         days.append({
@@ -296,7 +298,7 @@ def _build_protocol_group(version, direction, by_date, sorted_dates, threshold):
     max_qam = MAX_QAM.get((direction, version), 4096)
     max_qam_label = f"{max_qam}QAM"
     overall_hi = _health_index_for_group(all_observations, direction, version)
-    overall_lq = _low_qam_pct(all_observations, threshold)
+    overall_lq = _low_qam_pct(all_observations, effective_threshold)
     overall_dist = _distribution_pct(all_observations)
     dominant = max(overall_dist, key=overall_dist.get) if overall_dist else None
 
@@ -306,7 +308,7 @@ def _build_protocol_group(version, direction, by_date, sorted_dates, threshold):
         sorted_dates,
         version,
         direction,
-        _degraded_qam_threshold(direction, version, threshold),
+        effective_threshold,
     )
 
     return {
diff --git a/app/modules/modulation/static/main.js b/app/modules/modulation/static/main.js
@@ -8,7 +8,9 @@ var _modIntradayCharts = [];
 /* QAM color scheme */
 var QAM_COLORS = {
     '4QAM':    '#ef4444',
+    '8QAM':    '#fb7185',
     '16QAM':   '#f97316',
+    '32QAM':   '#f59e0b',
     '64QAM':   '#eab308',
     '128QAM':  '#84cc16',
     '256QAM':  '#22c55e',
@@ -20,6 +22,22 @@ var QAM_COLORS = {
     'Unknown': '#6b7280'
 };
 
+var MODULATION_LEVELS = [
+    '4QAM',
+    '8QAM',
+    '16QAM',
+    '32QAM',
+    '64QAM',
+    '128QAM',
+    '256QAM',
+    '512QAM',
+    '1024QAM',
+    '4096QAM',
+    'OFDM',
+    'OFDMA',
+    'Unknown'
+];
+
 /* ── Direction tabs ── */
 var dirTabs = document.querySelectorAll('#modulation-direction-tabs .trend-tab');
 dirTabs.forEach(function(btn) {
@@ -206,6 +224,9 @@ function renderProtocolGroups(data) {
         barDiv.style.height = '100%';
         barWrap.appendChild(barDiv);
         barCard.appendChild(barWrap);
+        var legendDiv = _el('div', 'modulation-custom-legend');
+        legendDiv.id = 'mod-dist-legend-' + idx;
+        barCard.appendChild(legendDiv);
         chartsGrid.appendChild(barCard);
 
         // Trend line chart card
@@ -245,8 +266,10 @@ function _buildMiniKPI(label, value, cls) {
 
 function renderGroupDistChart(pg, idx) {
     var container = document.getElementById('mod-dist-chart-' + idx);
+    var legendContainer = document.getElementById('mod-dist-legend-' + idx);
     if (!container) return;
     container.textContent = '';
+    if (legendContainer) legendContainer.textContent = '';
 
     var days = pg.days || [];
     var labels = days.map(function(d) { return d.date.slice(5); }); /* MM-DD, drop year */
@@ -269,8 +292,10 @@ function renderGroupDistChart(pg, idx) {
     /* Build cumulative sums for each modulation layer */
     var cumData = xData.map(function() { return 0; });
     var layerData = [];
+    var rawSeriesByMod = {};
     modKeys.forEach(function(mod) {
         var raw = days.map(function(d) { return (d.distribution || {})[mod] || 0; });
+        rawSeriesByMod[mod] = raw;
         var stacked = raw.map(function(v, j) { cumData[j] += v; return cumData[j]; });
         layerData.push({ mod: mod, data: stacked });
     });
@@ -291,6 +316,10 @@ function renderGroupDistChart(pg, idx) {
         });
     }
 
+    if (legendContainer) {
+        renderDistributionLegend(legendContainer, modKeys);
+    }
+
     var w = container.offsetWidth || 400;
     var h = container.offsetHeight || 300;
     var chart = new uPlot({
@@ -321,8 +350,13 @@ function renderGroupDistChart(pg, idx) {
         ],
         series: uSeries,
         cursor: { show: true, x: true, y: false, points: { show: false } },
-        legend: { show: true, live: false },
-        plugins: [tooltipPlugin(labels)]
+        legend: { show: false, live: false },
+        plugins: [tooltipPlugin(labels, function(ctx) {
+            var mod = ctx.dataset.label;
+            var rawSeries = rawSeriesByMod[mod] || [];
+            var raw = rawSeries[ctx.dataIndex] || 0;
+            return mod + ': ' + raw.toFixed(1) + '%';
+        })]
     }, uData, container);
     _modCharts.push(chart);
 }
@@ -523,7 +557,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', '128QAM', '256QAM', '512QAM', '1024QAM', '4096QAM', 'OFDM', 'OFDMA', 'Unknown'];
+    var qamLabels = MODULATION_LEVELS;
 
     var xData = [];
     for (var i = 0; i < n; i++) xData.push(i);
@@ -535,7 +569,7 @@ function renderChannelTimeline(canvasId, timeline) {
         height: h,
         scales: {
             x: { time: false, range: function() { return [-0.5, n - 0.5]; } },
-            y: { range: [-0.5, 10.5] }
+            y: { range: [-0.5, qamLabels.length - 0.5] }
         },
         axes: [
             {
@@ -556,7 +590,9 @@ 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,9,10]; },
+                splits: function() {
+                    return qamLabels.map(function(_, idx) { return idx; });
+                },
                 values: function(u, vals) { return vals.map(function(v) { return qamLabels[v] || ''; }); },
                 font: '10px system-ui',
                 size: 60
@@ -609,8 +645,22 @@ function densityClass(v) {
     return 'critical';
 }
 function modSortOrder(mod) {
-    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;
+    var order = {};
+    MODULATION_LEVELS.forEach(function(label, idx) {
+        order[label] = idx;
+    });
+    return order[mod] !== undefined ? order[mod] : (MODULATION_LEVELS.length - 1);
+}
+
+function renderDistributionLegend(container, modKeys) {
+    modKeys.forEach(function(mod) {
+        var item = _el('div', 'modulation-custom-legend-item');
+        var swatch = _el('span', 'modulation-custom-legend-swatch');
+        swatch.style.background = QAM_COLORS[mod] || '#6b7280';
+        item.appendChild(swatch);
+        item.appendChild(_el('span', 'modulation-custom-legend-label', mod));
+        container.appendChild(item);
+    });
 }
 
 function destroyCharts() {
diff --git a/app/modules/modulation/static/style.css b/app/modules/modulation/static/style.css
@@ -180,6 +180,29 @@
     font-size: 0.8em;
 }
 
+.modulation-custom-legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px 16px;
+    margin-top: 12px;
+    font-size: 0.75em;
+    color: var(--text-secondary, var(--muted));
+}
+
+.modulation-custom-legend-item {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    white-space: nowrap;
+}
+
+.modulation-custom-legend-swatch {
+    width: 10px;
+    height: 10px;
+    border-radius: 2px;
+    flex-shrink: 0;
+}
+
 @media (max-width: 768px) {
     .modulation-kpi-row {
         grid-template-columns: 1fr;
diff --git a/tests/test_modulation_engine.py b/tests/test_modulation_engine.py
@@ -467,6 +467,7 @@ def test_us31_128qam_counts_as_degraded(self):
         pg = result["protocol_groups"][0]
         assert pg["docsis_version"] == "3.1"
         assert pg["degraded_channel_count"] == 1
+        assert pg["low_qam_pct"] == 100.0
 
     def test_us31_512qam_not_counted_as_degraded(self):
         us_channels = [
@@ -478,6 +479,20 @@ def test_us31_512qam_not_counted_as_degraded(self):
         assert pg["docsis_version"] == "3.1"
         assert pg["degraded_channel_count"] == 0
 
+    def test_us31_low_qam_pct_tracks_protocol_threshold(self):
+        snaps = [
+            _make_snapshot("2026-03-01T10:00:00Z",
+                           us_channels=[{"channel_id": 41, "modulation": "1024QAM", "docsis_version": "3.1"}]),
+            _make_snapshot("2026-03-01T14:00:00Z",
+                           us_channels=[{"channel_id": 41, "modulation": "128QAM", "docsis_version": "3.1"}]),
+            _make_snapshot("2026-03-01T18:00:00Z",
+                           us_channels=[{"channel_id": 41, "modulation": "512QAM", "docsis_version": "3.1"}]),
+        ]
+        result = compute_distribution_v2(snaps, "us", "UTC")
+        pg = result["protocol_groups"][0]
+        assert pg["low_qam_pct"] == 33.3
+        assert pg["days"][0]["low_qam_pct"] == 33.3
+
     def test_per_day_data(self):
         snaps = [
             _make_snapshot("2026-03-01T10:00:00Z", us_channels=_make_channels(["64QAM"])),
