TwoPy 0.1.0__py3-none-any.whl

twopy/napari/protocols.py

@@ -0,0 +1,90 @@
+"""Tiny napari protocols used by tests and GUI adapter code.
+
+Inputs: napari viewer, window, and layer objects.
+Outputs: structural types for the small subset of napari behavior twopy uses.
+
+These protocols keep the adapter testable without importing or starting napari
+in unit tests.
+"""
+
+from typing import Protocol
+
+
+class NapariWindow(Protocol):
+    """Small protocol for adding dock widgets to a napari viewer.
+
+    Inputs: widget objects.
+    Outputs: dock widgets owned by napari.
+    """
+
+    def add_dock_widget(
+        self,
+        widget: object,
+        *,
+        name: str,
+        area: str,
+    ) -> object:
+        """Add a dock widget to the viewer window.
+
+        Args:
+            widget: Widget object to dock.
+            name: Dock title shown by napari.
+            area: Napari dock area name.
+
+        Returns:
+            The dock widget created by napari.
+        """
+        ...
+
+
+class NapariViewer(Protocol):
+    """Small viewer protocol used to keep tests independent from napari.
+
+    Inputs: image or label layer data.
+    Outputs: napari layer objects.
+    """
+
+    @property
+    def window(self) -> NapariWindow:
+        """Return the viewer window used to add dock widgets.
+
+        Inputs: viewer object.
+        Outputs: napari window object.
+        """
+        ...
+
+    def add_image(self, data: object, *, name: str, **kwargs: object) -> object:
+        """Add an image layer to the viewer.
+
+        Args:
+            data: Array-like image data.
+            name: Layer name shown in napari.
+            kwargs: napari image-layer options.
+
+        Returns:
+            The layer object created by napari.
+        """
+        ...
+
+    def add_labels(self, data: object, *, name: str, **kwargs: object) -> object:
+        """Add a labels layer to the viewer.
+
+        Args:
+            data: Two-dimensional integer label image.
+            name: Layer name shown in napari.
+            kwargs: napari label-layer options.
+
+        Returns:
+            The layer object created by napari.
+        """
+        ...
+
+
+class NapariLayerWithData(Protocol):
+    """Small protocol for napari layers that expose array-like data.
+
+    Inputs: a napari layer object.
+    Outputs: access to its ``data`` attribute.
+    """
+
+    data: object

twopy/napari/responses.py

@@ -0,0 +1,91 @@
+"""Response-computation helpers for the twopy napari adapter.
+
+Inputs: a loaded converted recording and the active napari Labels ROI layer.
+Outputs: plot-ready response data computed from the current labels.
+
+This module is the small boundary between GUI ROI editing and core analysis.
+It translates editable Labels pixels into a ``RoiSet`` and then calls the
+GUI-independent in-memory response workflow.
+"""
+
+from pathlib import Path
+
+import numpy as np
+
+from twopy.analysis.workflow import compute_recording_responses
+from twopy.converted import RecordingData
+from twopy.napari.plotting.data import (
+    ResponsePlotData,
+    response_plot_data_from_grouped,
+)
+from twopy.napari.roi import roi_label_image_from_layer_for_recording
+from twopy.roi import RoiSet, make_roi_set_from_label_image
+
+__all__ = [
+    "compute_response_plot_data_from_labels",
+    "compute_response_plot_data_from_roi_set",
+]
+
+
+def compute_response_plot_data_from_labels(
+    recording: RecordingData,
+    roi_labels_layer: object,
+    *,
+    source_path: Path | None = None,
+) -> ResponsePlotData:
+    """Compute plot-ready ROI responses from the current napari Labels layer.
+
+    Args:
+        recording: Loaded converted recording shown in napari.
+        roi_labels_layer: Active napari Labels layer containing ROI pixels.
+        source_path: Optional display path attached to the plot data.
+
+    Returns:
+        Plot-ready response means and SEMs grouped by stimulus epoch.
+
+    Raises:
+        ValueError: If the layer shape is not the crop-native display shape, if
+            no ROI labels are present, or if analysis inputs are invalid.
+
+    The helper deliberately does not save analysis files. Live ROI editing can
+    call it repeatedly without creating HDF5 churn; explicit save/export actions
+    remain separate user decisions.
+    """
+    label_image = roi_label_image_from_layer_for_recording(roi_labels_layer, recording)
+    if not np.any(label_image > 0):
+        msg = "No ROI labels to analyze."
+        raise ValueError(msg)
+
+    roi_set = make_roi_set_from_label_image(label_image)
+    return compute_response_plot_data_from_roi_set(
+        recording,
+        roi_set,
+        source_path=source_path,
+    )
+
+
+def compute_response_plot_data_from_roi_set(
+    recording: RecordingData,
+    roi_set: RoiSet,
+    *,
+    source_path: Path | None = None,
+) -> ResponsePlotData:
+    """Compute plot-ready ROI responses from a prepared ROI set.
+
+    Args:
+        recording: Loaded converted recording shown in napari.
+        roi_set: ROI masks created from the current Labels layer.
+        source_path: Optional display path attached to the plot data.
+
+    Returns:
+        Plot-ready response means and SEMs grouped by stimulus epoch.
+
+    This helper receives a prepared ROI set so live napari updates can copy
+    label pixels on the GUI thread, then run the heavier movie streaming work in
+    a worker thread.
+    """
+    computation = compute_recording_responses(recording, roi_set)
+    return response_plot_data_from_grouped(
+        computation.grouped_responses,
+        source_path=source_path,
+    )

twopy/napari/roi.py

@@ -0,0 +1,238 @@
+"""ROI helpers for the twopy napari adapter.
+
+Inputs: napari Labels layers, label images, ROI HDF5 files, and converted
+recording metadata.
+Outputs: twopy ``RoiSet`` objects, label images for display, and validated ROI
+save/load paths.
+
+This module is the only napari-facing layer that translates between editable
+Labels data and core ROI masks.
+"""
+
+from pathlib import Path
+from typing import cast
+
+import numpy as np
+import numpy.typing as npt
+
+from twopy.converted import RecordingData
+from twopy.napari.display import (
+    display_image_from_movie_image,
+    display_labels_from_movie_labels,
+    movie_labels_from_display_layer,
+)
+from twopy.napari.protocols import NapariLayerWithData
+from twopy.roi import (
+    RoiSet,
+    load_roi_set,
+    make_roi_set_from_label_image,
+    roi_set_to_label_image,
+    save_roi_set,
+)
+from twopy.spatial import SpatialCrop, full_frame_crop
+
+__all__ = [
+    "roi_label_image_from_layer",
+    "roi_label_image_from_layer_for_recording",
+    "save_napari_label_rois",
+    "validate_roi_layer_matches_recording_crop",
+]
+
+
+def roi_label_image_from_layer(layer: object) -> npt.NDArray[np.int64]:
+    """Read integer label data from a napari Labels layer.
+
+    Args:
+        layer: Napari Labels layer, or a test object with a ``data`` attribute.
+
+    Returns:
+        Full-frame movie-coordinate integer label image.
+
+    This small helper keeps scripts from reaching into napari layer internals
+    in several different ways. The label image can be passed directly to
+    ``save_napari_label_rois``. When twopy opened a cropped/transposed display
+    layer, crop metadata on the layer is used to restore movie coordinates.
+    """
+    if hasattr(layer, "metadata") or hasattr(layer, "options"):
+        return movie_labels_from_display_layer(layer)
+    data = cast(NapariLayerWithData, layer).data
+    return np.asarray(data, dtype=np.int64)
+
+
+def roi_label_image_from_layer_for_recording(
+    layer: object,
+    recording: RecordingData,
+) -> npt.NDArray[np.int64]:
+    """Return full-frame movie-coordinate ROI labels from a crop-native layer.
+
+    Args:
+        layer: Napari Labels layer, or a test layer with ``data``.
+        recording: Loaded converted recording that defines the displayed crop.
+
+    Returns:
+        Full-frame movie-coordinate label image with zeros outside the crop.
+
+    Raises:
+        ValueError: If the Labels layer is not shaped like the recording's
+            displayed alignment-valid crop.
+
+    Napari ROI editing is intentionally crop-native: users see and edit only
+    the pixels that analysis accepts by default. Persisted ROI files stay
+    full-frame so core scripts and analysis have one stable mask shape.
+    """
+    validate_roi_layer_matches_recording_crop(layer, recording)
+    display_labels = np.asarray(cast(NapariLayerWithData, layer).data, dtype=np.int64)
+    crop = recording.alignment_valid_crop
+    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 validate_roi_layer_matches_recording_crop(
+    layer: object,
+    recording: RecordingData,
+) -> None:
+    """Validate that a napari Labels layer matches the displayed recording crop.
+
+    Args:
+        layer: Napari Labels layer, or a test layer with ``data``.
+        recording: Loaded converted recording that defines the displayed crop.
+
+    Returns:
+        None.
+
+    Raises:
+        ValueError: If the Labels layer does not have the cropped display
+            shape.
+    """
+    display_labels = np.asarray(cast(NapariLayerWithData, layer).data)
+    crop = recording.alignment_valid_crop
+    expected_shape = (crop.shape[1], crop.shape[0])
+    if display_labels.shape != expected_shape:
+        msg = (
+            "ROI Labels layer must use the cropped recording view. "
+            f"Expected display shape {expected_shape} from "
+            f"{crop.source}; got {display_labels.shape}."
+        )
+        raise ValueError(msg)
+
+
+def save_napari_label_rois(
+    label_image: npt.ArrayLike,
+    path: Path,
+    *,
+    labels: tuple[str, ...] | None = None,
+    label_prefix: str = "roi",
+) -> RoiSet:
+    """Save a napari labels-layer image as a twopy ROI set.
+
+    Args:
+        label_image: Two-dimensional labels-layer data where ``0`` is
+            background and positive integers are ROIs.
+        path: Destination ROI HDF5 file.
+        labels: Optional text labels matching positive ROI values.
+        label_prefix: Prefix for generated ROI labels when ``labels`` is
+            omitted.
+
+    Returns:
+        Saved ``RoiSet``.
+
+    This keeps napari editing output in the same HDF5 format that scripts and
+    analysis functions already load.
+    """
+    roi_set = make_roi_set_from_label_image(
+        np.asarray(label_image),
+        labels=labels,
+        label_prefix=label_prefix,
+    )
+    save_roi_set(roi_set, path)
+    return roi_set
+
+
+def roi_label_image_for_display(
+    roi_set: RoiSet | Path | None,
+    recording: RecordingData,
+    *,
+    spatial_crop: SpatialCrop | None = None,
+) -> npt.NDArray[np.int64]:
+    """Create the label image shown in napari for ROI drawing/editing.
+
+    Args:
+        roi_set: Optional existing ROI set or saved ROI HDF5 path.
+        recording: Loaded converted recording.
+        spatial_crop: Optional crop shown in napari. When omitted, the full
+            movie frame is displayed.
+
+    Returns:
+        Integer label image in napari display coordinates.
+    """
+    crop = spatial_crop
+    if crop is None:
+        crop = full_frame_crop(recording.movie.shape[1:])
+    if roi_set is None:
+        return np.zeros((crop.shape[1], crop.shape[0]), dtype=np.int64)
+    loaded_roi_set = resolve_roi_set(roi_set)
+    validate_roi_shape(loaded_roi_set, recording)
+    return display_labels_from_movie_labels(
+        roi_set_to_label_image(loaded_roi_set),
+        crop,
+    )
+
+
+def resolve_roi_save_file(
+    *,
+    recording_data_path: Path,
+    roi_set: RoiSet | Path | None,
+    explicit_roi_save_file: Path | None,
+) -> Path:
+    """Resolve the default path used by the magicgui Save ROIs button.
+
+    Args:
+        recording_data_path: Converted recording manifest path.
+        roi_set: Optional ROI object or path opened in napari.
+        explicit_roi_save_file: Optional caller-provided save path.
+
+    Returns:
+        Path for saving ROI HDF5 files.
+    """
+    if explicit_roi_save_file is not None:
+        return explicit_roi_save_file.expanduser()
+    if isinstance(roi_set, Path):
+        return roi_set.expanduser()
+    return recording_data_path.expanduser().parent / "rois.h5"
+
+
+def resolve_roi_set(roi_set: RoiSet | Path) -> RoiSet:
+    """Return a ROI set object from either an object or HDF5 path.
+
+    Args:
+        roi_set: Existing ``RoiSet`` or saved ROI HDF5 path.
+
+    Returns:
+        Loaded ``RoiSet``.
+    """
+    if isinstance(roi_set, Path):
+        return load_roi_set(roi_set)
+    return roi_set
+
+
+def validate_roi_shape(roi_set: RoiSet, recording: RecordingData) -> None:
+    """Validate that ROI labels can be displayed over the recording.
+
+    Args:
+        roi_set: ROI masks to display.
+        recording: Loaded converted recording.
+
+    Returns:
+        None.
+    """
+    if roi_set.masks.shape[1:] != recording.movie.shape[1:]:
+        msg = (
+            f"ROI mask shape {roi_set.masks.shape[1:]} does not match movie "
+            f"shape {recording.movie.shape[1:]}"
+        )
+        raise ValueError(msg)