TwoPy 0.1.0__py3-none-any.whl

twopy/napari/display.py

@@ -0,0 +1,181 @@
+"""Display-coordinate helpers for the twopy napari adapter.
+
+Inputs: movie-coordinate images, label images, and spatial crops.
+Outputs: napari-display arrays and full-frame movie-coordinate ROI labels.
+
+twopy stores converted movie data as ``(frame, axis0, axis1)`` because those are
+the HDF5 array axes. napari displays two-dimensional images as
+``(row, column)``. These helpers keep that transpose explicit so ROI pixels
+drawn in napari can be converted back to analysis coordinates without guessing.
+"""
+
+from typing import Any, Protocol, cast
+
+import numpy as np
+import numpy.typing as npt
+
+from twopy.spatial import SpatialCrop
+from twopy.typing_guards import (
+    int_or_none,
+    int_tuple_or_none,
+    string_key_mapping_or_none,
+)
+
+DISPLAY_CROP_METADATA_KEY = "twopy_display_spatial_crop"
+
+__all__ = [
+    "display_image_from_movie_image",
+    "display_labels_from_movie_labels",
+    "display_metadata_for_spatial_crop",
+    "movie_labels_from_display_layer",
+]
+
+
+class _LayerWithData(Protocol):
+    """Small protocol for napari-like layers with array data."""
+
+    data: object
+
+
+class _LayerWithMetadata(Protocol):
+    """Small protocol for napari-like layers with metadata."""
+
+    metadata: object
+
+
+class _LayerWithOptions(Protocol):
+    """Small protocol for fake test layers that store napari kwargs."""
+
+    options: dict[str, object]
+
+
+def display_image_from_movie_image(
+    image: npt.NDArray[Any],
+) -> npt.NDArray[Any]:
+    """Convert a movie-coordinate image or movie block for napari display.
+
+    Args:
+        image: Two-dimensional ``(axis0, axis1)`` image or three-dimensional
+            ``(frame, axis0, axis1)`` movie block.
+
+    Returns:
+        View with the two spatial axes swapped for napari display.
+    """
+    values = np.asarray(image)
+    if values.ndim not in (2, 3):
+        msg = f"Expected a 2-D image or 3-D movie block; got {values.shape}"
+        raise ValueError(msg)
+    return np.swapaxes(values, -1, -2)
+
+
+def display_labels_from_movie_labels(
+    label_image: npt.NDArray[np.int64],
+    spatial_crop: SpatialCrop,
+) -> npt.NDArray[np.int64]:
+    """Convert full-frame movie-coordinate labels into napari display labels.
+
+    Args:
+        label_image: Full-frame integer labels in movie coordinates.
+        spatial_crop: Spatial crop displayed in napari.
+
+    Returns:
+        Display-coordinate label image for the crop.
+
+    The viewer shows the same alignment-valid crop used by default response
+    analysis. Cropping here prevents users from drawing ROIs in pixels that the
+    default analysis path will reject later.
+    """
+    cropped_labels = spatial_crop.crop_image(label_image)
+    return display_image_from_movie_image(cropped_labels)
+
+
+def movie_labels_from_display_layer(layer: object) -> npt.NDArray[np.int64]:
+    """Read napari display labels and return full-frame movie labels.
+
+    Args:
+        layer: napari Labels layer, or a test object with ``data`` and optional
+            crop metadata.
+
+    Returns:
+        Full-frame integer label image in movie coordinates.
+    """
+    display_labels = np.asarray(cast(_LayerWithData, layer).data, dtype=np.int64)
+    crop = _spatial_crop_from_layer_metadata(layer)
+    if crop is None:
+        return cast(npt.NDArray[np.int64], display_labels)
+
+    movie_crop_labels = display_image_from_movie_image(display_labels)
+    full_frame = np.zeros(crop.original_shape, dtype=np.int64)
+    full_frame[
+        crop.axis0_start : crop.axis0_stop,
+        crop.axis1_start : crop.axis1_stop,
+    ] = movie_crop_labels
+    return full_frame
+
+
+def display_metadata_for_spatial_crop(spatial_crop: SpatialCrop) -> dict[str, object]:
+    """Return napari layer metadata that records the displayed movie crop.
+
+    Args:
+        spatial_crop: Crop shown in napari display coordinates.
+
+    Returns:
+        Plain dictionary that can be stored in ``layer.metadata``.
+    """
+    return {
+        DISPLAY_CROP_METADATA_KEY: {
+            "axis0_start": spatial_crop.axis0_start,
+            "axis0_stop": spatial_crop.axis0_stop,
+            "axis1_start": spatial_crop.axis1_start,
+            "axis1_stop": spatial_crop.axis1_stop,
+            "original_shape": spatial_crop.original_shape,
+            "source": spatial_crop.source,
+        },
+    }
+
+
+def _spatial_crop_from_layer_metadata(layer: object) -> SpatialCrop | None:
+    """Return the crop recorded on a napari layer, if present.
+
+    Args:
+        layer: napari layer or test layer.
+
+    Returns:
+        ``SpatialCrop`` or ``None`` when the layer has no twopy crop metadata.
+    """
+    metadata = (
+        cast(_LayerWithMetadata, layer).metadata if hasattr(layer, "metadata") else None
+    )
+    if metadata is None and hasattr(layer, "options"):
+        metadata = cast(_LayerWithOptions, layer).options.get("metadata")
+    metadata_dict = string_key_mapping_or_none(metadata)
+    if metadata_dict is None:
+        return None
+    crop_data = metadata_dict.get(DISPLAY_CROP_METADATA_KEY)
+    crop_dict = string_key_mapping_or_none(crop_data)
+    if crop_dict is None:
+        return None
+    raw_shape = int_tuple_or_none(crop_dict.get("original_shape"), length=2)
+    if raw_shape is None:
+        return None
+    axis0_start = int_or_none(crop_dict.get("axis0_start"))
+    axis0_stop = int_or_none(crop_dict.get("axis0_stop"))
+    axis1_start = int_or_none(crop_dict.get("axis1_start"))
+    axis1_stop = int_or_none(crop_dict.get("axis1_stop"))
+    source = crop_dict.get("source")
+    if (
+        axis0_start is None
+        or axis0_stop is None
+        or axis1_start is None
+        or axis1_stop is None
+        or not isinstance(source, str)
+    ):
+        return None
+    return SpatialCrop(
+        axis0_start=axis0_start,
+        axis0_stop=axis0_stop,
+        axis1_start=axis1_start,
+        axis1_stop=axis1_stop,
+        original_shape=(raw_shape[0], raw_shape[1]),
+        source=source,
+    )

twopy/napari/display_paths.py

@@ -0,0 +1,197 @@
+"""Human-readable recording and output path labels for napari.
+
+Inputs: loaded converted recordings and output paths.
+Outputs: short strings for GUI labels and status messages.
+
+Full recording paths are too long for the napari sidebars. These helpers keep
+path presentation in one place while file-reading and file-writing code keeps
+using full ``Path`` objects.
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from twopy.config import DEFAULT_CONFIG_PATH, load_config
+from twopy.converted import RecordingData
+
+__all__ = [
+    "RecordingDisplaySummary",
+    "format_output_folder",
+    "format_twopy_h5_output",
+    "recording_display_summary",
+]
+
+_YEAR_PATTERN = re.compile(r"^\d{4}$")
+_DATE_PATTERN = re.compile(r"^\d{2}_\d{2}$")
+_TIME_PATTERN = re.compile(r"^\d{2}_\d{2}_\d{2}$")
+
+
+@dataclass(frozen=True)
+class RecordingDisplaySummary:
+    """Short recording identity shown in the response Update tab.
+
+    Inputs: one converted recording path.
+    Outputs: root data path, genotype folder, stimulus folder, and recording
+    time.
+    """
+
+    root: Path
+    genotype: str
+    stimulus: str
+    recording: str
+
+    def lines(self) -> tuple[str, str, str, str]:
+        """Return display lines for a compact Qt label.
+
+        Args:
+            None.
+
+        Returns:
+            Four user-facing lines.
+        """
+        return (
+            f"Root: {self.root}",
+            f"Genotype: {self.genotype}",
+            f"Stimulus: {self.stimulus}",
+            f"Recording: {self.recording}",
+        )
+
+
+def recording_display_summary(recording: RecordingData) -> RecordingDisplaySummary:
+    """Parse one recording into stable, readable identity fields.
+
+    Args:
+        recording: Loaded converted recording.
+
+    Returns:
+        Root/genotype/recording-time summary.
+
+    ``config.yml`` gives the cleanest root and genotype split when present.
+    The fallback still reads the final ``YYYY/MM_DD/HH_MM_SS`` path contract so
+    napari remains usable from copied example folders.
+    """
+    recording_dir = recording.source_session_dir.expanduser()
+    date_index = _recording_date_index(recording_dir)
+    recording_label = _recording_label(recording_dir, date_index)
+
+    try:
+        data_root = load_config(DEFAULT_CONFIG_PATH).data_path.expanduser()
+        relative = recording_dir.relative_to(data_root)
+    except (FileNotFoundError, ValueError):
+        data_root, genotype, stimulus = _fallback_path_parts(recording_dir, date_index)
+    else:
+        genotype = relative.parts[0] if len(relative.parts) > 0 else "unknown"
+        stimulus = relative.parts[1] if len(relative.parts) > 1 else "unknown"
+
+    return RecordingDisplaySummary(
+        root=data_root,
+        genotype=genotype,
+        stimulus=stimulus,
+        recording=recording_label,
+    )
+
+
+def format_twopy_h5_output(path: Path) -> str:
+    """Return the compact display form for twopy HDF5 outputs.
+
+    Args:
+        path: Full output path.
+
+    Returns:
+        ``./twopy/<filename>.h5`` style string.
+    """
+    return f"./twopy/{path.name}"
+
+
+def format_output_folder(path: Path, recording: RecordingData | None) -> str:
+    """Return a compact output-folder label for status messages.
+
+    Args:
+        path: File or folder path that was written.
+        recording: Optional selected recording used to compute a twopy-relative
+            folder.
+
+    Returns:
+        Short folder string such as ``./twopy`` or
+        ``./twopy/exports/recording_view``.
+    """
+    folder = path if path.suffix == "" else path.parent
+    if recording is None:
+        return str(folder)
+
+    twopy_dir = recording.path.parent
+    try:
+        relative = folder.relative_to(twopy_dir)
+    except ValueError:
+        return "./twopy"
+
+    if str(relative) == ".":
+        return "./twopy"
+    return f"./twopy/{relative}"
+
+
+def _recording_date_index(recording_dir: Path) -> int | None:
+    """Return the index of the ``YYYY/MM_DD/HH_MM_SS`` path segment.
+
+    Args:
+        recording_dir: Source recording folder.
+
+    Returns:
+        Index of the year segment, or ``None`` when the path is not recognized.
+    """
+    parts = recording_dir.parts
+    for index in range(len(parts) - 2):
+        if (
+            _YEAR_PATTERN.match(parts[index]) is not None
+            and _DATE_PATTERN.match(parts[index + 1]) is not None
+            and _TIME_PATTERN.match(parts[index + 2]) is not None
+        ):
+            return index
+    return None
+
+
+def _recording_label(recording_dir: Path, date_index: int | None) -> str:
+    """Return the recording date label from the source recording path.
+
+    Args:
+        recording_dir: Source recording folder.
+        date_index: Index of the year segment, if found.
+
+    Returns:
+        ``YYYY-MM-DD HH:MM:SS`` or the folder name as a fallback.
+    """
+    if date_index is None:
+        return recording_dir.name
+
+    parts = recording_dir.parts
+    year = parts[date_index]
+    month_day = parts[date_index + 1].replace("_", "-")
+    time = parts[date_index + 2].replace("_", ":")
+    return f"{year}-{month_day} {time}"
+
+
+def _fallback_path_parts(
+    recording_dir: Path,
+    date_index: int | None,
+) -> tuple[Path, str, str]:
+    """Infer root, genotype, and stimulus when config is unavailable.
+
+    Args:
+        recording_dir: Source recording folder.
+        date_index: Index of the year segment, if found.
+
+    Returns:
+        ``(root, genotype, stimulus)`` best effort.
+
+    Stable lab recording paths end as
+    ``<genotype>/<stimulus>/<YYYY>/<MM_DD>/<HH_MM_SS>``. The fallback keeps that
+    contract explicit instead of guessing from folder names.
+    """
+    if date_index is None or date_index < 2:
+        return recording_dir.parent, recording_dir.name, "unknown"
+
+    parts = recording_dir.parts
+    genotype_index = date_index - 2
+    stimulus_index = date_index - 1
+    return Path(*parts[:genotype_index]), parts[genotype_index], parts[stimulus_index]

twopy/napari/interactive.py

@@ -0,0 +1,310 @@
+"""Live response updates for napari ROI editing.
+
+Inputs: the selected converted recording, its editable Labels layer, and the
+response plot widget.
+Outputs: debounced plot refreshes as ROI pixels change.
+
+The controller owns GUI orchestration only. It copies Labels pixels on the GUI
+thread, then runs the heavier response calculation through the same in-memory
+analysis helper used by the manual update button.
+"""
+
+from collections.abc import Callable
+from concurrent.futures import Future, ThreadPoolExecutor
+from contextlib import suppress
+from dataclasses import dataclass
+from typing import Protocol, cast
+
+import numpy as np
+from qtpy.QtCore import QTimer
+
+from twopy.converted import RecordingData
+from twopy.napari.plotting.data import ResponsePlotData
+from twopy.napari.responses import compute_response_plot_data_from_roi_set
+from twopy.napari.roi import roi_label_image_from_layer_for_recording
+from twopy.roi import make_roi_set_from_label_image
+
+__all__ = ["LiveResponseController"]
+
+
+class ResponsePlotReceiver(Protocol):
+    """Small protocol for the plot widget methods used by live updates."""
+
+    def set_response_plot_data(
+        self,
+        plot_data: ResponsePlotData,
+        *,
+        reset_axes: bool,
+    ) -> None:
+        """Show newly computed plot data.
+
+        Args:
+            plot_data: Plot-ready response data.
+            reset_axes: Whether plot bounds should return to data-derived
+                defaults.
+
+        Returns:
+            None.
+        """
+        ...
+
+    def show_response_status(self, text: str) -> None:
+        """Show a user-facing response status message.
+
+        Args:
+            text: Status text.
+
+        Returns:
+            None.
+        """
+        ...
+
+
+class _EventEmitter(Protocol):
+    """Small protocol for psygnal event emitters exposed by napari layers."""
+
+    def connect(self, callback: Callable[..., None]) -> object:
+        """Connect one callback to the event emitter."""
+        ...
+
+    def disconnect(self, callback: Callable[..., None]) -> object:
+        """Disconnect one callback from the event emitter."""
+        ...
+
+
+@dataclass(frozen=True)
+class _ConnectedEmitter:
+    """One napari Labels event connection owned by the controller."""
+
+    emitter: _EventEmitter
+
+
+class LiveResponseController:
+    """Debounced response updater for one active napari Labels layer.
+
+    Inputs: a plot widget plus the selected recording/layer context.
+    Outputs: live response plot refreshes after ROI edits.
+
+    The controller keeps only one worker job active. If ROI pixels change while
+    a job is running, the running result is discarded when stale and one newer
+    job is scheduled. This keeps the UI responsive without building a complex
+    queue that would compute obsolete ROIs.
+    """
+
+    def __init__(
+        self,
+        plot_widget: ResponsePlotReceiver,
+        *,
+        debounce_ms: int = 400,
+        run_async: bool = True,
+    ) -> None:
+        """Create a live updater for one response plot widget.
+
+        Args:
+            plot_widget: Widget that receives plot data or status messages.
+            debounce_ms: Delay after the latest ROI edit before recomputing.
+            run_async: Whether heavy analysis should run in a worker thread.
+                Tests can turn this off to verify behavior synchronously.
+        """
+        self._plot_widget = plot_widget
+        self._recording: RecordingData | None = None
+        self._roi_labels_layer: object | None = None
+        self._connections: list[_ConnectedEmitter] = []
+        self._version = 0
+        self._active_version: int | None = None
+        self._pending_after_active_job = False
+        self._future: Future[ResponsePlotData] | None = None
+        self._executor = (
+            ThreadPoolExecutor(max_workers=1, thread_name_prefix="twopy-roi-live")
+            if run_async
+            else None
+        )
+        self._debounce_timer = QTimer()
+        self._debounce_timer.setSingleShot(True)
+        self._debounce_timer.timeout.connect(self._start_latest_job)
+        self._poll_timer = QTimer()
+        self._poll_timer.setInterval(75)
+        self._poll_timer.timeout.connect(self._collect_finished_job)
+        self._debounce_ms = debounce_ms
+
+    def set_context(
+        self,
+        recording: RecordingData | None,
+        roi_labels_layer: object | None,
+    ) -> None:
+        """Set the recording and Labels layer watched by live updates.
+
+        Args:
+            recording: Selected converted recording, or ``None``.
+            roi_labels_layer: Editable Labels layer for that recording, or
+                ``None``.
+
+        Returns:
+            None.
+        """
+        self._disconnect_layer_events()
+        self._recording = recording
+        self._roi_labels_layer = roi_labels_layer
+        self._version += 1
+        self._pending_after_active_job = False
+        self._connect_layer_events(roi_labels_layer)
+
+    def request_update(self, *_event_args: object) -> None:
+        """Schedule a live response update after an ROI edit.
+
+        Args:
+            _event_args: Optional napari event arguments. They are ignored
+                because the Labels layer itself is the source of truth.
+
+        Returns:
+            None.
+        """
+        self._version += 1
+        if self._debounce_ms <= 0:
+            self._start_latest_job()
+            return
+        self._debounce_timer.start(self._debounce_ms)
+
+    def update_now(self) -> None:
+        """Compute responses immediately on the GUI thread.
+
+        Args:
+            None.
+
+        Returns:
+            None.
+
+        The manual update button uses this synchronous path because a direct
+        button click should report validation errors immediately. Continuous ROI
+        edits use ``request_update`` so heavier work can run in the background.
+        """
+        self._version += 1
+        version = self._version
+        try:
+            plot_data = self._compute_current_plot_data()
+        except ValueError as error:
+            if version == self._version:
+                self._plot_widget.show_response_status(str(error))
+            return
+        if version == self._version:
+            self._plot_widget.set_response_plot_data(plot_data, reset_axes=True)
+
+    def shutdown(self) -> None:
+        """Disconnect layer events and stop background work.
+
+        Args:
+            None.
+
+        Returns:
+            None.
+        """
+        self._disconnect_layer_events()
+        self._debounce_timer.stop()
+        self._poll_timer.stop()
+        if self._executor is not None:
+            self._executor.shutdown(wait=False, cancel_futures=True)
+
+    def _start_latest_job(self) -> None:
+        """Start the newest queued response computation."""
+        if self._executor is None:
+            self.update_now()
+            return
+        if self._future is not None:
+            self._pending_after_active_job = True
+            return
+
+        version = self._version
+        try:
+            label_image = self._current_label_image()
+        except ValueError as error:
+            if version == self._version:
+                self._plot_widget.show_response_status(str(error))
+            return
+        if not np.any(label_image > 0):
+            if version == self._version:
+                self._plot_widget.show_response_status("No ROI labels to analyze.")
+            return
+
+        recording = self._require_recording()
+        roi_set = make_roi_set_from_label_image(label_image)
+        self._active_version = version
+        self._future = self._executor.submit(
+            compute_response_plot_data_from_roi_set,
+            recording,
+            roi_set,
+            source_path=None,
+        )
+        self._poll_timer.start()
+
+    def _collect_finished_job(self) -> None:
+        """Apply a finished worker result when it is still current."""
+        future = self._future
+        if future is None or not future.done():
+            return
+
+        version = self._active_version
+        self._future = None
+        self._active_version = None
+        self._poll_timer.stop()
+        try:
+            plot_data = future.result()
+        except ValueError as error:
+            if version == self._version:
+                self._plot_widget.show_response_status(str(error))
+        else:
+            if version == self._version:
+                self._plot_widget.set_response_plot_data(plot_data, reset_axes=True)
+
+        if self._pending_after_active_job or version != self._version:
+            self._pending_after_active_job = False
+            self._start_latest_job()
+
+    def _compute_current_plot_data(self) -> ResponsePlotData:
+        """Return plot data for the current recording and Labels layer."""
+        label_image = self._current_label_image()
+        if not np.any(label_image > 0):
+            msg = "No ROI labels to analyze."
+            raise ValueError(msg)
+        return compute_response_plot_data_from_roi_set(
+            self._require_recording(),
+            make_roi_set_from_label_image(label_image),
+            source_path=None,
+        )
+
+    def _current_label_image(self) -> np.ndarray:
+        """Return full-frame ROI labels from the current Labels layer."""
+        recording = self._require_recording()
+        layer = self._roi_labels_layer
+        if layer is None:
+            msg = "No ROI Labels layer is available."
+            raise ValueError(msg)
+        return roi_label_image_from_layer_for_recording(layer, recording)
+
+    def _require_recording(self) -> RecordingData:
+        """Return the selected recording or raise a user-facing error."""
+        if self._recording is None:
+            msg = "No recording loaded."
+            raise ValueError(msg)
+        return self._recording
+
+    def _connect_layer_events(self, layer: object | None) -> None:
+        """Connect Labels data-change events to debounced updates."""
+        if layer is None:
+            return
+        events = getattr(layer, "events", None)
+        if events is None:
+            return
+        for event_name in ("paint", "data"):
+            emitter = getattr(events, event_name, None)
+            if emitter is None:
+                continue
+            connected = cast(_EventEmitter, emitter)
+            connected.connect(self.request_update)
+            self._connections.append(_ConnectedEmitter(connected))
+
+    def _disconnect_layer_events(self) -> None:
+        """Disconnect all Labels event handlers owned by the controller."""
+        for connection in self._connections:
+            with suppress(RuntimeError, ValueError):
+                connection.emitter.disconnect(self.request_update)
+        self._connections.clear()