refactor: don't re-calculate side bias

Author: arjunsridhar12345

src/dynamic_foraging_processing/qc/__init__.py

@@ -29,8 +29,6 @@
     ProcessedQC,
     behavior_qc_results,
     calculate_lick_intervals,
-    compute_rolling_bias,
-    compute_side_bias,
     lick_interval_results,
     plot_lick_intervals,
     plot_side_bias,
@@ -53,8 +51,6 @@
     "bool_to_status",
     "build_quality_control",
     "calculate_lick_intervals",
-    "compute_rolling_bias",
-    "compute_side_bias",
     "contract_qc_metrics",
     "lick_interval_results",
     "make_metric",

src/dynamic_foraging_processing/qc/processed/__init__.py

@@ -2,8 +2,6 @@
 
 from dynamic_foraging_processing.qc.processed.behavior import (
     calculate_lick_intervals,
-    compute_rolling_bias,
-    compute_side_bias,
     lick_interval_results,
     side_bias_result,
 )
@@ -18,8 +16,6 @@
     "ProcessedQC",
     "behavior_qc_results",
     "calculate_lick_intervals",
-    "compute_rolling_bias",
-    "compute_side_bias",
     "lick_interval_results",
     "plot_lick_intervals",
     "plot_side_bias",

src/dynamic_foraging_processing/qc/processed/behavior.py

@@ -17,9 +17,6 @@
 SIDE_BIAS_PLOT = "side_bias.png"
 LICK_INTERVALS_PLOT = "lick_intervals.png"
 
-#: ``animal_response`` choice codes.
-_LEFT, _RIGHT, _IGNORE = 0, 1, 2
-
 
 def calculate_lick_intervals(
     left_lick_times: np.ndarray, right_lick_times: np.ndarray
@@ -105,92 +102,36 @@ def calculate_lick_intervals(
     }
 
 
-def compute_side_bias(animal_response: np.ndarray) -> float:
-    """Compute the average side bias over responded trials.
+def side_bias_result(side_bias: np.ndarray) -> QCResult:
+    """Build the average-side-bias ``QCResult`` from the trial-table column.
 
-    Bias is ``mean(is_right) - mean(is_left)`` across trials where the animal
-    responded (``ignore`` trials excluded). The result lies in ``[-1, +1]``;
-    positive means a rightward bias.
+    The per-trial side bias is read directly from the trial table rather than
+    recomputed; this check averages it over the session.
 
     Parameters
     ----------
-    animal_response : numpy.ndarray
-        Per-trial choice codes (``0`` left, ``1`` right, ``2`` ignore).
-
-    Returns
-    -------
-    float
-        The average side bias, or ``nan`` if no trial was responded to.
-    """
-    responses = np.asarray(animal_response)
-    responded = responses != _IGNORE
-    if not responded.any():
-        return float("nan")
-    chosen = responses[responded]
-    return float(np.mean(chosen == _RIGHT) - np.mean(chosen == _LEFT))
-
-
-def compute_rolling_bias(
-    animal_response: np.ndarray, window: int = 20
-) -> t.Tuple[np.ndarray, np.ndarray]:
-    """Compute a trailing-window side-bias trace with a normal-approx CI.
-
-    For each trial, the bias is ``p_right - p_left`` over responded trials in
-    the trailing ``window``; the confidence band is a 95% normal approximation
-    for that difference. Replaces the GUI-precomputed ``B_Bias`` / ``B_Bias_CI``.
-
-    Parameters
-    ----------
-    animal_response : numpy.ndarray
-        Per-trial choice codes (``0`` left, ``1`` right, ``2`` ignore).
-    window : int, optional
-        Number of trailing trials in the rolling window. Defaults to ``20``.
-
-    Returns
-    -------
-    tuple of numpy.ndarray
-        ``(bias, ci)`` where ``bias`` has shape ``(n_trials,)`` and ``ci`` has
-        shape ``(n_trials, 2)``. Trials with no responses are ``nan``.
-    """
-    responses = np.asarray(animal_response)
-    n = len(responses)
-    bias = np.full(n, np.nan)
-    ci = np.full((n, 2), np.nan)
-    for i in range(n):
-        window_slice = responses[max(0, i - window + 1) : i + 1]
-        chosen = window_slice[window_slice != _IGNORE]
-        if len(chosen) == 0:
-            continue
-        p_right = float(np.mean(chosen == _RIGHT))
-        b = 2.0 * p_right - 1.0  # p_right - p_left, since p_left + p_right == 1
-        se = 2.0 * np.sqrt(p_right * (1.0 - p_right) / len(chosen))
-        bias[i] = b
-        ci[i] = (b - 1.96 * se, b + 1.96 * se)
-    return bias, ci
-
-
-def side_bias_result(animal_response: np.ndarray) -> QCResult:
-    """Build the average-side-bias ``QCResult``.
-
-    Parameters
-    ----------
-    animal_response : numpy.ndarray
-        Per-trial choice codes (``0`` left, ``1`` right, ``2`` ignore).
+    side_bias : numpy.ndarray
+        Per-trial side bias from the trial table (right minus left); positive
+        means a rightward bias. Trials with no response are ``nan``.
 
     Returns
     -------
     QCResult
-        Passes when ``abs(mean_bias) < 0.5``. Fails when no trial was responded
-        to (``mean_bias`` is ``nan``). Tagged ``{"behavior": ...}`` and
+        Passes when ``abs(mean_bias) < 0.5``. Fails when the column is empty or
+        all ``nan`` (``mean_bias`` is ``nan``). Tagged ``{"behavior": ...}`` and
         referencing ``side_bias.png``.
     """
-    mean_bias = compute_side_bias(animal_response)
+    values = np.asarray(side_bias, dtype=float)
+    if values.size == 0 or np.all(np.isnan(values)):
+        mean_bias = float("nan")
+    else:
+        mean_bias = float(np.nanmean(values))
     name = "average side bias"
     return QCResult(
         name=name,
         value=mean_bias,
         passed=bool(abs(mean_bias) < 0.5),  # nan comparisons are False -> fails
-        description="Average side bias over responded trials (right minus left).",
+        description="Average of the per-trial side bias (right minus left).",
         reference=SIDE_BIAS_PLOT,
         tags={"behavior": name},
     )

src/dynamic_foraging_processing/qc/processed/plots.py

@@ -18,7 +18,6 @@
 from dynamic_foraging_processing.qc.processed.behavior import (
     LICK_INTERVALS_PLOT,
     SIDE_BIAS_PLOT,
-    compute_rolling_bias,
 )
 
 
@@ -86,18 +85,17 @@ def plot_lick_intervals(
     return LICK_INTERVALS_PLOT
 
 
-def _add_bias_plot(ax: plt.Axes, animal_response: np.ndarray, window: int) -> None:
-    """Draw the rolling side-bias trace with its confidence band."""
+def _add_bias_plot(ax: plt.Axes, side_bias: np.ndarray) -> None:
+    """Draw the per-trial side-bias trace from the trial-table column."""
     ax.set_xlabel("Trial #")
     ax.set_ylabel("Side Bias")
     ax.axhline(+0.7, color="r", linestyle="--")
     ax.axhline(-0.7, color="r", linestyle="--")
     ax.axhline(0, color="k", linestyle="--")
     ax.set_ylim([-1, +1])
 
-    bias, ci = compute_rolling_bias(animal_response, window=window)
+    bias = np.asarray(side_bias, dtype=float)
     trials = np.arange(len(bias))
-    ax.fill_between(trials, ci[:, 0], ci[:, 1], color="gray", alpha=0.5)
     ax.plot(trials, bias, "k", linewidth=2)
     if len(bias):
         ax.set_xlim([0, len(bias)])
@@ -236,6 +234,7 @@ def _add_reward_probabilities(
 
 def plot_side_bias(
     animal_response: np.ndarray,
+    side_bias: np.ndarray,
     results_folder: str,
     *,
     lickspout_x: t.Optional[np.ndarray] = None,
@@ -251,17 +250,18 @@ def plot_side_bias(
     autowater_right: t.Optional[np.ndarray] = None,
     manual_left_times: t.Optional[np.ndarray] = None,
     manual_right_times: t.Optional[np.ndarray] = None,
-    bias_window: int = 20,
 ) -> str:
     """Save the four-panel side-bias figure.
 
-    Panels: rolling side bias (with CI), lickspout position, behavior raster,
-    and reward probabilities.
+    Panels: per-trial side bias, lickspout position, behavior raster, and
+    reward probabilities.
 
     Parameters
     ----------
     animal_response : numpy.ndarray
         Per-trial choice codes (``0`` left, ``1`` right, ``2`` ignore).
+    side_bias : numpy.ndarray
+        Per-trial side bias from the trial table (right minus left).
     results_folder : str
         Directory to write ``side_bias.png`` into.
     lickspout_x, lickspout_y1, lickspout_y2, lickspout_z : numpy.ndarray, optional
@@ -276,8 +276,6 @@ def plot_side_bias(
         Per-trial autowater indicator arrays.
     manual_left_times, manual_right_times : numpy.ndarray, optional
         Manual-water delivery timestamps (s).
-    bias_window : int, optional
-        Trailing window for the rolling bias. Defaults to ``20``.
 
     Returns
     -------
@@ -290,7 +288,7 @@ def plot_side_bias(
         axis.spines["top"].set_visible(False)
         axis.spines["right"].set_visible(False)
 
-    _add_bias_plot(ax[0], animal_response, bias_window)
+    _add_bias_plot(ax[0], side_bias)
     _add_lickspout_position_plot(ax[1], lickspout_x, lickspout_y1, lickspout_y2, lickspout_z)
     _add_behavior_plot(
         ax[2],

src/dynamic_foraging_processing/qc/processed/results.py

@@ -21,6 +21,7 @@
 
 def behavior_qc_results(
     animal_response: np.ndarray,
+    side_bias: np.ndarray,
     left_lick_times: np.ndarray,
     right_lick_times: np.ndarray,
     results_folder: t.Optional[str] = None,
@@ -50,6 +51,8 @@ def behavior_qc_results(
     ----------
     animal_response : numpy.ndarray
         Per-trial choice codes (``0`` left, ``1`` right, ``2`` ignore).
+    side_bias : numpy.ndarray
+        Per-trial side bias from the trial table (right minus left).
     left_lick_times, right_lick_times : numpy.ndarray
         Timestamps (s) of left/right-port licks.
     results_folder : str, optional
@@ -68,12 +71,13 @@ def behavior_qc_results(
         The average-side-bias result followed by the four lick-interval results.
     """
     results = [
-        side_bias_result(animal_response),
+        side_bias_result(side_bias),
         *lick_interval_results(left_lick_times, right_lick_times),
     ]
     if results_folder is not None:
         plot_side_bias(
             animal_response,
+            side_bias,
             results_folder,
             lickspout_x=lickspout_x,
             lickspout_y1=lickspout_y1,

src/dynamic_foraging_processing/qc/processed/stage.py

@@ -21,6 +21,7 @@ class ProcessedQC(BaseQC):
     def run(
         self,
         animal_response: np.ndarray,
+        side_bias: np.ndarray,
         left_lick_times: np.ndarray,
         right_lick_times: np.ndarray,
         results_folder: t.Optional[str] = None,
@@ -49,6 +50,8 @@ def run(
         ----------
         animal_response : numpy.ndarray
             Per-trial choice codes (``0`` left, ``1`` right, ``2`` ignore).
+        side_bias : numpy.ndarray
+            Per-trial side bias from the trial table (right minus left).
         left_lick_times, right_lick_times : numpy.ndarray
             Timestamps (s) of left/right-port licks.
         results_folder : str, optional
@@ -67,6 +70,7 @@ def run(
         """
         results = behavior_qc_results(
             animal_response,
+            side_bias,
             left_lick_times,
             right_lick_times,
             results_folder,