multi-oracle: distinguish n=1 single-voter from real multi-oracle consensus

The consensus matrix previously rendered a single oracle's direction as
"all ↑" / "all ↓" — technically correct (all reporting oracles agree
trivially when there's one) but misleading to users who see "all ↑"
and assume multiple oracles concurred. v11 content-review audit
caught this on the committed SORT1 multi-oracle example, where
chrombpnet, legnet, and alphagenome are specialists — each reports a
different subset of layers — and the three "all ↑" rows in the matrix
were actually single-oracle votes.

Change:
- _consensus_rows now emits "single_gain" / "single_loss" when
  exactly one oracle reports a direction, separate from
  "consensus_gain" / "consensus_loss" which now require ≥2 oracles.
- Markdown renders as "only ↑ (n=1)" / "only ↓ (n=1)"; HTML uses
  "↑ only (n=1)" / "↓ only (n=1)" with a new neutral-grey
  .agree-single CSS class so users visually distinguish trivial
  single-voter layers from real cross-oracle consensus.
- Existing "all ↑" / "all ↓" labels still fire when 2+ oracles agree.

Regenerated SORT1 rs12740374 multi-oracle example (it was the direct
case that exposed the bug): the three previously-"all ↑" single-voter
layers (TF binding, histone marks, CAGE — all AlphaGenome-only) now
correctly read "only ↑ (n=1)". The "disagree" chromatin row (AG vs
ChromBPNet) and any future ≥2-oracle consensus rows are unchanged.

Tests: +1 regression test (test_single_voter_layer_uses_n1_label_not_all)
that verifies both agreement dict values ("single_gain"/"single_loss")
and the user-visible strings in MD + HTML. All existing multi-oracle
tests still pass (they all use ≥2 oracles per layer, so the
consensus_gain / consensus_loss path is untouched).

Verified: pytest -m "not integration" → 325 passed (was 324).

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

Author: lp698

chorus/analysis/multi_oracle_report.py

@@ -238,10 +238,16 @@ def _consensus_rows(self) -> list[dict]:
                     "quantile_score": best.quantile_score,
                 }
                 directions.append(1 if best.raw_score > 0 else -1)
+            # "Consensus" requires at least two voting oracles; a single
+            # voter is recorded as ``single_gain`` / ``single_loss`` so the
+            # rendered label doesn't read "all ↑" when only one oracle
+            # actually scored the layer.
             if directions:
                 pos = sum(1 for d in directions if d > 0)
                 neg = len(directions) - pos
-                if pos == len(directions):
+                if len(directions) == 1:
+                    entry["agreement"] = "single_gain" if pos == 1 else "single_loss"
+                elif pos == len(directions):
                     entry["agreement"] = "consensus_gain"
                 elif neg == len(directions):
                     entry["agreement"] = "consensus_loss"
@@ -308,6 +314,8 @@ def to_markdown(self) -> str:
             agree = {
                 "consensus_gain": "all ↑",
                 "consensus_loss": "all ↓",
+                "single_gain": "only ↑ (n=1)",
+                "single_loss": "only ↓ (n=1)",
                 "disagree": "disagree",
                 "no_data": "—",
             }[row["agreement"]]
@@ -328,6 +336,10 @@ def to_markdown(self) -> str:
                                font-weight: 600; }
 .consensus-table .agree-mixed { background: #fff3cd; color: #856404;
                                 font-weight: 600; }
+/* single-voter — neutral grey so users see that only one oracle
+   reported a direction (no real consensus possible). */
+.consensus-table .agree-single { background: #f3f4f6; color: #4b5563;
+                                 font-weight: 500; }
 .consensus-table .agree-none { color: #adb5bd; }
 .consensus-table td.effect-cell { font-family: ui-monospace, SFMono-Regular,
                                   Menlo, monospace; font-size: 0.85rem; }
@@ -447,6 +459,8 @@ def _build_multioracle_html(report: "MultiOracleReport") -> str:
         agree_label, agree_cls = {
             "consensus_gain": ("✅ all ↑", "agree-gain"),
             "consensus_loss": ("✅ all ↓", "agree-loss"),
+            "single_gain": ("↑ only (n=1)", "agree-single"),
+            "single_loss": ("↓ only (n=1)", "agree-single"),
             "disagree": ("⚠ disagree", "agree-mixed"),
             "no_data": ("—", "agree-none"),
         }[agree]

examples/applications/validation/SORT1_rs12740374_multioracle/example_output.json

@@ -10,9 +10,9 @@
   },
   "gene_name": "SORT1",
   "oracles": [
-    "alphagenome",
     "chrombpnet",
-    "legnet"
+    "legnet",
+    "alphagenome"
   ],
   "per_oracle_report_paths": {
     "legnet": "rs12740374_SORT1_legnet_report.html"
@@ -21,87 +21,87 @@
     {
       "layer": "chromatin_accessibility",
       "oracles": {
-        "alphagenome": {
-          "raw_score": 0.4525551981440325,
-          "assay_id": "DNASE/EFO:0001187 DNase-seq/.",
-          "cell_type": "HepG2",
-          "quantile_score": 1.0
-        },
         "chrombpnet": {
           "raw_score": -0.11089156202257182,
           "assay_id": "ATAC:HepG2",
           "cell_type": "HepG2",
           "quantile_score": 0.96721823290665
         },
-        "legnet": null
+        "legnet": null,
+        "alphagenome": {
+          "raw_score": 0.4525551981440325,
+          "assay_id": "DNASE/EFO:0001187 DNase-seq/.",
+          "cell_type": "HepG2",
+          "quantile_score": 1.0
+        }
       },
       "agreement": "disagree"
     },
+    {
+      "layer": "promoter_activity",
+      "oracles": {
+        "chrombpnet": null,
+        "legnet": {
+          "raw_score": -0.0278623104095459,
+          "assay_id": "LentiMPRA:HepG2",
+          "cell_type": "HepG2",
+          "quantile_score": null
+        },
+        "alphagenome": null
+      },
+      "agreement": "single_loss"
+    },
     {
       "layer": "tf_binding",
       "oracles": {
+        "chrombpnet": null,
+        "legnet": null,
         "alphagenome": {
           "raw_score": 0.3806839182959419,
           "assay_id": "CHIP_TF/EFO:0001187 TF ChIP-seq CEBPA genetically modified (insertion) using CRISPR targeting H. sapiens CEBPA/.",
           "cell_type": "HepG2",
           "quantile_score": 1.0
-        },
-        "chrombpnet": null,
-        "legnet": null
+        }
       },
-      "agreement": "consensus_gain"
+      "agreement": "single_gain"
     },
     {
       "layer": "histone_marks",
       "oracles": {
+        "chrombpnet": null,
+        "legnet": null,
         "alphagenome": {
           "raw_score": 0.17998971913566533,
           "assay_id": "CHIP_HISTONE/EFO:0001187 Histone ChIP-seq H3K27ac/.",
           "cell_type": "HepG2",
           "quantile_score": 1.0
-        },
-        "chrombpnet": null,
-        "legnet": null
+        }
       },
-      "agreement": "consensus_gain"
+      "agreement": "single_gain"
     },
     {
       "layer": "tss_activity",
       "oracles": {
+        "chrombpnet": null,
+        "legnet": null,
         "alphagenome": {
           "raw_score": 0.2541795926080432,
           "assay_id": "CAGE/hCAGE EFO:0001187/-",
           "cell_type": "HepG2",
           "quantile_score": 1.0
-        },
-        "chrombpnet": null,
-        "legnet": null
-      },
-      "agreement": "consensus_gain"
-    },
-    {
-      "layer": "promoter_activity",
-      "oracles": {
-        "alphagenome": null,
-        "chrombpnet": null,
-        "legnet": {
-          "raw_score": -0.0278623104095459,
-          "assay_id": "LentiMPRA:HepG2",
-          "cell_type": "HepG2",
-          "quantile_score": null
         }
       },
-      "agreement": "consensus_loss"
+      "agreement": "single_gain"
     }
   ],
   "analysis_request": {
-    "user_prompt": "Analyze rs12740374 (chr1:109274968 G>T) in HepG2 liver cells using DNASE, CEBPA/CEBPB ChIP, H3K27ac, and CAGE tracks. Gene is SORT1.",
-    "tool_name": "analyze_variant_multilayer",
-    "oracle_name": "alphagenome",
-    "normalizer_name": "per-track background CDFs",
-    "tracks_requested": "6 HepG2 tracks",
+    "user_prompt": "Validate rs12740374 (the classic SORT1 LDL-cholesterol causal variant) by scoring it with three independent deep-learning oracles: ChromBPNet for chromatin accessibility, LegNet for MPRA promoter activity, and AlphaGenome as a generalist model covering ChIP, histones and CAGE. A new user should be able to see at a glance whether the three oracles agree on direction, and which assay/cell type drove each call.",
+    "tool_name": "MultiOracleReport",
+    "oracle_name": "chrombpnet, legnet, alphagenome",
+    "normalizer_name": "per-oracle chorus per-track v1",
+    "tracks_requested": "assay_ids as listed in each per-oracle request",
     "cell_types": [],
     "notes": [],
-    "generated_at": "2026-04-17 19:45 UTC"
+    "generated_at": "2026-04-19 18:35 UTC"
   }
 }

examples/applications/validation/SORT1_rs12740374_multioracle/example_output.md

@@ -2,14 +2,14 @@
 
 - **Variant:** chr1:109,274,968 G>T
 - **Gene:** SORT1
-- **Oracles:** alphagenome, chrombpnet, legnet
+- **Oracles:** chrombpnet, legnet, alphagenome
 
 ## Cross-oracle consensus
 
-| Layer | alphagenome | chrombpnet | legnet | Agreement |
+| Layer | chrombpnet | legnet | alphagenome | Agreement |
 |---|---|---|---|---|
-| Chromatin accessibility (DNASE/ATAC) (log2fc) | +0.453 · DNASE/EFO:0001187 DNase-seq/. · HepG2 | -0.111 · ATAC:HepG2 · HepG2 | — | disagree |
-| Transcription factor binding (ChIP-TF) (log2fc) | +0.381 · CHIP_TF/EFO:0001187 TF ChIP-seq CEBPA genetically modified (insertion) using CRISPR targeting H. sapiens CEBPA/. · HepG2 | — | — | all ↑ |
-| Histone modifications (ChIP-Histone) (log2fc) | +0.180 · CHIP_HISTONE/EFO:0001187 Histone ChIP-seq H3K27ac/. · HepG2 | — | — | all ↑ |
-| TSS activity (CAGE/PRO-CAP) (log2fc) | +0.254 · CAGE/hCAGE EFO:0001187/- · HepG2 | — | — | all ↑ |
-| Promoter activity (MPRA) (diff) | — | — | -0.028 · LentiMPRA:HepG2 · HepG2 | all ↓ |
+| Chromatin accessibility (DNASE/ATAC) (log2fc) | -0.111 · ATAC:HepG2 · HepG2 | — | +0.453 · DNASE/EFO:0001187 DNase-seq/. · HepG2 | disagree |
+| Promoter activity (MPRA) (diff) | — | -0.028 · LentiMPRA:HepG2 · HepG2 | — | only ↓ (n=1) |
+| Transcription factor binding (ChIP-TF) (log2fc) | — | — | +0.381 · CHIP_TF/EFO:0001187 TF ChIP-seq CEBPA genetically modified (insertion) using CRISPR targeting H. sapiens CEBPA/. · HepG2 | only ↑ (n=1) |
+| Histone modifications (ChIP-Histone) (log2fc) | — | — | +0.180 · CHIP_HISTONE/EFO:0001187 Histone ChIP-seq H3K27ac/. · HepG2 | only ↑ (n=1) |
+| TSS activity (CAGE/PRO-CAP) (log2fc) | — | — | +0.254 · CAGE/hCAGE EFO:0001187/- · HepG2 | only ↑ (n=1) |