TwoPy 0.1.2__tar.gz → 0.1.3__tar.gz

twopy-0.1.3/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: twopy
+Version: 0.1.3
+Summary: Two-photon imaging analysis tool with a napari interface.
+Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
+License-Expression: MIT
+Requires-Python: <3.14,>=3.13
+Description-Content-Type: text/markdown
+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: pre-commit<5,>=4.6
+Requires-Dist: qtpy<3,>=2.4
+Requires-Dist: pyyaml<7,>=6.0.3
+Requires-Dist: ruff>=0.15
+Requires-Dist: scipy<2,>=1.17
+Requires-Dist: tifffile<2027,>=2026.3
+Requires-Dist: ty<0.1,>=0.0.34
+
+# twopy
+
+Two-photon imaging analysis tool for the Clark Lab output format.
+
+![twopy napari interface](https://raw.githubusercontent.com/gumadeiras/twopy/main/docs/assets/twopy-napari.png)
+
+## Getting Started
+
+twopy lets you open two-photon recordings, draw ROIs, plot responses in real time,
+process and analyze them, and save them.
+
+When you first load a recording, twopy converts it to a standardized HDF5 format.
+The converted format includes the aligned movie, mean image, stimulus tables,
+photodiode signals, and  recording metadata. Analysis and the GUI both work from
+the converted files, so the original source files remain separate from twopy's outputs.
+
+## Install
+
+Examples use micromamba, but any conda-compatible environment manager should work.
+
+
+```sh
+micromamba create -n twopy -c conda-forge python=3.13 pip -y
+micromamba run -n twopy python -m pip install twopy
+```
+
+Verify the install:
+
+```sh
+micromamba run -n twopy python -c 'import twopy; print(twopy.__name__)'
+```
+
+For a source checkout, copy `config.example.yml` to `config.yml` and edit the
+paths for your computer. `config.yml` stays local and is not tracked by git.
+
+## Start
+
+```sh
+micromamba activate twopy
+twopy
+```
+
+Open a source recording or converted recording directly:
+
+```sh
+twopy /path/to/source/recording
+twopy /path/to/recording_data.h5
+```
+
+Basic GUI flow:
+
+1. Choose a recording.
+2. Draw or edit ROIs in the `rois` Labels layer.
+3. Click Save ROIs.
+4. Update response plots from the current ROIs.
+5. Save analysis outputs.
+
+When a source recording has not been converted yet, twopy converts it first.
+Converted data includes the aligned movie, mean image, stimulus tables,
+photodiode signals, and recording metadata.
+
+## Docs
+
+- [GUI guide](docs/gui.md): napari loading, ROI editing, plotting, and saved
+  outputs.
+- [Python API guide](docs/python_api.md): find recordings, convert data, run
+  analysis, and open napari from scripts.
+- [Development guide](docs/development.md): source setup and local checks.
+- [Input data spec](docs/input_data_spec.md): short recording folder contract.
+- [Recording file reference](docs/recording_file_schema.md): detailed source
+  and converted file schema.
+
+## Check
+
+```sh
+micromamba run -n twopy pre-commit run --all-files
+```

twopy-0.1.3/README.md

@@ -0,0 +1,77 @@
+# twopy
+
+Two-photon imaging analysis tool for the Clark Lab output format.
+
+![twopy napari interface](https://raw.githubusercontent.com/gumadeiras/twopy/main/docs/assets/twopy-napari.png)
+
+## Getting Started
+
+twopy lets you open two-photon recordings, draw ROIs, plot responses in real time,
+process and analyze them, and save them.
+
+When you first load a recording, twopy converts it to a standardized HDF5 format.
+The converted format includes the aligned movie, mean image, stimulus tables,
+photodiode signals, and  recording metadata. Analysis and the GUI both work from
+the converted files, so the original source files remain separate from twopy's outputs.
+
+## Install
+
+Examples use micromamba, but any conda-compatible environment manager should work.
+
+
+```sh
+micromamba create -n twopy -c conda-forge python=3.13 pip -y
+micromamba run -n twopy python -m pip install twopy
+```
+
+Verify the install:
+
+```sh
+micromamba run -n twopy python -c 'import twopy; print(twopy.__name__)'
+```
+
+For a source checkout, copy `config.example.yml` to `config.yml` and edit the
+paths for your computer. `config.yml` stays local and is not tracked by git.
+
+## Start
+
+```sh
+micromamba activate twopy
+twopy
+```
+
+Open a source recording or converted recording directly:
+
+```sh
+twopy /path/to/source/recording
+twopy /path/to/recording_data.h5
+```
+
+Basic GUI flow:
+
+1. Choose a recording.
+2. Draw or edit ROIs in the `rois` Labels layer.
+3. Click Save ROIs.
+4. Update response plots from the current ROIs.
+5. Save analysis outputs.
+
+When a source recording has not been converted yet, twopy converts it first.
+Converted data includes the aligned movie, mean image, stimulus tables,
+photodiode signals, and recording metadata.
+
+## Docs
+
+- [GUI guide](docs/gui.md): napari loading, ROI editing, plotting, and saved
+  outputs.
+- [Python API guide](docs/python_api.md): find recordings, convert data, run
+  analysis, and open napari from scripts.
+- [Development guide](docs/development.md): source setup and local checks.
+- [Input data spec](docs/input_data_spec.md): short recording folder contract.
+- [Recording file reference](docs/recording_file_schema.md): detailed source
+  and converted file schema.
+
+## Check
+
+```sh
+micromamba run -n twopy pre-commit run --all-files
+```

{twopy-0.1.2 → twopy-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "twopy"
-version = "0.1.2"
+version = "0.1.3"
 description = "Two-photon imaging analysis tool with a napari interface."
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{twopy-0.1.2 → twopy-0.1.3}/src/twopy/database/cache.py

@@ -11,9 +11,9 @@ import hashlib
 import json
 import shutil
 from pathlib import Path
-from typing import cast
 
 from twopy.database.types import DatabaseAccess
+from twopy.typing_guards import string_key_mapping_or_none
 
 __all__ = [
     "DEFAULT_DATABASE_CACHE_DIR",
@@ -107,10 +107,7 @@ def _read_copy_manifest(manifest_path: Path) -> dict[str, object] | None:
     except (OSError, json.JSONDecodeError):
         return None
 
-    if not isinstance(loaded, dict):
-        return None
-
-    return cast(dict[str, object], loaded)
+    return string_key_mapping_or_none(loaded)
 
 
 def _manifest_metadata_matches(

{twopy-0.1.2 → twopy-0.1.3}/src/twopy/napari/controls.py

@@ -272,9 +272,14 @@ def _make_twopy_load_widget(state: NapariControlState) -> object:
             )
             movie_range = None
             if load_movie:
+                start_frame, end_frame = _widget_movie_frame_range_for_load(
+                    movie_frame_range,
+                    frame_count=loaded_recording.movie.shape[0],
+                    preserve_current_range=replace_selected,
+                )
                 movie_range = resolve_movie_frame_range(
-                    start_frame=int(movie_frame_range[0]),
-                    end_frame=int(movie_frame_range[1]),
+                    start_frame=start_frame,
+                    end_frame=end_frame,
                     frame_count=loaded_recording.movie.shape[0],
                     zero_end_means_last=True,
                 )
@@ -717,6 +722,42 @@ def _default_movie_end_frame(recording: RecordingData | None) -> int:
     return max(recording.movie.shape[0] - 1, 0)
 
 
+def _widget_movie_frame_range_for_load(
+    movie_frame_range: tuple[int, int],
+    *,
+    frame_count: int,
+    preserve_current_range: bool,
+) -> tuple[int, int]:
+    """Choose a GUI movie preview range for the recording being loaded.
+
+    Args:
+        movie_frame_range: Current range-slider value.
+        frame_count: Number of movie frames in the recording being loaded.
+        preserve_current_range: Whether this is a reload of the selected
+            recording after an option change.
+
+    Returns:
+        Inclusive preview range constrained to the recording length. New
+        recordings default to their full movie, while reloads preserve the
+        visible slider value where possible.
+
+    The frame-range widget keeps its previous value until after a recording
+    loads. That value is meaningful when reloading the same recording after an
+    option change, but stale when choosing a different recording.
+    """
+    last_frame = max(frame_count - 1, 0)
+    if not preserve_current_range:
+        return (0, last_frame)
+
+    start_frame = int(movie_frame_range[0])
+    end_frame = int(movie_frame_range[1])
+    if start_frame > last_frame:
+        start_frame = last_frame
+    if end_frame > last_frame:
+        end_frame = last_frame
+    return (start_frame, end_frame)
+
+
 def _load_recording_for_defaults(
     *,
     recording_data_path: Path,

{twopy-0.1.2 → twopy-0.1.3}/src/twopy/napari/loading.py

@@ -193,6 +193,7 @@ def _first_source_recording_dir(candidates: tuple[Path | None, ...]) -> Path | N
         Resolved source folder, or ``None``.
     """
     seen: set[Path] = set()
+    validation_error: FileNotFoundError | ValueError | None = None
     for candidate in candidates:
         if candidate is None:
             continue
@@ -202,6 +203,57 @@ def _first_source_recording_dir(candidates: tuple[Path | None, ...]) -> Path | N
         seen.add(expanded)
         try:
             return discover_session_files(expanded).session_dir.resolve()
-        except (FileNotFoundError, ValueError):
+        except (FileNotFoundError, ValueError) as error:
+            if validation_error is None and _looks_like_source_recording_dir(expanded):
+                validation_error = error
             continue
+    if validation_error is not None:
+        raise validation_error
     return None
+
+
+def _looks_like_source_recording_dir(path: Path) -> bool:
+    """Return whether a folder appears to be microscope source output.
+
+    Args:
+        path: Candidate folder.
+
+    Returns:
+        ``True`` when the folder contains stable source-recording markers.
+
+    Discovery errors from source-like folders should reach the user. Errors
+    from arbitrary folders should stay quiet so twopy can continue checking
+    other candidates such as a parent source folder.
+    """
+    if not path.is_dir():
+        return False
+    fixed_markers = (
+        "stimulusData",
+        "alignedMovie.mat",
+        "defaultAlignChannel.txt",
+        "highResPd.mat",
+        "imageDescription.mat",
+        "imagingResPd.mat",
+    )
+    if any((path / marker).exists() for marker in fixed_markers):
+        return True
+    return any(_source_candidate_files(path, "*.tif")) or any(
+        _source_candidate_files(path, "*_alignment.txt")
+    )
+
+
+def _source_candidate_files(path: Path, pattern: str) -> tuple[Path, ...]:
+    """Return source files matching a flexible microscope filename pattern.
+
+    Args:
+        path: Candidate source folder.
+        pattern: Glob pattern.
+
+    Returns:
+        Matching files excluding macOS AppleDouble sidecars.
+    """
+    return tuple(
+        candidate
+        for candidate in path.glob(pattern)
+        if candidate.is_file() and not candidate.name.startswith("._")
+    )

{twopy-0.1.2 → twopy-0.1.3}/src/twopy/napari/plotting/label_visibility.py

@@ -9,10 +9,12 @@ image, so hiding an ROI in the plot options cannot delete ROI data.
 """
 
 from collections.abc import Mapping
-from typing import Any, Protocol, cast
+from typing import Protocol, cast
 
 from qtpy.QtGui import QColor
 
+from twopy.typing_guards import int_or_none, string_key_mapping_or_none
+
 __all__ = [
     "apply_roi_visibility_to_labels_layer",
     "roi_label_value_from_label",
@@ -241,13 +243,11 @@ def _base_label_colormap_params(
     color cycle while users toggle ROI visibility.
     """
     stored = layer.metadata.get(_BASE_LABEL_COLORMAP_METADATA_KEY)
-    if isinstance(stored, dict):
-        stored_params = cast(dict[str, object], stored)
-        return {
-            "num_colors": int(cast(Any, stored_params["num_colors"])),
-            "seed": float(cast(Any, stored_params["seed"])),
-            "background_value": int(cast(Any, stored_params["background_value"])),
-        }
+    stored_params = string_key_mapping_or_none(stored)
+    if stored_params is not None:
+        params = _parsed_label_colormap_params(stored_params)
+        if params is not None:
+            return params
 
     colormap = cast(_LabelColormapLike, layer.colormap)
     colors = getattr(colormap, "colors", ())
@@ -258,3 +258,29 @@ def _base_label_colormap_params(
     }
     layer.metadata[_BASE_LABEL_COLORMAP_METADATA_KEY] = params
     return params
+
+
+def _parsed_label_colormap_params(
+    params: dict[str, object],
+) -> dict[str, int | float] | None:
+    """Return persisted label-colormap parameters when all fields parse."""
+    num_colors = int_or_none(params.get("num_colors"))
+    seed = _float_or_none(params.get("seed"))
+    background_value = int_or_none(params.get("background_value"))
+    if num_colors is None or seed is None or background_value is None:
+        return None
+    return {
+        "num_colors": num_colors,
+        "seed": seed,
+        "background_value": background_value,
+    }
+
+
+def _float_or_none(value: object) -> float | None:
+    """Return a float for simple numeric metadata values."""
+    if isinstance(value, bool) or not isinstance(value, int | float | str):
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None

{twopy-0.1.2 → twopy-0.1.3}/src/twopy/napari/viewer.py

@@ -32,7 +32,9 @@ from twopy.napari.types import NapariRecordingView
 from twopy.roi import RoiSet
 from twopy.spatial import SpatialCrop
 
-__all__ = ["open_recording_in_napari"]
+APPLICATION_TITLE = "twopy"
+
+__all__ = ["APPLICATION_TITLE", "create_viewer", "open_recording_in_napari"]
 
 
 class _LabelsLayerWithBrushSize(Protocol):
@@ -229,7 +231,7 @@ def create_viewer() -> NapariViewer:
     """
     import napari
 
-    return cast(NapariViewer, napari.Viewer())
+    return cast(NapariViewer, napari.Viewer(title=APPLICATION_TITLE))
 
 
 def set_labels_brush_size(layer: object, *, brush_size: int) -> None:

{twopy-0.1.2 → twopy-0.1.3}/src/twopy/session.py

@@ -154,7 +154,11 @@ def _find_one_file(session_dir: Path, pattern: str, label: str) -> Path:
     The raw movie and alignment text include stimulus/run details in their
     names. A strict one-match check avoids guessing when the folder is messy.
     """
-    matches = sorted(path for path in session_dir.glob(pattern) if path.is_file())
+    matches = sorted(
+        path
+        for path in session_dir.glob(pattern)
+        if path.is_file() and not path.name.startswith("._")
+    )
 
     if len(matches) != 1:
         joined = ", ".join(str(path) for path in matches) if matches else "none"

{twopy-0.1.2 → twopy-0.1.3}/src/twopy/stimulus.py

@@ -10,9 +10,9 @@ per-``stimtype`` mapping explicit for scripts and analysis code.
 """
 
 from dataclasses import dataclass
-from typing import cast
 
 from twopy.converted import RecordingData
+from twopy.typing_guards import require_string_key_mapping
 
 __all__ = [
     "StimulusSpecificColumnMapping",
@@ -176,10 +176,14 @@ def _mappings_from_metadata(
 
     mappings: list[StimulusSpecificColumnMapping] = []
     for column in columns:
-        if not isinstance(column, dict):
+        try:
+            column_metadata = require_string_key_mapping(
+                column,
+                name=f"stimulus metadata for stimtype {stimtype!r} column",
+            )
+        except ValueError as error:
             msg = f"stimulus metadata for stimtype {stimtype!r} is malformed"
-            raise ValueError(msg)
-        column_metadata = cast(dict[str, object], column)
+            raise ValueError(msg) from error
         if column_metadata.get("column_name") != stable_column_name:
             continue
 

twopy-0.1.3/src/twopy.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: twopy
+Version: 0.1.3
+Summary: Two-photon imaging analysis tool with a napari interface.
+Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
+License-Expression: MIT
+Requires-Python: <3.14,>=3.13
+Description-Content-Type: text/markdown
+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: pre-commit<5,>=4.6
+Requires-Dist: qtpy<3,>=2.4
+Requires-Dist: pyyaml<7,>=6.0.3
+Requires-Dist: ruff>=0.15
+Requires-Dist: scipy<2,>=1.17
+Requires-Dist: tifffile<2027,>=2026.3
+Requires-Dist: ty<0.1,>=0.0.34
+
+# twopy
+
+Two-photon imaging analysis tool for the Clark Lab output format.
+
+![twopy napari interface](https://raw.githubusercontent.com/gumadeiras/twopy/main/docs/assets/twopy-napari.png)
+
+## Getting Started
+
+twopy lets you open two-photon recordings, draw ROIs, plot responses in real time,
+process and analyze them, and save them.
+
+When you first load a recording, twopy converts it to a standardized HDF5 format.
+The converted format includes the aligned movie, mean image, stimulus tables,
+photodiode signals, and  recording metadata. Analysis and the GUI both work from
+the converted files, so the original source files remain separate from twopy's outputs.
+
+## Install
+
+Examples use micromamba, but any conda-compatible environment manager should work.
+
+
+```sh
+micromamba create -n twopy -c conda-forge python=3.13 pip -y
+micromamba run -n twopy python -m pip install twopy
+```
+
+Verify the install:
+
+```sh
+micromamba run -n twopy python -c 'import twopy; print(twopy.__name__)'
+```
+
+For a source checkout, copy `config.example.yml` to `config.yml` and edit the
+paths for your computer. `config.yml` stays local and is not tracked by git.
+
+## Start
+
+```sh
+micromamba activate twopy
+twopy
+```
+
+Open a source recording or converted recording directly:
+
+```sh
+twopy /path/to/source/recording
+twopy /path/to/recording_data.h5
+```
+
+Basic GUI flow:
+
+1. Choose a recording.
+2. Draw or edit ROIs in the `rois` Labels layer.
+3. Click Save ROIs.
+4. Update response plots from the current ROIs.
+5. Save analysis outputs.
+
+When a source recording has not been converted yet, twopy converts it first.
+Converted data includes the aligned movie, mean image, stimulus tables,
+photodiode signals, and recording metadata.
+
+## Docs
+
+- [GUI guide](docs/gui.md): napari loading, ROI editing, plotting, and saved
+  outputs.
+- [Python API guide](docs/python_api.md): find recordings, convert data, run
+  analysis, and open napari from scripts.
+- [Development guide](docs/development.md): source setup and local checks.
+- [Input data spec](docs/input_data_spec.md): short recording folder contract.
+- [Recording file reference](docs/recording_file_schema.md): detailed source
+  and converted file schema.
+
+## Check
+
+```sh
+micromamba run -n twopy pre-commit run --all-files
+```

{twopy-0.1.2 → twopy-0.1.3}/tests/test_napari.py

@@ -90,7 +90,11 @@ from twopy.napari.plotting.widgets import (
 )
 from twopy.napari.state import write_last_recording_folder
 from twopy.napari.text import counted_noun
-from twopy.napari.viewer import interior_random_frame_indices
+from twopy.napari.viewer import (
+    APPLICATION_TITLE,
+    create_viewer,
+    interior_random_frame_indices,
+)
 from twopy.spatial import SpatialCrop
 
 
@@ -400,6 +404,20 @@ class NapariAdapterTest(unittest.TestCase):
             environ["TWOPY_NAPARI_STATE_FILE"] = self._previous_state_file
         self._state_temp_dir.cleanup()
 
+    def test_create_viewer_uses_twopy_window_title(self) -> None:
+        """Confirm the launcher brands the top-level napari window.
+
+        Inputs: patched napari Viewer constructor.
+        Outputs: viewer construction receives the twopy application title.
+        """
+        viewer = _FakeViewer()
+
+        with patch("napari.Viewer", return_value=viewer) as viewer_constructor:
+            created = create_viewer()
+
+        self.assertIs(created, viewer)
+        viewer_constructor.assert_called_once_with(title=APPLICATION_TITLE)
+
     def test_opens_empty_roi_labels_layer_by_default(self) -> None:
         """Confirm new recordings open with an editable empty ROI layer.
 
@@ -1311,6 +1329,42 @@ class NapariAdapterTest(unittest.TestCase):
             self.assertEqual(load_widget.movie_frame_range.value, (0, 1))
             self.assertEqual(len(viewer.images), 2)
 
+    def test_loading_shorter_recording_clamps_stale_movie_range(self) -> None:
+        """Confirm old movie slider values do not block a shorter recording.
+
+        Inputs: two converted recordings where the first movie is longer.
+        Outputs: the second recording loads and the slider fits its frame count.
+        """
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            first = root / "first"
+            second = root / "second"
+            first.mkdir()
+            second.mkdir()
+            _write_converted_recording(
+                first,
+                movie_values=np.arange(20, dtype=np.float64).reshape(5, 2, 2),
+            )
+            _write_converted_recording(
+                second,
+                movie_values=np.arange(12, dtype=np.float64).reshape(3, 2, 2),
+            )
+            viewer = _FakeViewer()
+            control_docks = add_twopy_magicgui_controls(
+                viewer,
+                roi_labels_layer=None,
+                roi_save_file=Path("unused.h5"),
+            )
+            controls = cast(_ControlWidget, control_docks.load_widget)
+            load_widget = cast(Any, controls[1])
+
+            load_widget(recording_folder=first)
+            load_widget.movie_frame_range.value = (3, 4)
+            load_widget(recording_folder=second)
+
+            self.assertEqual(load_widget.movie_frame_range.value, (0, 2))
+            self.assertEqual(len(viewer.images), 4)
+
     def test_recording_path_resolution_reports_available_files(self) -> None:
         """Confirm folder resolution finds optional movie and ROI paths.
 
@@ -1380,6 +1434,20 @@ class NapariAdapterTest(unittest.TestCase):
                 (source_dir / "twopy" / "aligned_movie.h5").resolve(),
             )
 
+    def test_source_recording_validation_error_is_reported(self) -> None:
+        """Confirm malformed source folders do not look like missing HDF5.
+
+        Inputs: source-shaped recording folder with two real TIFF movies.
+        Outputs: the source discovery error reaches the caller.
+        """
+        with tempfile.TemporaryDirectory() as temp_dir:
+            source_dir = Path(temp_dir)
+            _write_source_recording_shape(source_dir)
+            (source_dir / "second_movie.tif").touch()
+
+            with self.assertRaisesRegex(ValueError, "raw TIFF movie"):
+                resolve_or_convert_recording(source_dir)
+
     def test_recording_path_resolution_repairs_missing_converted_movie(self) -> None:
         """Confirm incomplete source-local twopy output is regenerated in place.
 
@@ -1593,6 +1661,24 @@ class NapariAdapterTest(unittest.TestCase):
         self.assertEqual(layer.get_color(1)[3], 1.0)
         self.assertAlmostEqual(layer.get_color(2)[3], 0.2)
 
+    def test_roi_visibility_ignores_malformed_colormap_metadata(self) -> None:
+        """Confirm malformed persisted label-colormap metadata is rebuilt.
+
+        Inputs: Labels layer with incomplete twopy colormap metadata.
+        Outputs: visibility still applies instead of raising from metadata access.
+        """
+        layer = Labels(np.array([[1]], dtype=np.int64))
+        layer.metadata["twopy_base_label_colormap"] = {"num_colors": "invalid"}
+
+        apply_roi_visibility_to_labels_layer(
+            layer,
+            roi_labels=("roi_1",),
+            visibility={"roi_1": False},
+            colors=(QColor("#ff0000"),),
+        )
+
+        self.assertAlmostEqual(layer.get_color(1)[3], 0.2)
+
     def test_display_helpers_transpose_movie_axes_for_napari(self) -> None:
         """Confirm movie axes are transposed only at the napari boundary.