TwoPy 0.1.1__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.1 → twopy-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "twopy"
-version = "0.1.1"
+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.1 → twopy-0.1.3}/src/twopy/__init__.py

@@ -5,6 +5,7 @@ Inputs: none.
 Outputs: package constants and helper functions imported by users and scripts.
 """
 
+from twopy._version import __version__
 from twopy.analysis import (
     DEFAULT_RESPONSE_POST_WINDOW_SECONDS,
     DEFAULT_RESPONSE_PRE_WINDOW_SECONDS,
@@ -174,5 +175,3 @@ __all__ = [
     "write_response_summary_grouped_csv",
     "write_response_summary_trials_csv",
 ]
-
-__version__ = "0.1.0"

twopy-0.1.3/src/twopy/_version.py

@@ -0,0 +1,14 @@
+"""Package-version metadata for twopy.
+
+Inputs: installed Python package metadata.
+Outputs: the current twopy package version string.
+
+Keeping this in one small module prevents the public Python API and command-line
+interface from drifting when ``pyproject.toml`` changes.
+"""
+
+from importlib.metadata import version
+
+__all__ = ["__version__"]
+
+__version__ = version("twopy")

{twopy-0.1.1 → 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.1 → 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.1 → twopy-0.1.3}/src/twopy/napari/launcher.py

@@ -9,8 +9,10 @@ analysis workflows belong in dedicated helpers that the controls call.
 """
 
 from argparse import ArgumentParser, Namespace
+from collections.abc import Sequence
 from pathlib import Path
 
+from twopy._version import __version__
 from twopy.napari.controls import add_twopy_magicgui_controls
 from twopy.napari.layout import place_response_options_after_recording_list
 from twopy.napari.loading import resolve_or_convert_launch_recording
@@ -99,11 +101,12 @@ def launch_napari(
     return view
 
 
-def parse_launch_args() -> Namespace:
+def parse_launch_args(args: Sequence[str] | None = None) -> Namespace:
     """Parse command-line arguments for ``python -m twopy.napari``.
 
     Args:
-        None.
+        args: Optional command-line arguments. ``None`` reads from
+            ``sys.argv``.
 
     Returns:
         Parsed argument namespace.
@@ -111,6 +114,13 @@ def parse_launch_args() -> Namespace:
     parser = ArgumentParser(
         description="Launch napari for a twopy-converted recording.",
     )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"twopy {__version__}",
+        help="Print the current twopy package version and exit.",
+    )
     parser.add_argument(
         "recording_data_path",
         nargs="?",
@@ -152,7 +162,7 @@ def parse_launch_args() -> Namespace:
         action="store_true",
         help="Skip loading movie preview frames and show only the mean image.",
     )
-    return parser.parse_args()
+    return parser.parse_args(args)
 
 
 def main() -> None:

{twopy-0.1.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → twopy-0.1.3}/src/twopy.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 src/twopy/__init__.py
 src/twopy/_segments.py
+src/twopy/_version.py
 src/twopy/api.py
 src/twopy/config.py
 src/twopy/converted.py

{twopy-0.1.1 → twopy-0.1.3}/tests/test_import.py

@@ -5,6 +5,7 @@ Outputs: unittest assertions that confirm basic package metadata is available.
 """
 
 import unittest
+from importlib.metadata import version
 
 import twopy
 
@@ -18,7 +19,7 @@ class ImportTest(unittest.TestCase):
         Inputs: imported twopy module.
         Outputs: a passing assertion when the version matches package metadata.
         """
-        self.assertEqual(twopy.__version__, "0.1.0")
+        self.assertEqual(twopy.__version__, version("twopy"))
 
 
 if __name__ == "__main__":