Causal IGV: apply shared floor-rescale so all reports have scaled tracks

The causal report's IGV renderer was writing signal tracks directly from
raw oracle predictions with per-track autoscale, while the variant-report
IGV was already running a PerTrackNormalizer floor-subtract + rescale to
[0, 3.0] (1.0 = genome-wide p99 peak). That inconsistency meant two
reports from the same run had incomparable y-axes.

Extract the rescale step into ``_igv_report.apply_floor_rescale`` and
call it from both ``build_igv_html`` and ``_build_causal_igv`` so every
IGV panel in every report uses the same scaling by default. Users who
want raw dynamics can opt out via ``CausalResult._igv_raw`` (mirrors the
existing ``VariantReport._igv_raw`` knob).

Regenerated the SORT1 causal example; 36 signal-track panels now use
scaled (min=0, max=3) instead of raw autoscale.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Author: lucapinello

chorus/analysis/_igv_report.py

@@ -130,6 +130,54 @@ def _ensure_igv_local() -> Path | None:
 _DISPLAY_MAX = 3.0
 
 
+def apply_floor_rescale(
+    normalizer,
+    oracle_name: str | None,
+    assay_id: str,
+    layer: str,
+    ref_vals,
+    alt_vals,
+):
+    """Floor-subtract + rescale a ref/alt value pair using the normalizer.
+
+    Returns ``(floor_ok, ref_scaled, alt_scaled)``.  When ``floor_ok`` is
+    ``True`` the returned arrays are mapped to ``[0, _DISPLAY_MAX]`` with
+    layer-aware thresholds (p95 / p99 for sharp signals, p90 / p99 for
+    broad histone marks) — 1.0 on the y-axis then corresponds to the
+    genome-wide p99 peak in that assay, making tracks comparable across
+    assays *and* across reports. When False, callers should fall back to
+    raw autoscale.
+
+    This helper is shared by the standard variant-report IGV
+    (:func:`build_igv_html`) and the causal-report IGV
+    (:func:`chorus.analysis.causal._build_causal_igv`) so both reports
+    render the same "scaled-by-default" IGV tracks.
+    """
+    if normalizer is None or oracle_name is None:
+        return False, ref_vals, alt_vals
+    from .normalization import PerTrackNormalizer
+    if not isinstance(normalizer, PerTrackNormalizer):
+        return False, ref_vals, alt_vals
+    floor_p = _LAYER_FLOOR_PCTILE.get(layer, _DEFAULT_FLOOR_PCTILE)
+    ref_fl = normalizer.perbin_floor_rescale_batch(
+        oracle_name, assay_id, ref_vals,
+        floor_pctile=floor_p,
+        peak_pctile=_PEAK_PCTILE,
+        max_value=_DISPLAY_MAX,
+    )
+    if ref_fl is None:
+        return False, ref_vals, alt_vals
+    alt_fl = normalizer.perbin_floor_rescale_batch(
+        oracle_name, assay_id, alt_vals,
+        floor_pctile=floor_p,
+        peak_pctile=_PEAK_PCTILE,
+        max_value=_DISPLAY_MAX,
+    )
+    if alt_fl is None:
+        return False, ref_vals, alt_vals
+    return True, ref_fl, alt_fl
+
+
 def build_igv_html(
     ref_pred,
     alt_pred,
@@ -231,25 +279,9 @@ def build_igv_html(
         # Apply layer-aware floor-subtract + rescale when available
         floor_ok = False
         if use_floor:
-            from .normalization import PerTrackNormalizer
-            if isinstance(normalizer, PerTrackNormalizer):
-                floor_p = _LAYER_FLOOR_PCTILE.get(layer, _DEFAULT_FLOOR_PCTILE)
-                ref_fl = normalizer.perbin_floor_rescale_batch(
-                    oracle_name, assay_id, ref_vals,
-                    floor_pctile=floor_p,
-                    peak_pctile=_PEAK_PCTILE,
-                    max_value=_DISPLAY_MAX,
-                )
-                if ref_fl is not None:
-                    alt_fl = normalizer.perbin_floor_rescale_batch(
-                        oracle_name, assay_id, alt_vals,
-                        floor_pctile=floor_p,
-                        peak_pctile=_PEAK_PCTILE,
-                        max_value=_DISPLAY_MAX,
-                    )
-                    ref_vals = ref_fl
-                    alt_vals = alt_fl
-                    floor_ok = True
+            floor_ok, ref_vals, alt_vals = apply_floor_rescale(
+                normalizer, oracle_name, assay_id, layer, ref_vals, alt_vals,
+            )
 
         ref_features = _downsample_to_features(
             ref_vals, variant_chrom, t_start, t_res, bin_size,

chorus/analysis/causal.py

@@ -96,6 +96,11 @@ class CausalResult:
     cell_types: list[str] = field(default_factory=list)
     nearby_genes: list[str] = field(default_factory=list)
     analysis_request: AnalysisRequest | None = None
+    # When True, the IGV browser shows raw predicted signal with autoscale
+    # instead of the layer-aware floor-rescale (1.0 = genome-wide p99).
+    # Default False so tracks are cross-comparable by default, matching the
+    # rest of Chorus; flip to True only when raw dynamics matter.
+    _igv_raw: bool = field(default=False, repr=False)
 
     def top_candidate(self) -> CausalVariantScore:
         """Return the highest-ranked variant."""
@@ -973,7 +978,12 @@ def _build_causal_igv(result: CausalResult) -> str:
 
         if ref_pred and alt_pred:
             from .scorers import classify_track_layer
-            from ._igv_report import _downsample_to_features, _LAYER_COLORS, _REF_COLOR
+            from ._igv_report import (
+                _DISPLAY_MAX,
+                _REF_COLOR,
+                _downsample_to_features,
+                apply_floor_rescale,
+            )
 
             assay_ids = list(ref_pred.keys())
             first_track = ref_pred[assay_ids[0]]
@@ -983,20 +993,47 @@ def _build_causal_igv(result: CausalResult) -> str:
             bin_size = max(1, window_bp // 3000)
             alt_rgb = _TOP_VARIANT_COLORS[vi]["r"] if vi < len(_TOP_VARIANT_COLORS) else "70,130,180"
 
+            # Route signal tracks through the shared floor-rescale helper
+            # so the causal IGV looks like every other Chorus report:
+            # 1.0 = genome-wide p99 peak. Users opt out via
+            # CausalResult._igv_raw (set by the caller) or by building
+            # variant reports with ``igv_raw=True``.
+            normalizer = getattr(top_s._variant_report, "_normalizer", None)
+            oracle_name = getattr(top_s._variant_report, "oracle_name", None)
+            igv_raw = (
+                getattr(result, "_igv_raw", False)
+                or getattr(top_s._variant_report, "_igv_raw", False)
+            )
+            if igv_raw:
+                normalizer = None
+
             for aid in assay_ids:
                 ref_t = ref_pred[aid]
                 alt_t = alt_pred[aid]
                 t_start = ref_t.prediction_interval.reference.start
                 t_res = ref_t.resolution
 
+                layer = classify_track_layer(ref_t)
+                floor_ok, ref_vals, alt_vals = apply_floor_rescale(
+                    normalizer, oracle_name, aid, layer,
+                    ref_t.values, alt_t.values,
+                )
+
                 ref_feats = _downsample_to_features(
-                    ref_t.values, chrom, t_start, t_res, bin_size,
+                    ref_vals, chrom, t_start, t_res, bin_size,
+                    skip_zeros=not floor_ok,
                 )
                 alt_feats = _downsample_to_features(
-                    alt_t.values, chrom, t_start, t_res, bin_size,
+                    alt_vals, chrom, t_start, t_res, bin_size,
+                    skip_zeros=not floor_ok,
                 )
 
                 group_id = f"{aid}_{top_s.variant_id}".replace(":", "_").replace(" ", "_")
+                if floor_ok:
+                    scale_cfg = {"min": 0, "max": _DISPLAY_MAX, "autoscale": False}
+                else:
+                    scale_cfg = {"autoscale": True, "autoscaleGroup": group_id}
+
                 rank_label = _TOP_VARIANT_COLORS[vi]["label"] if vi < len(_TOP_VARIANT_COLORS) else f"#{vi+1}"
                 tracks.append({
                     "name": f"{aid} ({rank_label} {top_s.variant_id})",
@@ -1007,16 +1044,14 @@ def _build_causal_igv(result: CausalResult) -> str:
                             "type": "wig",
                             "name": f"{aid} ref",
                             "color": f"rgb({_REF_COLOR})",
-                            "autoscale": True,
-                            "autoscaleGroup": group_id,
+                            **scale_cfg,
                             "features": ref_feats,
                         },
                         {
                             "type": "wig",
                             "name": f"{aid} alt",
                             "color": f"rgb({alt_rgb})",
-                            "autoscale": True,
-                            "autoscaleGroup": group_id,
+                            **scale_cfg,
                             "features": alt_feats,
                         },
                     ],