TwoPy 0.3.2__tar.gz → 0.3.3__tar.gz

{twopy-0.3.2 → twopy-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twopy
-Version: 0.3.2
+Version: 0.3.3
 Summary: Two-photon imaging analysis tool with a napari interface.
 Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
 License-Expression: MIT
@@ -12,6 +12,7 @@ Requires-Dist: h5py<4,>=3.16
 Requires-Dist: matplotlib<4,>=3.10
 Requires-Dist: napari[all]<0.8,>=0.7
 Requires-Dist: numpy<3,>=2.3
+Requires-Dist: packaging<27,>=26
 Requires-Dist: pre-commit<5,>=4.6
 Requires-Dist: qtpy<3,>=2.4
 Requires-Dist: pyyaml<7,>=6.0.3

{twopy-0.3.2 → twopy-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "twopy"
-version = "0.3.2"
+version = "0.3.3"
 description = "Two-photon imaging analysis tool with a napari interface."
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -17,6 +17,7 @@ dependencies = [
   "matplotlib>=3.10,<4",
   "napari[all]>=0.7,<0.8",
   "numpy>=2.3,<3",
+  "packaging>=26,<27",
   "pre-commit>=4.6,<5",
   "qtpy>=2.4,<3",
   "pyyaml>=6.0.3,<7",
@@ -37,7 +38,7 @@ Repository = "https://github.com/gumadeiras/twopy"
 where = ["src"]
 
 [tool.setuptools.package-data]
-twopy = ["calibrations/*.csv", "config.example.yml"]
+twopy = ["calibrations/*.csv", "config.example.yml", "napari/assets/*.png"]
 
 [tool.ruff]
 line-length = 88

{twopy-0.3.2 → twopy-0.3.3}/src/twopy/analysis/group_matching.py

@@ -143,7 +143,7 @@ def make_manual_fov_group_rows(
 
 
 def make_manual_roi_match_rows(
-    recording_rois: Mapping[Path, str],
+    recording_rois: Sequence[tuple[Path, str]],
     *,
     group_cell_id: int,
     fov_group_id: str = "",
@@ -153,7 +153,9 @@ def make_manual_roi_match_rows(
     """Create validated match-table rows for one user decision.
 
     Args:
-        recording_rois: Mapping from recording path to ROI label.
+        recording_rois: Recording path and ROI label pairs selected for one
+            group. A recording can appear more than once when multiple ROIs
+            from that recording belong in the group.
         group_cell_id: Positive cell-group identifier for this decision.
         fov_group_id: Optional user-facing FOV group identifier.
         status: Decision status for every emitted row.
@@ -172,16 +174,27 @@ def make_manual_roi_match_rows(
         raise ValueError(msg)
 
     rows: list[ManualRoiMatchRow] = []
+    seen: set[tuple[Path, str]] = set()
     for recording_path, roi_label in sorted(
-        recording_rois.items(),
-        key=lambda item: str(item[0]),
+        recording_rois,
+        key=lambda item: (str(item[0]), item[1]),
     ):
+        validated_path = _validate_recording_path(recording_path)
+        validated_roi = _validate_roi_label(roi_label)
+        key = (validated_path, validated_roi)
+        if key in seen:
+            msg = (
+                "Manual ROI match rows cannot repeat the same recording and "
+                f"ROI label: {validated_path} {validated_roi}."
+            )
+            raise ValueError(msg)
+        seen.add(key)
         rows.append(
             ManualRoiMatchRow(
                 fov_group_id=fov_group_id,
                 group_cell_id=group_cell_id,
-                recording_path=_validate_recording_path(recording_path),
-                roi_label=_validate_roi_label(roi_label),
+                recording_path=validated_path,
+                roi_label=validated_roi,
                 status=status,
                 note=note,
             ),
@@ -225,7 +238,7 @@ def matched_manual_roi_groups(
 
 def add_manual_roi_match_group(
     rows: Sequence[ManualRoiMatchRow],
-    recording_rois: Mapping[Path, str],
+    recording_rois: Sequence[tuple[Path, str]],
     *,
     fov_group_id: str,
     note: str = "",
@@ -234,7 +247,7 @@ def add_manual_roi_match_group(
 
     Args:
         rows: Existing manual ROI match rows.
-        recording_rois: Mapping from recording path to selected ROI label.
+        recording_rois: Selected recording path and ROI label pairs.
         fov_group_id: FOV id for the new matched group.
         note: Optional note copied to every new row.
 
@@ -255,7 +268,7 @@ def add_manual_roi_match_group(
 
 def replace_manual_roi_match_group(
     rows: Sequence[ManualRoiMatchRow],
-    recording_rois: Mapping[Path, str],
+    recording_rois: Sequence[tuple[Path, str]],
     *,
     fov_group_id: str,
     group_cell_id: int,
@@ -265,7 +278,7 @@ def replace_manual_roi_match_group(
 
     Args:
         rows: Existing manual ROI match rows.
-        recording_rois: Replacement recording-to-ROI selections.
+        recording_rois: Replacement recording path and ROI label pairs.
         fov_group_id: FOV id containing the group.
         group_cell_id: Existing group id to replace.
         note: Optional note copied to every replacement row.

twopy-0.3.3/src/twopy/napari/empty_state.py

@@ -0,0 +1,159 @@
+"""Empty-viewer message helpers for the twopy napari adapter.
+
+Inputs: napari viewer objects that may expose welcome and text overlays.
+Outputs: a twopy-owned message while no recording is loaded.
+
+The center viewer belongs to napari, but twopy owns the empty recording
+workflow. These helpers hide napari's generic welcome overlay and use napari's
+public text overlay for the small twopy-specific launch message.
+"""
+
+from typing import Protocol, cast
+
+from twopy._version import __version__
+
+__all__ = [
+    "EMPTY_VIEWER_MESSAGE",
+    "hide_empty_viewer_message",
+    "refresh_empty_viewer_message",
+    "show_empty_viewer_message",
+]
+
+_BASE_EMPTY_VIEWER_MESSAGE = (
+    f"twopy {__version__}\n\n"
+    "Getting Started\n\n"
+    "Search or load recordings manually\n"
+    "using the Load tab on the right."
+)
+EMPTY_VIEWER_MESSAGE = _BASE_EMPTY_VIEWER_MESSAGE
+
+
+class _WelcomeScreen(Protocol):
+    """Small shape of napari's welcome overlay."""
+
+    visible: bool
+
+
+class _ViewerWithWelcomeScreen(Protocol):
+    """Small viewer shape for napari welcome-screen updates."""
+
+    welcome_screen: object
+
+
+class _ViewerWithTextOverlay(Protocol):
+    """Small viewer shape for napari text overlay updates."""
+
+    text_overlay: object
+
+
+class _TextOverlay(Protocol):
+    """Small shape of napari's canvas text overlay."""
+
+    text: str
+    visible: bool
+    position: str
+    font_size: int
+    color: object
+    box: bool
+    box_color: object
+
+
+def show_empty_viewer_message(
+    viewer: object, *, update_command: str | None = None
+) -> None:
+    """Show twopy's empty-recording message on a napari viewer.
+
+    Args:
+        viewer: Napari viewer or test double.
+        update_command: Optional pip command shown when a newer twopy release is
+            known.
+
+    Returns:
+        None.
+
+    This replaces napari's generic welcome screen only while twopy has no
+    loaded recording. The message tells the user what the empty canvas means in
+    the twopy workflow.
+    """
+    welcome_screen = _welcome_screen(viewer)
+    if welcome_screen is not None:
+        welcome_screen.visible = False
+
+    overlay = _text_overlay(viewer)
+    if overlay is None:
+        return
+    overlay.text = empty_viewer_message(update_command=update_command)
+    overlay.visible = True
+    overlay.position = "top_center"
+    overlay.font_size = 13
+    overlay.color = "white"
+    overlay.box = True
+    overlay.box_color = (0.0, 0.0, 0.0, 0.65)
+
+
+def hide_empty_viewer_message(viewer: object) -> None:
+    """Hide twopy's empty-recording message when real content owns the viewer.
+
+    Args:
+        viewer: Napari viewer or test double.
+
+    Returns:
+        None.
+
+    The helper clears only the exact twopy empty message. Trial HUD text and any
+    other overlay owner are left untouched.
+    """
+    overlay = _text_overlay(viewer)
+    if overlay is None or not _is_empty_viewer_message(overlay.text):
+        return
+    overlay.text = ""
+    overlay.visible = False
+
+
+def refresh_empty_viewer_message(
+    viewer: object,
+    *,
+    update_command: str | None,
+) -> None:
+    """Update twopy's empty-recording message when it already owns the overlay.
+
+    Args:
+        viewer: Napari viewer or test double.
+        update_command: Optional pip command shown when a newer twopy release is
+            known.
+
+    Returns:
+        None.
+    """
+    overlay = _text_overlay(viewer)
+    if overlay is None or not _is_empty_viewer_message(overlay.text):
+        return
+    overlay.text = empty_viewer_message(update_command=update_command)
+
+
+def empty_viewer_message(*, update_command: str | None = None) -> str:
+    """Return the empty-viewer text for the current update state."""
+    if not update_command:
+        return _BASE_EMPTY_VIEWER_MESSAGE
+    return f"{_BASE_EMPTY_VIEWER_MESSAGE}\n\nUpdate\n{update_command}"
+
+
+def _is_empty_viewer_message(text: str) -> bool:
+    """Return whether text is owned by twopy's empty-recording overlay."""
+    return text == EMPTY_VIEWER_MESSAGE or text.startswith(
+        f"{EMPTY_VIEWER_MESSAGE}\n\nUpdate\n"
+    )
+
+
+def _welcome_screen(viewer: object) -> _WelcomeScreen | None:
+    """Return napari's welcome screen overlay when the viewer exposes one."""
+    if not hasattr(viewer, "welcome_screen"):
+        return None
+    return cast(_WelcomeScreen, cast(_ViewerWithWelcomeScreen, viewer).welcome_screen)
+
+
+def _text_overlay(viewer: object) -> _TextOverlay | None:
+    """Return napari's text overlay when the viewer exposes one."""
+    if not hasattr(viewer, "text_overlay"):
+        return None
+    return cast(_TextOverlay, cast(_ViewerWithTextOverlay, viewer).text_overlay)

{twopy-0.3.2 → twopy-0.3.3}/src/twopy/napari/group_matching/images.py

@@ -50,16 +50,16 @@ def mean_image_roi_overlay_pixmap(
     *,
     mean_image_layer: object,
     roi_labels_layer: object | None,
-    roi_label: str | None,
+    roi_labels: tuple[str, ...],
     selected_color: QColor,
     contrast_percentile: float,
 ) -> QPixmap | None:
-    """Return a mean-image preview with one selected ROI highlighted.
+    """Return a mean-image preview with selected ROIs highlighted.
 
     Args:
         mean_image_layer: Napari mean-image layer.
         roi_labels_layer: Napari Labels layer for the same displayed crop.
-        roi_label: ``roi_####`` label to highlight, or ``None`` for no overlay.
+        roi_labels: ``roi_####`` labels to highlight.
         selected_color: Color used for the selected ROI mask and matching trace.
         contrast_percentile: Upper percentile used as the white point.
 
@@ -72,7 +72,11 @@ def mean_image_roi_overlay_pixmap(
     if image is None:
         return None
     rgba = _grayscale_rgba(image, contrast_percentile=contrast_percentile)
-    label_value = _roi_label_value(roi_label)
+    label_values = tuple(
+        label_value
+        for label_value in (_roi_label_value(roi_label) for roi_label in roi_labels)
+        if label_value is not None
+    )
     labels = _layer_image(roi_labels_layer)
     roi_centers: tuple[tuple[int, float, float], ...] = ()
     if labels is not None and labels.shape == image.shape:
@@ -81,7 +85,7 @@ def mean_image_roi_overlay_pixmap(
         _blend_roi_masks(
             rgba,
             integer_labels,
-            selected_label=label_value,
+            selected_labels=label_values,
             selected_color=selected_color,
         )
     pixmap = _rgba_pixmap(rgba, size=ROI_PREVIEW_SIZE)
@@ -89,7 +93,7 @@ def mean_image_roi_overlay_pixmap(
         pixmap,
         roi_centers=roi_centers,
         image_shape=image.shape,
-        selected_label=label_value,
+        selected_labels=label_values,
     )
     return pixmap
 
@@ -166,14 +170,15 @@ def _blend_roi_masks(
     rgba: np.ndarray,
     labels: np.ndarray,
     *,
-    selected_label: int | None,
+    selected_labels: tuple[int, ...],
     selected_color: QColor,
 ) -> None:
     """Blend all ROI masks into the preview, emphasizing the selected mask."""
+    selected = set(selected_labels)
     roi_values = tuple(
         int(value)
         for value in np.unique(labels)
-        if int(value) > 0 and int(value) != selected_label
+        if int(value) > 0 and int(value) not in selected
     )
     for roi_value in roi_values:
         _blend_mask_color(
@@ -182,7 +187,7 @@ def _blend_roi_masks(
             color=(31, 180, 190),
             alpha=0.28,
         )
-    if selected_label is not None:
+    for selected_label in selected_labels:
         selected_mask = labels == selected_label
         rgba[selected_mask, 0] = selected_color.red()
         rgba[selected_mask, 1] = selected_color.green()
@@ -228,7 +233,7 @@ def _draw_roi_numbers(
     *,
     roi_centers: tuple[tuple[int, float, float], ...],
     image_shape: tuple[int, ...],
-    selected_label: int | None,
+    selected_labels: tuple[int, ...],
 ) -> None:
     """Draw ROI numbers at scaled ROI centroids on top of a preview pixmap."""
     if len(roi_centers) == 0 or len(image_shape) < 2:
@@ -244,13 +249,14 @@ def _draw_roi_numbers(
         painter.setFont(font)
         x_scale = pixmap.width() / width
         y_scale = pixmap.height() / height
+        selected = set(selected_labels)
         for label_value, x_center, y_center in roi_centers:
             text = str(label_value)
             x = int(round(x_center * x_scale))
             y = int(round(y_center * y_scale))
             foreground = (
                 QColor(255, 246, 230)
-                if label_value == selected_label
+                if label_value in selected
                 else QColor(215, 255, 255)
             )
             painter.setPen(QColor(0, 0, 0))

{twopy-0.3.2 → twopy-0.3.3}/src/twopy/napari/group_matching/response_preview.py

@@ -36,7 +36,10 @@ from twopy.napari.roi import roi_label_image_from_layer_for_recording
 from twopy.napari.session import LoadedNapariRecording
 from twopy.napari.text import counted_noun
 
+SelectedRoiKey = tuple[Path, str]
+
 __all__ = [
+    "SelectedRoiKey",
     "SelectedRoiResponse",
     "add_response_legend",
     "combined_response_plot_data",
@@ -58,6 +61,11 @@ class SelectedRoiResponse:
     plot_data: ResponsePlotData
     color: QColor
 
+    @property
+    def key(self) -> SelectedRoiKey:
+        """Return the visibility key for this selected ROI trace."""
+        return (self.recording_path, self.roi_label)
+
 
 def selected_roi_response_plot_data(
     recording: LoadedNapariRecording,
@@ -184,11 +192,11 @@ def selected_response_visibility_status(
     """Return the Selected ROIs summary for the current trace visibility."""
     if visible_count == total_count:
         if total_count == 1:
-            return "Showing the selected recording trace."
-        selected_traces = counted_noun(total_count, "selected recording trace")
+            return "Showing the selected ROI trace."
+        selected_traces = counted_noun(total_count, "selected ROI trace")
         return f"Showing all {selected_traces}."
-    total_traces = counted_noun(total_count, "selected recording trace")
-    hidden_traces = counted_noun(total_count - visible_count, "recording trace")
+    total_traces = counted_noun(total_count, "selected ROI trace")
+    hidden_traces = counted_noun(total_count - visible_count, "ROI trace")
     return f"Showing {visible_count} of {total_traces}; {hidden_traces} hidden."
 
 
@@ -261,18 +269,18 @@ def add_response_legend(
     layout: QGridLayout,
     selected_responses: tuple[SelectedRoiResponse, ...],
     *,
-    hidden_recordings: set[Path],
-    set_visible: Callable[[Path, bool], None],
+    hidden_responses: set[SelectedRoiKey],
+    set_visible: Callable[[SelectedRoiKey, bool], None],
     max_width: int,
 ) -> None:
-    """Add clickable color toggles for overlaid recording traces."""
+    """Add clickable color toggles for overlaid selected-ROI traces."""
     row_index = 0
     row_width = 0
     spacing = max(0, layout.spacing())
     available_width = max(120, max_width)
     row_layout = _new_response_legend_row(layout, row_index, spacing)
     for response in selected_responses:
-        visible = response.recording_path not in hidden_recordings
+        visible = response.key not in hidden_responses
         recording_label = format_recording_minute_label(response.recording_path)
         button = QPushButton(
             f"{recording_label} - ROI {roi_label_display_id(response.roi_label)}",
@@ -281,7 +289,7 @@ def add_response_legend(
         button.setChecked(visible)
         button.setStyleSheet(trace_button_style(response.color, visible=visible))
         button.clicked.connect(
-            lambda checked, path=response.recording_path: set_visible(path, checked),
+            lambda checked, key=response.key: set_visible(key, checked),
         )
         button_width = button.sizeHint().width()
         button.setSizePolicy(QSizePolicy.Policy.Fixed, QSizePolicy.Policy.Fixed)