TwoPy 0.1.7__tar.gz → 0.1.8__tar.gz

{twopy-0.1.7 → twopy-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twopy
-Version: 0.1.7
+Version: 0.1.8
 Summary: Two-photon imaging analysis tool with a napari interface.
 Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
 License-Expression: MIT
@@ -64,10 +64,10 @@ twopy /path/to/recording_data.h5
 
 Basic GUI flow:
 
-1. Choose a recording.
+1. Search the database or load a recording manually.
 2. Draw or edit ROIs in the `rois` Labels layer.
 3. Update response plots from the current ROIs.
-4. Click Save ROIs + analysis when the plots look right.
+4. Click Save ROIs + analysis in Export when the plots look right.
 
 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.
 

{twopy-0.1.7 → twopy-0.1.8}/README.md

@@ -44,10 +44,10 @@ twopy /path/to/recording_data.h5
 
 Basic GUI flow:
 
-1. Choose a recording.
+1. Search the database or load a recording manually.
 2. Draw or edit ROIs in the `rois` Labels layer.
 3. Update response plots from the current ROIs.
-4. Click Save ROIs + analysis when the plots look right.
+4. Click Save ROIs + analysis in Export when the plots look right.
 
 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.
 

{twopy-0.1.7 → twopy-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "twopy"
-version = "0.1.7"
+version = "0.1.8"
 description = "Two-photon imaging analysis tool with a napari interface."
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -32,6 +32,9 @@ twopy = "twopy.napari:main"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+twopy = ["calibrations/*.csv"]
+
 [tool.ruff]
 line-length = 88
 src = ["src", "tests"]

{twopy-0.1.7 → twopy-0.1.8}/src/twopy/__init__.py

@@ -14,6 +14,7 @@ from twopy.analysis import (
     BackgroundCorrectedRoiTraces,
     BackgroundCorrectionMethod,
     CorrelationFilterOptions,
+    DeltaFOverFBaselineMode,
     DeltaFOverFFitMode,
     DeltaFOverFOptions,
     EpochFrameWindow,
@@ -35,6 +36,7 @@ from twopy.analysis import (
     compute_recording_responses,
     compute_roi_delta_f_over_f,
     default_baseline_epoch_number,
+    default_recording_baseline_epoch_number,
     extract_background_corrected_roi_traces,
     frame_windows_from_photodiode_alignment,
     group_delta_f_over_f_by_epoch,
@@ -43,6 +45,7 @@ from twopy.analysis import (
     load_analysis_outputs,
     make_frame_windows,
     map_stimulus_epochs_to_frame_windows,
+    no_baseline_epoch_frame_windows,
     resolve_baseline_frame_windows,
     save_analysis_outputs,
     select_baseline_frame_windows,
@@ -73,6 +76,33 @@ from twopy.photodiode_classification import (
     PhotodiodeEventType,
     classify_recording_photodiode_events,
 )
+from twopy.pixel_calibration import (
+    DEFAULT_PIXEL_CALIBRATION_PATH,
+    PixelCalibrationResolution,
+    PixelCalibrationResolutionMethod,
+    PixelCalibrationRow,
+    load_pixel_calibrations,
+    resolve_pixel_size_um,
+)
+from twopy.pixel_calibration_profiles import (
+    DEFAULT_PIXEL_CALIBRATION_PROFILE_PATH,
+    PixelCalibrationGroup,
+    PixelCalibrationProfile,
+    PixelCalibrationProfileMapping,
+    PixelCalibrationProfileSource,
+    load_pixel_calibration_profile_mappings,
+    resolve_pixel_calibration_profile,
+    select_pixel_calibration_group,
+)
+from twopy.response_roi_extraction import (
+    ResponseNormalization,
+    ResponsePolarity,
+    ResponseStatistic,
+    ResponseWatershedExtraction,
+    ResponseWatershedScoreImages,
+    extract_response_watershed_rois,
+    response_watershed_roi_set,
+)
 from twopy.roi import (
     RoiSet,
     RoiTraces,
@@ -83,6 +113,15 @@ from twopy.roi import (
     roi_set_to_label_image,
     save_roi_set,
 )
+from twopy.roi_extraction import (
+    RoiExtractionConfig,
+    RoiExtractionMethod,
+    extract_rois_from_image,
+    grid_roi_set,
+    grid_roi_set_microns,
+    grid_size_pixels_from_microns,
+    watershed_roi_set,
+)
 from twopy.spatial import SpatialCrop, SpatialDomain, full_frame_crop
 from twopy.stimulus import (
     StimulusSpecificColumnMapping,
@@ -119,13 +158,19 @@ __all__ = [
     "convert_recording_to_twopy",
     "DEFAULT_RESPONSE_POST_WINDOW_SECONDS",
     "DEFAULT_RESPONSE_PRE_WINDOW_SECONDS",
+    "DEFAULT_PIXEL_CALIBRATION_PATH",
+    "DEFAULT_PIXEL_CALIBRATION_PROFILE_PATH",
     "default_baseline_epoch_number",
+    "default_recording_baseline_epoch_number",
     "detect_photodiode_events",
     "detect_recording_photodiode_events",
+    "DeltaFOverFBaselineMode",
     "DeltaFOverFFitMode",
     "DeltaFOverFOptions",
     "EpochFrameWindow",
     "extract_background_corrected_roi_traces",
+    "extract_response_watershed_rois",
+    "extract_rois_from_image",
     "extract_roi_traces",
     "find_recordings",
     "frame_windows_from_photodiode_alignment",
@@ -134,12 +179,17 @@ __all__ = [
     "group_delta_f_over_f_by_epoch",
     "GroupedRoiResponseSummary",
     "GroupedRoiResponses",
+    "grid_roi_set",
+    "grid_roi_set_microns",
+    "grid_size_pixels_from_microns",
     "InterpolatedEpochMapping",
     "interpolate_stimulus_epochs_to_frame_windows",
     "is_baseline_epoch_name",
     "launch_napari",
     "load_analysis_outputs",
     "load_converted_recording",
+    "load_pixel_calibrations",
+    "load_pixel_calibration_profile_mappings",
     "load_roi_set",
     "load_source_conversion_inputs",
     "LoadedAnalysisOutputs",
@@ -148,6 +198,7 @@ __all__ = [
     "make_frame_windows",
     "make_roi_set",
     "map_stimulus_epochs_to_frame_windows",
+    "no_baseline_epoch_frame_windows",
     "map_stimulus_specific_column",
     "NapariRecordingView",
     "NapariSidebarWidgets",
@@ -158,9 +209,26 @@ __all__ = [
     "PhotodiodeEvent",
     "PhotodiodeEventType",
     "PhotodiodeEventSet",
+    "PixelCalibrationResolution",
+    "PixelCalibrationResolutionMethod",
+    "PixelCalibrationGroup",
+    "PixelCalibrationProfile",
+    "PixelCalibrationProfileMapping",
+    "PixelCalibrationProfileSource",
+    "PixelCalibrationRow",
+    "ResponseNormalization",
+    "ResponsePolarity",
     "ResponseProcessingOptions",
+    "ResponseStatistic",
+    "ResponseWatershedExtraction",
+    "ResponseWatershedScoreImages",
     "recording_frame_rate_hz",
+    "resolve_pixel_size_um",
+    "resolve_pixel_calibration_profile",
     "resolve_baseline_frame_windows",
+    "response_watershed_roi_set",
+    "RoiExtractionConfig",
+    "RoiExtractionMethod",
     "RoiDeltaFOverF",
     "RoiCorrelationScores",
     "RoiResponseSummary",
@@ -173,6 +241,7 @@ __all__ = [
     "save_napari_label_rois",
     "save_roi_set",
     "select_baseline_frame_windows",
+    "select_pixel_calibration_group",
     "split_traces_by_frame_windows",
     "SmoothingOptions",
     "SpatialCrop",
@@ -182,6 +251,7 @@ __all__ = [
     "summarize_epoch_roi_responses",
     "summarize_grouped_responses",
     "validate_grouped_roi_responses",
+    "watershed_roi_set",
     "WindowedRoiResponse",
     "write_response_summary_grouped_csv",
     "write_response_summary_trials_csv",

{twopy-0.1.7 → twopy-0.1.8}/src/twopy/analysis/__init__.py

@@ -18,7 +18,7 @@ from twopy.analysis.dff import (
     RoiDeltaFOverF,
     compute_roi_delta_f_over_f,
 )
-from twopy.analysis.dff_options import DeltaFOverFOptions
+from twopy.analysis.dff_options import DeltaFOverFBaselineMode, DeltaFOverFOptions
 from twopy.analysis.epoch_mapping import (
     InterpolatedEpochMapping,
     interpolate_stimulus_epochs_to_frame_windows,
@@ -32,6 +32,7 @@ from twopy.analysis.persistence import (
     write_response_summary_grouped_csv,
     write_response_summary_trials_csv,
 )
+from twopy.analysis.response_context import default_recording_baseline_epoch_number
 from twopy.analysis.response_processing import (
     CorrelationFilterOptions,
     LowPassFilterOptions,
@@ -58,6 +59,7 @@ from twopy.analysis.trials import (
     is_baseline_epoch_name,
     make_frame_windows,
     map_stimulus_epochs_to_frame_windows,
+    no_baseline_epoch_frame_windows,
     resolve_baseline_frame_windows,
     select_baseline_frame_windows,
     split_traces_by_frame_windows,
@@ -85,6 +87,8 @@ __all__ = [
     "compute_recording_responses",
     "CorrelationFilterOptions",
     "default_baseline_epoch_number",
+    "default_recording_baseline_epoch_number",
+    "DeltaFOverFBaselineMode",
     "DeltaFOverFOptions",
     "DeltaFOverFFitMode",
     "EpochFrameWindow",
@@ -102,6 +106,7 @@ __all__ = [
     "LowPassFilterOptions",
     "make_frame_windows",
     "map_stimulus_epochs_to_frame_windows",
+    "no_baseline_epoch_frame_windows",
     "RoiDeltaFOverF",
     "ResponseProcessingOptions",
     "RoiCorrelationScores",

{twopy-0.1.7 → twopy-0.1.8}/src/twopy/analysis/background_subtraction.py

@@ -9,6 +9,7 @@ trace extraction stay in ``twopy.roi``; dF/F and trial analysis can consume the
 auditable outputs produced here.
 """
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Literal
 
@@ -75,6 +76,7 @@ def extract_background_corrected_roi_traces(
     local_y_radius: int | None = None,
     local_percentile: float = 20.0,
     spatial_domain: SpatialDomain = "alignment_valid_crop",
+    check_cancelled: Callable[[], None] | None = None,
 ) -> BackgroundCorrectedRoiTraces:
     """Extract ROI traces plus an explicit background correction.
 
@@ -108,6 +110,8 @@ def extract_background_corrected_roi_traces(
             uses the alignment-valid crop saved during conversion, matching the
             crop-domain analysis contract while keeping ROI masks stored in
             full-frame coordinates.
+        check_cancelled: Optional callback that raises ``CancelledError`` when
+            an interactive caller has superseded this computation.
 
     Returns:
         ``BackgroundCorrectedRoiTraces`` with raw, background, and corrected
@@ -115,7 +119,10 @@ def extract_background_corrected_roi_traces(
 
     Raises:
         ValueError: If masks do not match the movie or a background mask is
-            empty.
+            empty. ROI y-stripe background correction also raises when the
+            selected spatial domain has no unlabeled pixels outside all ROIs,
+            which is expected for dense grid ROIs that cover the whole analysis
+            crop.
 
     The function streams movie chunks from HDF5 and never loads the full movie
     into memory. Each method records enough metadata to audit how the background
@@ -124,6 +131,7 @@ def extract_background_corrected_roi_traces(
     _validate_background_method(method)
     validate_trace_statistic(statistic)
     _validate_roi_movie_shape(roi_set, recording)
+    _check_cancelled(check_cancelled)
 
     frame_start, frame_stop = normalize_frame_range(
         frame_count=recording.movie.shape[0],
@@ -144,6 +152,7 @@ def extract_background_corrected_roi_traces(
             frame_stop=frame_stop,
             chunk_frames=chunk_frames,
             spatial_crop=crop,
+            check_cancelled=check_cancelled,
         )
         background_values = np.zeros_like(raw_values)
         corrected_values = raw_values.copy()
@@ -162,6 +171,7 @@ def extract_background_corrected_roi_traces(
                 percentile=global_percentile,
                 spatial_crop=crop,
                 spatial_domain=spatial_domain,
+                check_cancelled=check_cancelled,
             )
         )
     elif method == "movie_y_stripe_percentile":
@@ -176,6 +186,7 @@ def extract_background_corrected_roi_traces(
                 percentile=stripe_percentile,
                 spatial_crop=crop,
                 spatial_domain=spatial_domain,
+                check_cancelled=check_cancelled,
             )
         )
     elif method == "roi_y_stripe_percentile":
@@ -191,6 +202,7 @@ def extract_background_corrected_roi_traces(
                 local_percentile=local_percentile,
                 spatial_crop=crop,
                 spatial_domain=spatial_domain,
+                check_cancelled=check_cancelled,
             )
         )
 
@@ -244,6 +256,7 @@ def _extract_mean_traces_from_indices(
     frame_stop: int,
     chunk_frames: int,
     spatial_crop: SpatialCrop,
+    check_cancelled: Callable[[], None] | None = None,
 ) -> npt.NDArray[np.float64]:
     """Extract mean traces for arbitrary flattened pixel-index groups.
 
@@ -255,6 +268,7 @@ def _extract_mean_traces_from_indices(
         frame_stop: Exclusive stop frame.
         chunk_frames: Maximum number of frames per HDF5 read.
         spatial_crop: Spatial domain read from each movie frame.
+        check_cancelled: Optional callback that raises when work is obsolete.
 
     Returns:
         Array shaped ``(frames, traces)``.
@@ -264,12 +278,14 @@ def _extract_mean_traces_from_indices(
     rather than total recording length.
     """
     traces = np.empty((frame_stop - frame_start, len(pixel_indices_by_trace)))
+    _check_cancelled(check_cancelled)
     for chunk_start, chunk_stop, frames in recording.movie.iter_frame_batches(
         chunk_frames=chunk_frames,
         start=frame_start,
         stop=frame_stop,
         spatial_crop=spatial_crop,
     ):
+        _check_cancelled(check_cancelled)
         chunk_offset = chunk_start - frame_start
         chunk_slice = slice(chunk_offset, chunk_offset + (chunk_stop - chunk_start))
         chunk_flat = frames.reshape(frames.shape[0], -1)
@@ -277,6 +293,7 @@ def _extract_mean_traces_from_indices(
             traces[chunk_slice, trace_index] = chunk_flat[:, pixel_indices].mean(
                 axis=1,
             )
+        _check_cancelled(check_cancelled)
 
     return traces
 
@@ -291,6 +308,7 @@ def _extract_movie_global_percentile_corrected_traces(
     percentile: float,
     spatial_crop: SpatialCrop,
     spatial_domain: SpatialDomain,
+    check_cancelled: Callable[[], None] | None = None,
 ) -> tuple[
     npt.NDArray[np.float64],
     npt.NDArray[np.float64],
@@ -308,6 +326,7 @@ def _extract_movie_global_percentile_corrected_traces(
         percentile: Mean-image percentile used to define background pixels.
         spatial_crop: Spatial domain used for background and ROI pixels.
         spatial_domain: User-facing name of ``spatial_crop``.
+        check_cancelled: Optional callback that raises when work is obsolete.
 
     Returns:
         Raw ROI traces, repeated background traces, corrected ROI traces, and
@@ -317,6 +336,7 @@ def _extract_movie_global_percentile_corrected_traces(
     negatives to zero, and then averages corrected pixels inside each ROI.
     """
     _validate_percentile(percentile)
+    _check_cancelled(check_cancelled)
     mean_image = spatial_crop.crop_image(recording.mean_image)
     background_indices, threshold = _global_background_pixel_indices(
         mean_image,
@@ -334,6 +354,7 @@ def _extract_movie_global_percentile_corrected_traces(
         stop=frame_stop,
         spatial_crop=spatial_crop,
     ):
+        _check_cancelled(check_cancelled)
         chunk_offset = chunk_start - frame_start
         chunk_slice = slice(chunk_offset, chunk_offset + (chunk_stop - chunk_start))
         chunk_flat = frames.reshape(frames.shape[0], -1)
@@ -346,6 +367,7 @@ def _extract_movie_global_percentile_corrected_traces(
             # corrected ROI trace below zero.
             corrected_pixels = np.maximum(roi_pixels - background_trace[:, None], 0.0)
             corrected_values[chunk_slice, roi_index] = corrected_pixels.mean(axis=1)
+        _check_cancelled(check_cancelled)
 
     metadata: dict[str, BackgroundMetadataValue] = {
         "method": "movie_global_percentile",
@@ -369,6 +391,7 @@ def _extract_movie_y_stripe_percentile_corrected_traces(
     percentile: float,
     spatial_crop: SpatialCrop,
     spatial_domain: SpatialDomain,
+    check_cancelled: Callable[[], None] | None = None,
 ) -> tuple[
     npt.NDArray[np.float64],
     npt.NDArray[np.float64],
@@ -388,6 +411,7 @@ def _extract_movie_y_stripe_percentile_corrected_traces(
         percentile: Percentile used inside each frame stripe.
         spatial_crop: Spatial domain used for background and ROI pixels.
         spatial_domain: User-facing name of ``spatial_crop``.
+        check_cancelled: Optional callback that raises when work is obsolete.
 
     Returns:
         Raw ROI traces, stripe-field background traces, corrected traces, and
@@ -404,6 +428,7 @@ def _extract_movie_y_stripe_percentile_corrected_traces(
     near one ROI are safe neuropil reference pixels.
     """
     _validate_percentile(percentile)
+    _check_cancelled(check_cancelled)
     crop_shape = spatial_crop.crop_image(recording.mean_image).shape
     stripe_height = _resolve_stripe_y_height(
         row_count=crop_shape[0],
@@ -425,6 +450,7 @@ def _extract_movie_y_stripe_percentile_corrected_traces(
         stop=frame_stop,
         spatial_crop=spatial_crop,
     ):
+        _check_cancelled(check_cancelled)
         chunk_offset = chunk_start - frame_start
         chunk_slice = slice(chunk_offset, chunk_offset + (chunk_stop - chunk_start))
         background_field = _framewise_y_stripe_background_field(
@@ -443,6 +469,7 @@ def _extract_movie_y_stripe_percentile_corrected_traces(
             )
             corrected_pixels = np.maximum(roi_pixels - roi_background_pixels, 0.0)
             corrected_values[chunk_slice, roi_index] = corrected_pixels.mean(axis=1)
+        _check_cancelled(check_cancelled)
 
     metadata: dict[str, BackgroundMetadataValue] = {
         "method": "movie_y_stripe_percentile",
@@ -467,6 +494,7 @@ def _extract_roi_y_stripe_percentile_corrected_traces(
     local_percentile: float,
     spatial_crop: SpatialCrop,
     spatial_domain: SpatialDomain,
+    check_cancelled: Callable[[], None] | None = None,
 ) -> tuple[
     npt.NDArray[np.float64],
     npt.NDArray[np.float64],
@@ -487,6 +515,7 @@ def _extract_roi_y_stripe_percentile_corrected_traces(
             y-stripe.
         spatial_crop: Spatial domain used for background and ROI pixels.
         spatial_domain: User-facing name of ``spatial_crop``.
+        check_cancelled: Optional callback that raises when work is obsolete.
 
     Returns:
         Raw ROI traces, local background traces, corrected traces, and metadata.
@@ -508,6 +537,7 @@ def _extract_roi_y_stripe_percentile_corrected_traces(
         local_y_radius=local_y_radius,
     )
     _validate_percentile(local_percentile)
+    _check_cancelled(check_cancelled)
     background_indices_by_roi = _roi_y_stripe_background_pixel_indices(
         roi_masks=roi_masks,
         mean_image=spatial_crop.crop_image(recording.mean_image),
@@ -521,6 +551,7 @@ def _extract_roi_y_stripe_percentile_corrected_traces(
         frame_stop=frame_stop,
         chunk_frames=chunk_frames,
         spatial_crop=spatial_crop,
+        check_cancelled=check_cancelled,
     )
     background_values = _extract_mean_traces_from_indices(
         recording=recording,
@@ -529,6 +560,7 @@ def _extract_roi_y_stripe_percentile_corrected_traces(
         frame_stop=frame_stop,
         chunk_frames=chunk_frames,
         spatial_crop=spatial_crop,
+        check_cancelled=check_cancelled,
     )
     corrected_values = raw_values - background_values
     background_counts = tuple(
@@ -561,6 +593,13 @@ def _roi_pixel_indices_from_masks(
     return tuple(np.flatnonzero(mask).astype(np.int64) for mask in flat_masks)
 
 
+def _check_cancelled(check_cancelled: Callable[[], None] | None) -> None:
+    """Raise ``CancelledError`` when an interactive caller superseded this work."""
+    if check_cancelled is None:
+        return
+    check_cancelled()
+
+
 def _crop_roi_masks_for_domain(
     roi_set: RoiSet,
     spatial_crop: SpatialCrop,
@@ -770,6 +809,15 @@ def _roi_y_stripe_background_pixel_indices(
     """
     occupied_mask = np.any(roi_masks, axis=0)
     background_mask = ~occupied_mask
+    if not np.any(background_mask):
+        msg = (
+            "ROI y-stripe P% background subtraction needs unlabeled background "
+            "pixels outside all ROIs in the selected spatial domain. The current "
+            "ROI masks cover every pixel, which is common for dense grid ROIs; "
+            "use shared y-stripe P% or leave unlabeled background pixels."
+        )
+        raise ValueError(msg)
+
     row_grid = np.arange(background_mask.shape[0])[:, None]
     background_indices: list[npt.NDArray[np.int64]] = []
 
@@ -782,7 +830,10 @@ def _roi_y_stripe_background_pixel_indices(
         if local_candidate_values.size == 0:
             msg = (
                 f"ROI {roi_index} has no local background candidates within "
-                f"{local_y_radius} rows"
+                f"{local_y_radius} rows. ROI y-stripe P% only uses unlabeled "
+                "pixels outside all ROIs; increase the local y radius, use "
+                "shared y-stripe P%, or leave unlabeled background pixels near "
+                "this ROI."
             )
             raise ValueError(msg)
         local_threshold = float(np.percentile(local_candidate_values, local_percentile))

{twopy-0.1.7 → twopy-0.1.8}/src/twopy/analysis/dff_options.py

@@ -7,19 +7,23 @@ without hiding the scientific workflow parameters.
 """
 
 from dataclasses import dataclass
+from typing import Literal
 
 from twopy.analysis.background_subtraction import BackgroundCorrectionMethod
 from twopy.analysis.dff import DeltaFOverFFitMode
 
-__all__ = ["DeltaFOverFOptions"]
+__all__ = ["DeltaFOverFBaselineMode", "DeltaFOverFOptions"]
+
+DeltaFOverFBaselineMode = Literal["epoch", "no_baseline_epoch"]
 
 
 @dataclass(frozen=True)
 class DeltaFOverFOptions:
     """Options that control ROI dF/F computation before response grouping.
 
-    Inputs: baseline epoch selection, background correction method, baseline
-    window sampling, dF/F fit mode, and motion-artifact masking choice.
+    Inputs: baseline epoch selection, baseline mode, background correction
+    method, baseline window sampling, dF/F fit mode, and motion-artifact
+    masking choice.
     Outputs: typed parameters that map directly to
     ``compute_recording_responses`` and ``analyze_recording_responses``.
 
@@ -27,8 +31,9 @@ class DeltaFOverFOptions:
     response processing choices such as smoothing and correlation filtering.
     """
 
-    baseline_epoch_number: int = 1
+    baseline_epoch_number: int | None = None
     baseline_epoch_name: str | None = None
+    baseline_mode: DeltaFOverFBaselineMode = "epoch"
     background_method: BackgroundCorrectionMethod = "movie_global_percentile"
     baseline_sample_seconds: float | None = 1.0
     fit_mode: DeltaFOverFFitMode = "direct_bounded_tau"

{twopy-0.1.7 → twopy-0.1.8}/src/twopy/analysis/persistence.py

@@ -38,6 +38,15 @@ from twopy.analysis.responses import (
     validate_grouped_roi_responses,
 )
 from twopy.analysis.trials import EpochFrameWindow, FrameWindow
+from twopy.hdf5_utils import (
+    plain_hdf5_attr_value,
+)
+from twopy.hdf5_utils import (
+    read_string_dataset as _read_string_dataset,
+)
+from twopy.hdf5_utils import (
+    write_string_dataset as _write_string_dataset,
+)
 from twopy.roi import RoiSet, TraceStatistic, make_roi_set
 from twopy.typing_guards import (
     require_bool_array,
@@ -418,12 +427,12 @@ def _read_background_traces(group: h5py.Group) -> BackgroundCorrectedRoiTraces:
         start_frame=int(group.attrs["start_frame"]),
         stop_frame=int(group.attrs["stop_frame"]),
         statistic=require_string_choice(
-            _plain_attr_value(group.attrs["statistic"]),
+            plain_hdf5_attr_value(group.attrs["statistic"], scalar_only=True),
             name="traces statistic",
             allowed=_TRACE_STATISTICS,
         ),
         method=require_string_choice(
-            _plain_attr_value(group.attrs["method"]),
+            plain_hdf5_attr_value(group.attrs["method"], scalar_only=True),
             name="traces background correction method",
             allowed=_BACKGROUND_CORRECTION_METHODS,
         ),
@@ -704,7 +713,9 @@ def _read_response_trial(group: h5py.Group) -> RoiResponseTrial:
     """
     return RoiResponseTrial(
         epoch_number=int(group.attrs["epoch_number"]),
-        epoch_name=str(_plain_attr_value(group.attrs["epoch_name"])),
+        epoch_name=str(
+            plain_hdf5_attr_value(group.attrs["epoch_name"], scalar_only=True),
+        ),
         trial_index=int(group.attrs["trial_index"]),
         window_index=int(group.attrs["window_index"]),
         start_frame=int(group.attrs["start_frame"]),
@@ -789,41 +800,10 @@ def _read_metadata(group: h5py.Group) -> dict[str, str | int | float | bool]:
     Returns:
         Plain Python metadata dictionary.
     """
-    return {key: _plain_attr_value(value) for key, value in group.attrs.items()}
-
-
-def _write_string_dataset(
-    group: h5py.Group,
-    name: str,
-    values: tuple[str, ...],
-) -> None:
-    """Write a tuple of strings as a UTF-8 HDF5 dataset.
-
-    Args:
-        group: Destination HDF5 group.
-        name: Dataset name.
-        values: String values to write.
-
-    Returns:
-        None.
-    """
-    group.create_dataset(
-        name,
-        data=np.asarray(values, dtype=h5py.string_dtype("utf-8")),
-    )
-
-
-def _read_string_dataset(group: h5py.Group, name: str) -> tuple[str, ...]:
-    """Read a UTF-8 string dataset.
-
-    Args:
-        group: HDF5 group containing the dataset.
-        name: Dataset name.
-
-    Returns:
-        Tuple of decoded strings.
-    """
-    return tuple(_decode_string(value) for value in group[name][()])
+    return {
+        key: plain_hdf5_attr_value(value, scalar_only=True)
+        for key, value in group.attrs.items()
+    }
 
 
 def _time_columns(trials: Sequence[RoiResponseTrial]) -> tuple[str, ...]:
@@ -1045,41 +1025,7 @@ def _require_analysis_format(h5_file: h5py.File, path: Path) -> None:
     Returns:
         None.
     """
-    actual = str(_plain_attr_value(h5_file.attrs.get("twopy_format", "")))
+    actual = str(plain_hdf5_attr_value(h5_file.attrs.get("twopy_format", "")))
     if actual != ANALYSIS_OUTPUT_FILE_FORMAT:
         msg = f"Expected {ANALYSIS_OUTPUT_FILE_FORMAT!r} file at {path}"
         raise ValueError(msg)
-
-
-def _plain_attr_value(value: object) -> str | int | float | bool:
-    """Convert one HDF5 attribute value to a plain Python scalar.
-
-    Args:
-        value: Raw HDF5 attribute value.
-
-    Returns:
-        Plain string, integer, float, or boolean.
-    """
-    if isinstance(value, bytes):
-        return value.decode("utf-8")
-    if isinstance(value, np.bool_ | bool):
-        return bool(value)
-    if isinstance(value, np.integer | int):
-        return int(value)
-    if isinstance(value, np.floating | float):
-        return float(value)
-    return str(value)
-
-
-def _decode_string(value: object) -> str:
-    """Decode one HDF5 string scalar.
-
-    Args:
-        value: Raw scalar read from a string dataset.
-
-    Returns:
-        Decoded text.
-    """
-    if isinstance(value, bytes):
-        return value.decode("utf-8")
-    return str(value)