Combine strand decisions into one binary CDS track with background ties

README.md

@@ -76,7 +76,9 @@ The benchmark fetches one row group per source, validates its selected probabili
 
 ## Data and coordinates
 
-The viewer offers **Probabilities** and **Binary labels** modes, with an adjustable threshold defaulting to **0.5**. Binary labels are computed per base and strand as `P(CDS) >= threshold`. Stepped tracks preserve exact labels using their change positions when a strand has at most 20,000 transitions. For denser regions, a clearly labeled overview shows 1 when any base in a bin meets the threshold; zoom in by changing the start/end fields for exact labels. Thresholding happens before binning, so it never thresholds an averaged probability. Mode and threshold changes update the current region without resetting its coordinates. Downloads continue to contain original probabilities.
+The viewer offers **Probabilities** and **Binary labels** modes, with an adjustable threshold defaulting to **0.5**. Binary mode shows one combined CDS/background track: `max(P_positive, P_negative) > threshold`. Either strand can make a base CDS; exact ties are background. This combines the per-strand binary decisions with OR. Validation uses per-strand `argmax` between background and CDS and scores those strand labels; the combined viewer track is not a separate reproduction of those validation metrics. Stored float16 probabilities and inference-window averaging also prevent exact reconstruction of original evaluation logits.
+
+The stepped track preserves exact labels using their change positions when the combined track has at most 20,000 transitions. For denser regions, a clearly labeled overview shows 1 when any base in a bin exceeds the threshold; zoom in by changing the start/end fields for exact labels. Thresholding happens before binning, so it never thresholds an averaged probability. Mode and threshold changes update the current region without resetting its coordinates. Probability mode retains the two strand tracks. Downloads continue to contain original probabilities.
 
 The bucket contains model predictions: positive- and negative-strand per-base P(CDS), metadata, and sometimes sequence. It does not provide curated gene names or gene models. Coordinates are 0-based, end-exclusive. The initial viewport shows the entire selected segment; update the start/end fields to inspect a smaller region. Large windows are averaged into at most 1,200 bins per strand. Downloads retain original probabilities and source columns without downsampling.
 

app.py

@@ -43,7 +43,8 @@ def build_app(catalog=None):
         binary = mode == "Binary labels"
         column = "Predicted CDS" if binary else "P(CDS)"
         figure = go.Figure()
-        for strand, color in [("+ strand", "#2563eb"), ("− strand", "#ea580c")]:
+        tracks = [("CDS (either strand)", "#2563eb")] if binary else [("+ strand", "#2563eb"), ("− strand", "#ea580c")]
+        for strand, color in tracks:
             rows = frame[frame["Strand"] == strand]
             figure.add_trace(go.Scatter(x=rows["Position (bp)"].tolist(), y=rows[column].tolist(),
                                        name=strand, mode="lines",
@@ -51,7 +52,7 @@ def build_app(catalog=None):
         if not binary:
             figure.add_hline(y=threshold, line_dash="dot", line_color="#64748b",
                             annotation_text=f"Threshold {threshold:g}")
-        figure.update_layout(title="Predicted CDS labels by strand" if binary else "CDS probability by strand",
+        figure.update_layout(title="Predicted CDS — either strand" if binary else "CDS probability by strand",
                              xaxis_title="Position (bp; 0-based)", yaxis_title=column,
                              height=360, margin=dict(l=55, r=20, t=50, b=45), template="plotly_white",
                              hovermode="x unified", legend=dict(orientation="h"))
@@ -75,9 +76,10 @@ def build_app(catalog=None):
     def plot_note(step, stats, mode="Probabilities", threshold=0.5):
         origin = "local sample" if stats.get("local") else "cache" if stats["cache_hit"] else "bucket"
         if mode == "Binary labels":
-            resolution = (f"**1 = P(CDS) ≥ {threshold:g}; 0 = below threshold**, evaluated separately on each strand. "
-                          + ("The stepped tracks preserve every base label in this region." if step == 1 else
-                             f"**Binned overview:** each interval spans up to {step:,} bases and is 1 if **any** base meets the threshold. "
+            resolution = (f"**1 = max(P_positive, P_negative) > {threshold:g}; 0 = otherwise.** "
+                          "This is one CDS/background label per base, combining both strands. "
+                          + ("The stepped track preserves every base label in this region." if step == 1 else
+                             f"**Binned overview:** each interval spans up to {step:,} bases and is 1 if **any** base exceeds the threshold. "
                              "This does not mean every base in that interval is CDS. Narrow the region for exact labels."))
         else:
             resolution = "Each point is one base." if step == 1 else f"Each point is the mean of up to **{step:,} bases**; short peaks can be smoothed."
@@ -141,7 +143,7 @@ def build_app(catalog=None):
             view = gr.Button("Update region")
         with gr.Row():
             mode = gr.Radio(["Probabilities", "Binary labels"], value="Probabilities", label="Viewer mode")
-            threshold = gr.Slider(0, 1, value=0.5, step=0.01, label="CDS threshold (P ≥ threshold)")
+            threshold = gr.Slider(0, 1, value=0.5, step=0.01, label="CDS threshold (max strand P > threshold)")
         plot = gr.Plot(label="CDS tracks")
         note = gr.Markdown("Choose a segment to see its probability tracks.")
         with gr.Accordion("Segment metadata and provenance", open=False):

catalog.py

@@ -103,7 +103,7 @@ class Catalog:
             table = self.segment_table(index)
         width = end - start
         if mode == "Binary labels":
-            labels, changes = [], []
+            label = np.zeros(width, dtype=bool)
             for column in PROBS:
                 values = table.column(column)[0].values
                 if len(values) != hi - lo:
@@ -111,20 +111,18 @@ class Catalog:
                 values = values.slice(start - lo, width).to_numpy(zero_copy_only=False).astype(np.float32)
                 if not np.isfinite(values).all():
                     raise ValueError("Cannot assign binary labels to missing or non-finite probabilities.")
-                label = values >= threshold
-                labels.append(label)
-                changes.append(np.flatnonzero(label[1:] != label[:-1]) + 1)
+                # OR the per-strand decisions: max(P_pos, P_neg) > threshold.
+                # Strict > keeps exact ties as background, as binary argmax does.
+                label |= values > threshold
+            transitions = np.flatnonzero(label[1:] != label[:-1]) + 1
             # Preserve every transition when manageable. Only dense regions need an overview.
-            step = 1 if max(map(len, changes)) <= max_transitions else max(1, (width + max_points - 1) // max_points)
-            frames = []
-            for label, transitions, strand in zip(labels, changes, ["+ strand", "− strand"]):
-                offsets = np.r_[0, transitions] if step == 1 else np.arange(0, width, step)
-                values = label[offsets] if step == 1 else np.logical_or.reduceat(label, offsets)
-                # The last point closes the final half-open interval; it adds no base.
-                frames.append(pd.DataFrame({"Position (bp)": np.r_[start + offsets, end],
-                                            "Predicted CDS": np.r_[values, values[-1]].astype(np.uint8),
-                                            "Strand": strand}))
-            return pd.concat(frames, ignore_index=True), step
+            step = 1 if len(transitions) <= max_transitions else max(1, (width + max_points - 1) // max_points)
+            offsets = np.r_[0, transitions] if step == 1 else np.arange(0, width, step)
+            values = label[offsets] if step == 1 else np.logical_or.reduceat(label, offsets)
+            # The last point closes the final half-open interval; it adds no base.
+            return pd.DataFrame({"Position (bp)": np.r_[start + offsets, end],
+                                 "Predicted CDS": np.r_[values, values[-1]].astype(np.uint8),
+                                 "Strand": "CDS (either strand)"}), step
         step = max(1, (width + max_points - 1) // max_points)
         positions = np.arange(start, end, step)
         frames = []

tests/test_catalog.py

@@ -85,32 +85,32 @@ class CoordinateTests(unittest.TestCase):
                 self.catalog.window(0, start, end)
 
     def test_binary_labels_preserve_exact_transitions_and_coordinates(self):
-        frame, step = self.catalog.window(0, 100, 105, mode='Binary labels', threshold=0.4)
+        frame, step = self.catalog.window(0, 100, 105, mode='Binary labels', threshold=0.75)
         self.assertEqual(step, 1)
-        positive = frame[frame.Strand == '+ strand']
-        negative = frame[frame.Strand == '− strand']
-        self.assertEqual(positive['Position (bp)'].tolist(), [100, 102, 105])
-        self.assertEqual(positive['Predicted CDS'].tolist(), [0, 1, 1])
-        self.assertEqual(negative['Position (bp)'].tolist(), [100, 104, 105])
-        self.assertEqual(negative['Predicted CDS'].tolist(), [1, 0, 0])
+        self.assertEqual(frame.Strand.unique().tolist(), ['CDS (either strand)'])
+        self.assertEqual(frame['Position (bp)'].tolist(), [100, 102, 104, 105])
+        self.assertEqual(frame['Predicted CDS'].tolist(), [1, 0, 1, 1])
         self.assertTrue(set(frame['Predicted CDS']).issubset({0, 1}))
 
     def test_binary_overview_thresholds_before_binning(self):
-        frame, step = self.catalog.window(0, 100, 105, mode='Binary labels', threshold=0.4,
+        frame, step = self.catalog.window(0, 100, 105, mode='Binary labels', threshold=0.85,
                                           max_points=2, max_transitions=0)
         self.assertEqual(step, 3)
-        positive = frame[frame.Strand == '+ strand']
-        # First bin's mean is 0.2, but one base reaches 0.4 and must be shown.
-        self.assertEqual(positive['Position (bp)'].tolist(), [100, 103, 105])
-        self.assertEqual(positive['Predicted CDS'].tolist(), [1, 1, 1])
+        # First bin's combined mean is 0.8, but one base exceeds 0.85.
+        self.assertEqual(frame['Position (bp)'].tolist(), [100, 103, 105])
+        self.assertEqual(frame['Predicted CDS'].tolist(), [1, 0, 0])
 
     def test_threshold_limits_and_equality(self):
         frame, _ = self.catalog.window(0, mode='Binary labels', threshold=0)
         self.assertEqual(set(frame['Predicted CDS']), {1})
         frame, _ = self.catalog.window(0, mode='Binary labels', threshold=1)
-        negative = frame[frame.Strand == '− strand']
-        self.assertEqual(negative['Position (bp)'].tolist(), [100, 101, 105])
-        self.assertEqual(negative['Predicted CDS'].tolist(), [1, 0, 0])
+        self.assertEqual(set(frame['Predicted CDS']), {0})
+        table = pa.Table.from_pylist([{
+            'pred_prob_positive_strand_cds': [0.5, 0.1, 0.51, 0.49, 0.5],
+            'pred_prob_negative_strand_cds': [0.1, 0.5, 0.1, 0.1, 0.5]}])
+        frame, _ = self.catalog.window(0, mode='Binary labels', threshold=0.5, table=table)
+        self.assertEqual(frame['Position (bp)'].tolist(), [100, 102, 103, 105])
+        self.assertEqual(frame['Predicted CDS'].tolist(), [0, 1, 0, 0])
         for threshold in [-0.1, 1.1, float('nan')]:
             with self.assertRaises(ValueError):
                 self.catalog.window(0, mode='Binary labels', threshold=threshold)