fix(validation): null-safety, status, cache fingerprint, blank coverage tab

Audit of the validation step (BLAST + minimap2) found bugs that silently broke
the Validation tab:

- parse_nanometanf_aggregate_json: a single JSON null on a numeric field made
  None<=1.0 / float(None) raise, which the catch-all except swallowed, dropping
  the WHOLE validation_results.json and blanking the Validation tab. Coerce
  every numeric with `or 0`/`or 0.0` and clamp percent_validated to <=100
  (covers both the blast and the expanded minimap2 result).
- determine_status: reads classified to an organism but 0 validated now reads as
  LOW_CONFIDENCE (examined-and-negative), not NO_DATA -- "checked, not confirmed"
  must not look identical to "not yet checked".
- _validation_dir_fingerprint: validation_dir resolves to validation/blast, but
  the authoritative aggregate JSON is one level up at
  validation/validation_results.json; fold its mtime in so realtime rewrites
  invalidate the cache instead of serving stale results.
- update_coverage_plots: the no-PAF branch returned the warning Alert into
  coverage-stats-container while hiding its parent coverage-plots-section,
  blanking the tab; keep the section visible so the warning shows.

Tests: null-safety, hit-rate clamp, examined-but-0-hits, cache-fingerprint-
tracks-aggregate, no-PAF-shows-warning-visible; four tests that encoded the old
behaviour updated. Full suite 2622 passed; verified live in the browser with
zero callback 500s.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: druvus

nanometa_live/app/tabs/validation_tab.py

@@ -743,11 +743,15 @@ def update_coverage_plots(selected_key, min_mapq, depth_threshold,
                 title="No coverage data",
                 message=no_paf_msg,
             )
+            # Keep the section VISIBLE: coverage-stats-container (where this
+            # warning lands) and the placeholder figures live inside
+            # coverage-plots-section, so hiding the section would blank the tab
+            # and swallow the explanation.
             return no_paf(), no_paf(), no_paf(), dbc.Alert(
                 no_paf_msg,
                 color="warning",
                 className="text-center",
-            ), hidden
+            ), visible
 
         depth_fig = create_coverage_depth_figure(coverage, threshold=threshold)
         cum_fig = create_cumulative_coverage_figure(coverage)

nanometa_live/core/parsers/blast_validation_parser.py

@@ -132,6 +132,12 @@ def determine_status(self) -> ValidationStatus:
             return ValidationStatus.FAILED
         if self.validated_reads == 0 and self.total_reads == 0:
             return ValidationStatus.NO_DATA
+        # Examined but nothing validated (reads were classified to this organism
+        # but BLAST/minimap2 confirmed none): a negative result, NOT "no data".
+        # Distinguishing the two matters clinically -- "checked, not confirmed"
+        # must not look identical to "not yet checked".
+        if self.validated_reads == 0 and self.total_reads > 0:
+            return ValidationStatus.LOW_CONFIDENCE
         if self.percent_validated >= 80 and self.percent_identity_mean >= 90:
             return ValidationStatus.CONFIRMED
         if self.percent_validated >= 50:
@@ -214,6 +220,23 @@ def _validation_dir_fingerprint(self) -> Optional[float]:
                         latest = m
                 except OSError:
                     continue
+            # The authoritative aggregate JSON is written one level up at
+            # validation/validation_results.json (the loader prefers it), but
+            # validation_dir often resolves to validation/blast or
+            # validation/minimap2. Without folding the aggregate's mtime in, a
+            # realtime rewrite of validation_results.json never advances this
+            # fingerprint and the cache serves stale results.
+            for agg in (
+                self.validation_dir.parent / "validation_results.json",
+                self.results_dir / "validation" / "validation_results.json",
+            ):
+                try:
+                    if agg.exists():
+                        m = agg.stat().st_mtime
+                        if m > latest:
+                            latest = m
+                except OSError:
+                    continue
             return latest
         except OSError:
             return None
@@ -444,21 +467,29 @@ def parse_nanometanf_aggregate_json(
 
                     method = entry.get('validation_method', method_default)
 
-                    # Map nanometanf fields to ValidationResult
-                    kraken_reads = entry.get('kraken_reads', 0)
-                    hit_rate = entry.get('hit_rate', 0.0)
-                    validated = entry.get('blast_hits', entry.get('mapped_reads', 0))
+                    # Map nanometanf fields to ValidationResult. A JSON ``null``
+                    # makes ``.get(key, default)`` return None (the default only
+                    # applies when the key is ABSENT), and ``None <= 1.0`` /
+                    # ``float(None)`` would raise -- caught by the catch-all
+                    # except below, which would silently drop the WHOLE aggregate
+                    # and blank the Validation tab. Coerce every numeric to a real
+                    # number with ``or 0`` before arithmetic.
+                    kraken_reads = entry.get('kraken_reads', 0) or 0
+                    hit_rate = entry.get('hit_rate', 0.0) or 0.0
+                    validated = entry.get('blast_hits', entry.get('mapped_reads', 0)) or 0
 
                     result = ValidationResult(
                         sample_id=sample_id,
                         taxid=tid,
                         species=entry.get('species', ''),
-                        total_reads=kraken_reads,
-                        validated_reads=validated,
-                        percent_validated=hit_rate * 100 if hit_rate <= 1.0 else hit_rate,
-                        percent_identity_mean=float(entry.get('avg_identity', 0.0)),
-                        coverage_breadth=float(entry.get('avg_coverage', 0.0)),
-                        avg_mapq=float(entry.get('avg_mapq', 0.0)),
+                        total_reads=int(kraken_reads),
+                        validated_reads=int(validated),
+                        percent_validated=min(
+                            100.0, hit_rate * 100 if hit_rate <= 1.0 else hit_rate
+                        ),
+                        percent_identity_mean=float(entry.get('avg_identity', 0.0) or 0.0),
+                        coverage_breadth=float(entry.get('avg_coverage', 0.0) or 0.0),
+                        avg_mapq=float(entry.get('avg_mapq', 0.0) or 0.0),
                         # ref_name / ref_length are emitted by nanometanf but were
                         # previously dropped here; surface the reference identity
                         # and genome size in the GUI.
@@ -472,20 +503,23 @@ def parse_nanometanf_aggregate_json(
 
                     # If 'both' method, check for minimap2 fields on a BLAST entry
                     if entry.get('minimap2_mapped') is not None:
+                        mm2_hit_rate = entry.get('minimap2_hit_rate', 0.0) or 0.0
                         mm2_result = ValidationResult(
                             sample_id=sample_id,
                             taxid=tid,
                             species=entry.get('species', ''),
-                            total_reads=kraken_reads,
-                            validated_reads=int(entry.get('minimap2_mapped', 0)),
-                            percent_validated=(
-                                entry.get('minimap2_hit_rate', 0.0) * 100
-                                if entry.get('minimap2_hit_rate', 0.0) <= 1.0
-                                else entry.get('minimap2_hit_rate', 0.0)
+                            total_reads=int(kraken_reads),
+                            validated_reads=int(entry.get('minimap2_mapped', 0) or 0),
+                            percent_validated=min(
+                                100.0,
+                                mm2_hit_rate * 100 if mm2_hit_rate <= 1.0 else mm2_hit_rate,
+                            ),
+                            percent_identity_mean=float(entry.get('minimap2_identity', 0.0) or 0.0),
+                            coverage_breadth=float(
+                                entry.get('minimap2_coverage',
+                                          entry.get('avg_coverage', 0.0)) or 0.0
                             ),
-                            percent_identity_mean=float(entry.get('minimap2_identity', 0.0)),
-                            coverage_breadth=float(entry.get('minimap2_coverage', entry.get('avg_coverage', 0.0))),
-                            avg_mapq=float(entry.get('avg_mapq', 0.0)),
+                            avg_mapq=float(entry.get('avg_mapq', 0.0) or 0.0),
                             reference_accession=entry.get('ref_name', '') or '',
                             reference_length=int(entry.get('ref_length', 0) or 0),
                             validation_method='minimap2',

tests/test_blast_validation_parser.py

@@ -16,6 +16,7 @@
 """
 
 import json
+import time
 from pathlib import Path
 
 import pytest
@@ -104,13 +105,45 @@ def test_missing_file_is_no_data(self, parser, tmp_path):
         assert result.status == ValidationStatus.NO_DATA
 
 
+class TestCacheFingerprintTracksAggregate:
+    """The cache fingerprint must advance when the authoritative aggregate JSON
+    (validation/validation_results.json) is rewritten -- it sits one level above
+    validation_dir (validation/blast), so a naive iterdir misses it and the
+    realtime Validation tab would serve stale results."""
+
+    def test_aggregate_rewrite_advances_fingerprint(self, tmp_path):
+        import os
+        from nanometa_live.core.parsers.blast_validation_parser import ValidationParser
+        vdir = tmp_path / "validation" / "blast"
+        vdir.mkdir(parents=True)
+        (vdir / "barcode01_taxid562.blast.tsv").write_text("x\n")
+        agg = tmp_path / "validation" / "validation_results.json"
+        agg.write_text("{}")
+        old = time.time() - 100
+        os.utime(vdir, (old, old))
+        os.utime(vdir / "barcode01_taxid562.blast.tsv", (old, old))
+        os.utime(agg, (old, old))
+
+        parser = ValidationParser(str(tmp_path))
+        assert parser.validation_dir.name == "blast"
+        fp1 = parser._validation_dir_fingerprint()
+
+        # Rewrite only the aggregate, one level above validation_dir.
+        newer = time.time()
+        agg.write_text('{"results": {}}')
+        os.utime(agg, (newer, newer))
+        fp2 = parser._validation_dir_fingerprint()
+        assert fp2 > fp1
+
+
 class TestDetermineStatusBoundaries:
     """Exact-threshold behaviour of ValidationResult.determine_status().
 
     Authoritative rule (blast_validation_parser.py): CONFIRMED iff
     percent_validated >= 80 AND percent_identity_mean >= 90; PARTIAL iff
-    percent_validated >= 50; LOW_CONFIDENCE iff > 0; else NO_DATA; FAILED on
-    errors. The boundaries are inclusive on the >= side.
+    percent_validated >= 50; LOW_CONFIDENCE iff > 0 OR (validated_reads == 0 but
+    total_reads > 0, i.e. examined-and-negative); NO_DATA only when nothing was
+    examined; FAILED on errors. Boundaries are inclusive on the >= side.
     """
 
     @pytest.mark.parametrize("pv,ident,expected", [
@@ -120,7 +153,8 @@ class TestDetermineStatusBoundaries:
         (79.9, 99.0, ValidationStatus.PARTIAL),       # validated just below 80
         (50.0, 99.0, ValidationStatus.PARTIAL),       # 50 boundary inclusive
         (49.9, 99.0, ValidationStatus.LOW_CONFIDENCE),
-        (0.0, 99.0, ValidationStatus.NO_DATA),        # no reads validated
+        # Examined (reads exist) but nothing validated -> low, NOT no_data.
+        (0.0, 99.0, ValidationStatus.LOW_CONFIDENCE),
     ])
     def test_threshold_boundaries(self, pv, ident, expected):
         # validated/total kept > 0 so the (0,0) early NO_DATA branch is not hit
@@ -133,6 +167,15 @@ def test_threshold_boundaries(self, pv, ident, expected):
         )
         assert r.determine_status() == expected
 
+    def test_examined_zero_hits_is_low_not_no_data(self):
+        # A watchlist organism Kraken classified but BLAST/minimap2 confirmed
+        # none must read as "checked, not confirmed", distinct from "not run".
+        r = ValidationResult(
+            sample_id="s", taxid=1, total_reads=120, validated_reads=0,
+            percent_validated=0.0, validation_method="blast",
+        )
+        assert r.determine_status() == ValidationStatus.LOW_CONFIDENCE
+
     def test_errors_force_failed_even_with_high_metrics(self):
         r = ValidationResult(
             sample_id="s", taxid=1, total_reads=100, validated_reads=100,
@@ -176,6 +219,41 @@ def test_single_blast_entry(self, parser, tmp_path):
         assert r.percent_validated == pytest.approx(90.0)
         assert r.status == ValidationStatus.CONFIRMED
 
+    def test_null_numeric_fields_do_not_drop_the_file(self, parser, tmp_path):
+        # A JSON null on a numeric field must not make None<=1.0 / float(None)
+        # raise and silently empty the whole aggregate (and the Validation tab).
+        f = tmp_path / "validation_results.json"
+        f.write_text(json.dumps(_aggregate({
+            "barcode01": {
+                "562": {
+                    "species": "Escherichia coli",
+                    "kraken_reads": 100,
+                    "blast_hits": None,
+                    "hit_rate": None,
+                    "avg_identity": None,
+                    "avg_coverage": None,
+                    "avg_mapq": None,
+                }
+            }
+        })))
+        results = parser.parse_nanometanf_aggregate_json(f)
+        assert len(results) == 1
+        r = results[0]
+        assert r.validated_reads == 0
+        assert r.percent_validated == 0.0
+        assert r.percent_identity_mean == 0.0
+
+    def test_hit_rate_above_100_is_clamped(self, parser, tmp_path):
+        # A pre-multiplied hit_rate that overshoots 100 (the >1.0 passthrough
+        # branch) must be clamped so the UI never shows e.g. 130%.
+        f = tmp_path / "validation_results.json"
+        f.write_text(json.dumps(_aggregate({
+            "barcode01": {"562": {"species": "E. coli", "kraken_reads": 10,
+                                  "blast_hits": 13, "hit_rate": 130.0,
+                                  "avg_identity": 98.0}}})))
+        r = parser.parse_nanometanf_aggregate_json(f)[0]
+        assert r.percent_validated == 100.0
+
     def test_both_method_expands_to_two_results(self, parser, tmp_path):
         f = tmp_path / "validation_results.json"
         f.write_text(json.dumps(_aggregate({
@@ -259,8 +337,9 @@ def test_both_method_without_minimap2_fields_does_not_expand(self, parser, tmp_p
 
     def test_minimap2_mapped_zero_still_expands(self, parser, tmp_path):
         # ``minimap2_mapped: 0`` is a real (mapped-nothing) outcome, distinct from
-        # an absent key — it must expand to a NO_DATA minimap2 result, not be
-        # silently dropped.
+        # an absent key — it must expand to a result, not be silently dropped.
+        # Reads existed (kraken_reads=100) but none mapped, so the status is
+        # LOW_CONFIDENCE (examined-and-negative), not NO_DATA.
         f = tmp_path / "validation_results.json"
         f.write_text(json.dumps(_aggregate({
             "barcode01": {
@@ -275,7 +354,7 @@ def test_minimap2_mapped_zero_still_expands(self, parser, tmp_path):
         assert len(results) == 2
         mm2 = next(r for r in results if r.validation_method == "minimap2")
         assert mm2.validated_reads == 0
-        assert mm2.status == ValidationStatus.NO_DATA
+        assert mm2.status == ValidationStatus.LOW_CONFIDENCE
 
     def test_mixed_methods_across_taxids_split_correctly(self, parser, tmp_path):
         # One taxid is "both" (-> 2 results), another is blast-only (-> 1). Total 3.

tests/test_validation_tab_callbacks.py

@@ -193,10 +193,13 @@ def test_batch_paf_renders(self, validation_app, enabled_config):
             "barcode01_1773", 0, 10, "batch", "1", enabled_config)
         assert style == {"display": "block"}
 
-    def test_missing_paf_returns_warning_hidden(self, validation_app, enabled_config):
+    def test_missing_paf_shows_warning_visible(self, validation_app, enabled_config):
+        # No PAF: the section must stay VISIBLE so the warning Alert (which lives
+        # inside coverage-plots-section) is actually shown, not swallowed.
         depth, cum, hist, stats, style = self._fn(validation_app)(
             "barcode99_9999", 0, 10, "cumulative", None, enabled_config)
-        assert style == {"display": "none"}
+        assert style == {"display": "block"}
+        assert "No PAF file" in str(stats)
 
     def test_negative_depth_threshold_sanitized(self, validation_app, enabled_config):
         # A negative or None threshold must not raise; it clamps internally.

tests/validation/generate_synthetic_data.py

@@ -359,7 +359,7 @@ def _minimap2_stats_dict(sample, taxid, species, total_reads, mapped_reads,
     ("barcode01", 1773, "minimap2", "confirmed"),   # expanded minimap2 side
     ("barcode01", 1280, "blast", "partial"),        # S. aureus
     ("barcode02", 1639, "minimap2", "confirmed"),   # L. monocytogenes
-    ("barcode03", 562, "blast", "no_data"),         # E. coli (low, no hits)
+    ("barcode03", 562, "blast", "low"),             # E. coli: reads classified, no BLAST hits -> examined-and-negative
     ("barcode05", 263, "minimap2", "confirmed"),    # F. tularensis TUL4 amplicon
 ]