TwoPy 0.1.0__py3-none-any.whl

twopy/analysis/responses.py

@@ -0,0 +1,345 @@
+"""Group ROI responses by stimulus epoch and trial.
+
+Inputs: computed ROI dF/F traces and stimulus-labeled frame windows.
+Outputs: per-trial response arrays and compact per-ROI summary rows.
+
+This module keeps response grouping independent from plotting, napari, and file
+storage. It only works with converted twopy analysis objects that already have
+explicit frame coordinates.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import numpy as np
+import numpy.typing as npt
+
+from twopy.analysis.dff import RoiDeltaFOverF
+from twopy.analysis.trials import EpochFrameWindow
+
+__all__ = [
+    "GroupedRoiResponseSummary",
+    "GroupedRoiResponses",
+    "RoiResponseSummary",
+    "RoiResponseTrial",
+    "group_delta_f_over_f_by_epoch",
+    "is_gray_epoch_name",
+    "summarize_epoch_roi_responses",
+    "summarize_grouped_responses",
+]
+
+
+@dataclass(frozen=True)
+class RoiResponseTrial:
+    """One ROI response matrix for one stimulus trial.
+
+    Inputs: one stimulus-labeled frame window and a slice of ROI dF/F.
+    Outputs: frame-by-ROI values plus absolute frame numbers and relative time.
+
+    ``trial_index`` is one-based within each epoch because that is the number a
+    scientist naturally uses when checking repeated presentations.
+    """
+
+    epoch_number: int
+    epoch_name: str
+    trial_index: int
+    window_index: int
+    start_frame: int
+    stop_frame: int
+    frame_numbers: npt.NDArray[np.int64]
+    time_seconds: npt.NDArray[np.float64]
+    values: npt.NDArray[np.float64]
+
+
+@dataclass(frozen=True)
+class GroupedRoiResponses:
+    """ROI responses grouped by epoch and trial.
+
+    Inputs: one dF/F result plus epoch windows.
+    Outputs: trial response objects, ROI labels, and the frame rate used for
+    relative trial time.
+
+    The values stay as one matrix per trial instead of being padded into a
+    larger cube. This avoids fake samples when trial lengths differ.
+    """
+
+    roi_labels: tuple[str, ...]
+    data_rate_hz: float
+    trials: tuple[RoiResponseTrial, ...]
+
+
+@dataclass(frozen=True)
+class RoiResponseSummary:
+    """Compact response metrics for one ROI in one trial.
+
+    Inputs: one trial response matrix.
+    Outputs: mean, peak, minimum, and frame metadata for one ROI.
+
+    These rows are intentionally simple so they can be written to CSV and
+    inspected without custom Python code.
+    """
+
+    epoch_number: int
+    epoch_name: str
+    trial_index: int
+    window_index: int
+    roi_label: str
+    start_frame: int
+    stop_frame: int
+    frame_count: int
+    mean_response: float
+    peak_response: float
+    min_response: float
+
+
+@dataclass(frozen=True)
+class GroupedRoiResponseSummary:
+    """Response metrics collapsed across trials for one epoch and ROI.
+
+    Inputs: trial-level response summaries for one ``(epoch, ROI)`` pair.
+    Outputs: mean response, SEM, and the trial count behind those values.
+
+    A single usable trial gets SEM ``0`` because there is no across-trial spread
+    to estimate. Empty or all-NaN groups are not emitted.
+    """
+
+    epoch_number: int
+    epoch_name: str
+    roi_label: str
+    mean_response: float
+    sem_response: float
+    n_trials: int
+
+
+def group_delta_f_over_f_by_epoch(
+    dff: RoiDeltaFOverF,
+    epoch_windows: Sequence[EpochFrameWindow],
+    *,
+    data_rate_hz: float,
+    pre_window_seconds: float = 0.0,
+    post_window_seconds: float = 0.0,
+) -> GroupedRoiResponses:
+    """Group dF/F values by stimulus epoch windows.
+
+    Args:
+        dff: Computed ROI dF/F with absolute frame coordinates.
+        epoch_windows: Stimulus-labeled windows to slice.
+        data_rate_hz: Imaging frame rate in hertz for relative trial time.
+        pre_window_seconds: Seconds before each epoch window to include. This
+            is useful for plots that show the gray interleave baseline before
+            stimulus onset.
+        post_window_seconds: Seconds after each epoch window to include. This
+            is useful for plots that show the response returning into the next
+            gray interleave.
+
+    Returns:
+        ``GroupedRoiResponses`` with one response object per input window.
+
+    Raises:
+        ValueError: If the dF/F shape, frame rate, or windows are invalid.
+
+    The function only groups existing dF/F values. It does not decide which
+    windows are trials and does not recompute fluorescence.
+    """
+    _validate_grouping_inputs(
+        dff,
+        epoch_windows,
+        data_rate_hz,
+        pre_window_seconds,
+        post_window_seconds,
+    )
+
+    trials: list[RoiResponseTrial] = []
+    epoch_counts: dict[tuple[int, str], int] = {}
+    pre_window_frames = int(round(pre_window_seconds * data_rate_hz))
+    post_window_frames = int(round(post_window_seconds * data_rate_hz))
+    for epoch_window in epoch_windows:
+        key = (epoch_window.epoch_number, epoch_window.epoch_name)
+        epoch_counts[key] = epoch_counts.get(key, 0) + 1
+        window = epoch_window.window
+        response_start_frame = max(
+            window.start_frame - pre_window_frames, dff.start_frame
+        )
+        response_stop_frame = min(
+            window.stop_frame + post_window_frames,
+            dff.stop_frame,
+        )
+        local_start = response_start_frame - dff.start_frame
+        local_stop = response_stop_frame - dff.start_frame
+        frame_numbers = np.arange(
+            response_start_frame, response_stop_frame, dtype=np.int64
+        )
+        time_seconds = (frame_numbers - window.start_frame) / data_rate_hz
+        trials.append(
+            RoiResponseTrial(
+                epoch_number=epoch_window.epoch_number,
+                epoch_name=epoch_window.epoch_name,
+                trial_index=epoch_counts[key],
+                window_index=window.index,
+                start_frame=response_start_frame,
+                stop_frame=response_stop_frame,
+                frame_numbers=frame_numbers,
+                time_seconds=time_seconds.astype(np.float64, copy=False),
+                values=dff.values[local_start:local_stop, :],
+            ),
+        )
+
+    return GroupedRoiResponses(
+        roi_labels=dff.labels,
+        data_rate_hz=float(data_rate_hz),
+        trials=tuple(trials),
+    )
+
+
+def summarize_grouped_responses(
+    grouped: GroupedRoiResponses,
+) -> tuple[RoiResponseSummary, ...]:
+    """Summarize grouped responses with one row per trial and ROI.
+
+    Args:
+        grouped: Grouped response object.
+
+    Returns:
+        Tuple of compact response summary rows.
+
+    The summary uses NaN-aware metrics so motion-masked dF/F frames do not make
+    an entire trial unusable.
+    """
+    summaries: list[RoiResponseSummary] = []
+    for trial in grouped.trials:
+        if trial.values.shape[1] != len(grouped.roi_labels):
+            msg = (
+                "Trial response width does not match ROI labels: "
+                f"{trial.values.shape[1]} values, {len(grouped.roi_labels)} labels"
+            )
+            raise ValueError(msg)
+        for roi_index, roi_label in enumerate(grouped.roi_labels):
+            values = trial.values[:, roi_index]
+            summaries.append(
+                RoiResponseSummary(
+                    epoch_number=trial.epoch_number,
+                    epoch_name=trial.epoch_name,
+                    trial_index=trial.trial_index,
+                    window_index=trial.window_index,
+                    roi_label=roi_label,
+                    start_frame=trial.start_frame,
+                    stop_frame=trial.stop_frame,
+                    frame_count=trial.stop_frame - trial.start_frame,
+                    mean_response=float(np.nanmean(values)),
+                    peak_response=float(np.nanmax(values)),
+                    min_response=float(np.nanmin(values)),
+                ),
+            )
+    return tuple(summaries)
+
+
+def summarize_epoch_roi_responses(
+    grouped: GroupedRoiResponses,
+) -> tuple[GroupedRoiResponseSummary, ...]:
+    """Summarize responses across trials with one row per epoch and ROI.
+
+    Args:
+        grouped: Grouped response object.
+
+    Returns:
+        Tuple of grouped summary rows.
+
+    The grouped mean and SEM are computed from trial-level mean responses, not
+    from every frame pooled together. That keeps each trial at equal weight even
+    if window lengths differ slightly.
+    """
+    trial_summaries = summarize_grouped_responses(grouped)
+    grouped_values: dict[tuple[int, str, str], list[float]] = {}
+    for summary in trial_summaries:
+        if np.isnan(summary.mean_response):
+            continue
+        key = (summary.epoch_number, summary.epoch_name, summary.roi_label)
+        grouped_values.setdefault(key, []).append(summary.mean_response)
+
+    rows: list[GroupedRoiResponseSummary] = []
+    for key, values in grouped_values.items():
+        epoch_number, epoch_name, roi_label = key
+        response_values = np.asarray(values, dtype=np.float64)
+        trial_count = int(response_values.size)
+        sem = (
+            float(np.nanstd(response_values, ddof=1) / np.sqrt(trial_count))
+            if trial_count > 1
+            else 0.0
+        )
+        rows.append(
+            GroupedRoiResponseSummary(
+                epoch_number=epoch_number,
+                epoch_name=epoch_name,
+                roi_label=roi_label,
+                mean_response=float(np.nanmean(response_values)),
+                sem_response=sem,
+                n_trials=trial_count,
+            ),
+        )
+    return tuple(rows)
+
+
+def is_gray_epoch_name(epoch_name: str) -> bool:
+    """Return whether an epoch name looks like a gray interleave.
+
+    Args:
+        epoch_name: Stimulus epoch name.
+
+    Returns:
+        ``True`` for ``gray`` or ``grey`` spelling.
+    """
+    lowered = epoch_name.lower()
+    return "gray" in lowered or "grey" in lowered
+
+
+def _validate_grouping_inputs(
+    dff: RoiDeltaFOverF,
+    epoch_windows: Sequence[EpochFrameWindow],
+    data_rate_hz: float,
+    pre_window_seconds: float,
+    post_window_seconds: float,
+) -> None:
+    """Validate response grouping inputs.
+
+    Args:
+        dff: Candidate dF/F result.
+        epoch_windows: Candidate windows.
+        data_rate_hz: Candidate frame rate.
+        pre_window_seconds: Candidate prestimulus duration.
+        post_window_seconds: Candidate poststimulus duration.
+
+    Returns:
+        None.
+    """
+    if dff.values.ndim != 2:
+        msg = f"dF/F values must have shape (frames, rois); got {dff.values.shape}"
+        raise ValueError(msg)
+    if dff.values.shape[1] != len(dff.labels):
+        msg = (
+            f"dF/F labels length {len(dff.labels)} does not match "
+            f"{dff.values.shape[1]} ROIs"
+        )
+        raise ValueError(msg)
+    if data_rate_hz <= 0:
+        msg = f"data_rate_hz must be positive; got {data_rate_hz}"
+        raise ValueError(msg)
+    if pre_window_seconds < 0:
+        msg = f"pre_window_seconds must be nonnegative; got {pre_window_seconds}"
+        raise ValueError(msg)
+    if post_window_seconds < 0:
+        msg = f"post_window_seconds must be nonnegative; got {post_window_seconds}"
+        raise ValueError(msg)
+    for epoch_window in epoch_windows:
+        window = epoch_window.window
+        if window.start_frame < dff.start_frame or window.stop_frame > dff.stop_frame:
+            msg = (
+                f"Window [{window.start_frame}, {window.stop_frame}) is outside "
+                f"dF/F range [{dff.start_frame}, {dff.stop_frame})"
+            )
+            raise ValueError(msg)
+        if window.start_frame >= window.stop_frame:
+            msg = (
+                f"Window [{window.start_frame}, {window.stop_frame}) must have "
+                "positive duration"
+            )
+            raise ValueError(msg)

twopy/analysis/trials.py

@@ -0,0 +1,341 @@
+"""Split ROI traces into frame windows for response analysis.
+
+Inputs: converted recordings, ROI traces, frame boundaries, and photodiode
+alignment.
+Outputs: frame windows, stimulus-epoch labels, and windowed ROI response
+arrays.
+
+This module keeps trial slicing independent from the GUI and from source files.
+Stimulus-specific labels can be added when the stimulus metadata has been
+decoded.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import numpy as np
+import numpy.typing as npt
+
+from twopy.converted import RecordingData
+from twopy.photodiode_classification import classify_recording_photodiode_events
+from twopy.roi import RoiTraces
+from twopy.synchronization import PhotodiodeAlignment
+
+__all__ = [
+    "EpochFrameWindow",
+    "FrameWindow",
+    "WindowedRoiResponse",
+    "frame_windows_from_photodiode_alignment",
+    "make_frame_windows",
+    "map_stimulus_epochs_to_frame_windows",
+    "select_epoch_frame_windows",
+    "split_traces_by_frame_windows",
+]
+
+
+@dataclass(frozen=True)
+class FrameWindow:
+    """One half-open frame interval.
+
+    Inputs: start and stop frame indices in aligned movie coordinates.
+    Outputs: a labeled interval that can slice ROI traces.
+
+    ``start_frame`` is inclusive and ``stop_frame`` is exclusive, matching
+    Python slicing and HDF5 frame reads.
+    """
+
+    index: int
+    start_frame: int
+    stop_frame: int
+    label: str
+
+
+@dataclass(frozen=True)
+class EpochFrameWindow:
+    """One photodiode-aligned frame window with stimulus epoch metadata.
+
+    Inputs: one frame window and the matching stimulus epoch run.
+    Outputs: frame bounds plus the epoch number and epoch name.
+
+    This object is the bridge between stimulus-computer rows and imaging-frame
+    movie slices. It is intentionally small so later response code can inspect
+    exactly which epoch each frame window came from.
+    """
+
+    window: FrameWindow
+    epoch_number: int
+    epoch_name: str
+
+
+@dataclass(frozen=True)
+class WindowedRoiResponse:
+    """ROI traces for one frame window.
+
+    Inputs: one ``FrameWindow`` and the matching slice of ``RoiTraces``.
+    Outputs: frame-by-ROI values plus ROI labels.
+
+    The values remain in frame order so callers can compute baselines,
+    peak responses, averages, or plots without losing timing.
+    """
+
+    window: FrameWindow
+    values: npt.NDArray[np.float64]
+    roi_labels: tuple[str, ...]
+
+
+def make_frame_windows(
+    boundary_frames: Sequence[int],
+    *,
+    frame_count: int,
+    labels: Sequence[str] | None = None,
+) -> tuple[FrameWindow, ...]:
+    """Create frame windows from explicit frame boundaries.
+
+    Args:
+        boundary_frames: Ordered frame boundaries. Each neighboring pair forms
+            one window.
+        frame_count: Total number of aligned movie frames.
+        labels: Optional label for each output window.
+
+    Returns:
+        Tuple of ``FrameWindow`` objects.
+
+    Raises:
+        ValueError: If boundaries are out of range, not increasing, or too few.
+
+    The caller owns what the boundaries mean: trials, epochs, baseline periods,
+    or any other stimulus-derived interval.
+    """
+    boundaries = tuple(int(frame) for frame in boundary_frames)
+    if len(boundaries) < 2:
+        msg = "At least two frame boundaries are required to make windows"
+        raise ValueError(msg)
+    if any(frame < 0 or frame > frame_count for frame in boundaries):
+        msg = f"Frame boundaries must be within [0, {frame_count}]: {boundaries}"
+        raise ValueError(msg)
+    if any(
+        stop <= start for start, stop in zip(boundaries, boundaries[1:], strict=False)
+    ):
+        msg = f"Frame boundaries must be strictly increasing: {boundaries}"
+        raise ValueError(msg)
+
+    window_count = len(boundaries) - 1
+    resolved_labels = _resolve_window_labels(window_count, labels)
+    return tuple(
+        FrameWindow(
+            index=index,
+            start_frame=boundaries[index],
+            stop_frame=boundaries[index + 1],
+            label=resolved_labels[index],
+        )
+        for index in range(window_count)
+    )
+
+
+def frame_windows_from_photodiode_alignment(
+    alignment: PhotodiodeAlignment,
+    *,
+    frame_count: int,
+    labels: Sequence[str] | None = None,
+) -> tuple[FrameWindow, ...]:
+    """Create frame windows from paired photodiode event frames.
+
+    Args:
+        alignment: Photodiode events paired to imaging frames.
+        frame_count: Total number of aligned movie frames.
+        labels: Optional label for each neighboring event interval.
+
+    Returns:
+        Frame windows between consecutive paired photodiode events.
+
+    This turns decoded photodiode boundaries into frame intervals without
+    assuming what each event means in a stimulus-specific protocol.
+    """
+    return make_frame_windows(
+        tuple(event.imaging_frame for event in alignment.paired_events),
+        frame_count=frame_count,
+        labels=labels,
+    )
+
+
+def map_stimulus_epochs_to_frame_windows(
+    recording: RecordingData,
+    alignment: PhotodiodeAlignment,
+) -> tuple[EpochFrameWindow, ...]:
+    """Map stimulus epoch runs onto photodiode-aligned imaging-frame windows.
+
+    Args:
+        recording: Loaded converted recording with ``stimulus/data`` and epoch
+            parameter metadata.
+        alignment: Photodiode events paired to imaging frames.
+
+    Returns:
+        One ``EpochFrameWindow`` per nonzero stimulus epoch run.
+
+    Raises:
+        ValueError: If the stimulus epoch runs and photodiode windows do not
+            have the same count.
+
+    This wraps the stricter photodiode classifier and returns the older
+    ``EpochFrameWindow`` shape used by response helpers.
+    """
+    timing = classify_recording_photodiode_events(recording, alignment)
+    return tuple(
+        EpochFrameWindow(
+            window=FrameWindow(
+                index=window.index,
+                start_frame=window.start_frame,
+                stop_frame=window.stop_frame,
+                label=_epoch_window_label(window.epoch_number, window.epoch_name),
+            ),
+            epoch_number=window.epoch_number,
+            epoch_name=window.epoch_name,
+        )
+        for window in timing.windows
+    )
+
+
+def select_epoch_frame_windows(
+    epoch_windows: tuple[EpochFrameWindow, ...],
+    *,
+    epoch_name: str | None = None,
+    epoch_number: int | None = None,
+) -> tuple[FrameWindow, ...]:
+    """Select frame windows for one stimulus epoch.
+
+    Args:
+        epoch_windows: Stimulus-labeled frame windows.
+        epoch_name: Optional epoch name to match exactly.
+        epoch_number: Optional epoch number to match exactly.
+
+    Returns:
+        Matching ``FrameWindow`` objects.
+
+    Raises:
+        ValueError: If neither selector is supplied.
+
+    This is the small script-facing helper used for baseline windows such as
+    ``Gray Interleave`` without making dF/F code know stimulus-table details.
+    """
+    if epoch_name is None and epoch_number is None:
+        msg = "Select by epoch_name, epoch_number, or both"
+        raise ValueError(msg)
+
+    return tuple(
+        epoch_window.window
+        for epoch_window in epoch_windows
+        if _matches_epoch_window(
+            epoch_window,
+            epoch_name=epoch_name,
+            epoch_number=epoch_number,
+        )
+    )
+
+
+def split_traces_by_frame_windows(
+    traces: RoiTraces,
+    windows: Sequence[FrameWindow],
+) -> tuple[WindowedRoiResponse, ...]:
+    """Split ROI traces into explicit frame windows.
+
+    Args:
+        traces: ROI traces with known start and stop frame indices.
+        windows: Frame windows to slice.
+
+    Returns:
+        One ``WindowedRoiResponse`` per window.
+
+    Raises:
+        ValueError: If a window falls outside the trace frame range.
+
+    This function only slices; it does not compute response metrics. Keeping
+    those steps separate makes later baseline and trial logic auditable.
+    """
+    responses: list[WindowedRoiResponse] = []
+    for window in windows:
+        _validate_window_inside_traces(window, traces)
+        start = window.start_frame - traces.start_frame
+        stop = window.stop_frame - traces.start_frame
+        responses.append(
+            WindowedRoiResponse(
+                window=window,
+                values=traces.values[start:stop, :],
+                roi_labels=traces.labels,
+            ),
+        )
+
+    return tuple(responses)
+
+
+def _epoch_window_label(epoch_number: int, epoch_name: str) -> str:
+    """Create a readable label for a stimulus epoch frame window.
+
+    Args:
+        epoch_number: One-indexed stimulus epoch number.
+        epoch_name: Human-readable epoch name from converted stimulus metadata.
+
+    Returns:
+        Label suitable for plots and logs.
+    """
+    safe_name = epoch_name.strip().replace(" ", "_") or "unnamed"
+    return f"epoch_{epoch_number:04d}_{safe_name}"
+
+
+def _matches_epoch_window(
+    epoch_window: EpochFrameWindow,
+    *,
+    epoch_name: str | None,
+    epoch_number: int | None,
+) -> bool:
+    """Check whether one epoch window matches optional selectors.
+
+    Args:
+        epoch_window: Candidate stimulus-labeled window.
+        epoch_name: Optional epoch name selector.
+        epoch_number: Optional epoch number selector.
+
+    Returns:
+        ``True`` when all supplied selectors match.
+    """
+    if epoch_name is not None and epoch_window.epoch_name != epoch_name:
+        return False
+    return epoch_number is None or epoch_window.epoch_number == epoch_number
+
+
+def _resolve_window_labels(
+    window_count: int,
+    labels: Sequence[str] | None,
+) -> tuple[str, ...]:
+    """Resolve optional frame-window labels.
+
+    Args:
+        window_count: Number of windows being created.
+        labels: Optional caller labels.
+
+    Returns:
+        One label per window.
+    """
+    if labels is None:
+        return tuple(f"window_{index + 1:04d}" for index in range(window_count))
+    if len(labels) != window_count:
+        msg = f"Expected {window_count} labels; got {len(labels)}"
+        raise ValueError(msg)
+    return tuple(labels)
+
+
+def _validate_window_inside_traces(window: FrameWindow, traces: RoiTraces) -> None:
+    """Confirm one frame window can slice a trace matrix.
+
+    Args:
+        window: Frame window to check.
+        traces: ROI traces with available frame bounds.
+
+    Returns:
+        None.
+    """
+    if window.start_frame < traces.start_frame or window.stop_frame > traces.stop_frame:
+        msg = (
+            f"Window [{window.start_frame}, {window.stop_frame}) is outside "
+            f"trace range [{traces.start_frame}, {traces.stop_frame})"
+        )
+        raise ValueError(msg)