TwoPy 0.2.1__tar.gz → 0.3.1__tar.gz

{twopy-0.2.1 → twopy-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twopy
-Version: 0.2.1
+Version: 0.3.1
 Summary: Two-photon imaging analysis tool with a napari interface.
 Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
 License-Expression: MIT

{twopy-0.2.1 → twopy-0.3.1}/pyproject.toml

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

{twopy-0.2.1 → twopy-0.3.1}/src/twopy/__init__.py

@@ -94,15 +94,6 @@ from twopy.converted import (
     recording_frame_rate_hz,
     recording_hemisphere,
 )
-from twopy.napari import (
-    NapariRecordingView,
-    NapariSidebarWidgets,
-    add_twopy_magicgui_controls,
-    launch_napari,
-    open_recording_in_napari,
-    roi_label_image_from_layer,
-    save_napari_label_rois,
-)
 from twopy.photodiode_classification import (
     ClassifiedPhotodiodeEvent,
     ClassifiedStimulusTiming,
@@ -180,7 +171,6 @@ __all__ = [
     "AnalysisResponseComputation",
     "add_manual_roi_match_group",
     "analyze_recording_responses",
-    "add_twopy_magicgui_controls",
     "append_manual_roi_match_rows",
     "apply_motion_artifact_mask_to_delta_f_over_f",
     "BackgroundCorrectedRoiTraces",
@@ -227,7 +217,6 @@ __all__ = [
     "is_baseline_epoch_name",
     "KernelFitMethod",
     "KernelStimulusModality",
-    "launch_napari",
     "load_analysis_outputs",
     "load_response_map_data",
     "load_manual_fov_group_rows",
@@ -254,9 +243,6 @@ __all__ = [
     "remove_manual_roi_match_group",
     "replace_manual_roi_match_group",
     "map_stimulus_specific_column",
-    "NapariRecordingView",
-    "NapariSidebarWidgets",
-    "open_recording_in_napari",
     "pair_photodiode_events_to_imaging_frames",
     "PhotodiodeAlignment",
     "PhotodiodeDurationClass",
@@ -296,13 +282,11 @@ __all__ = [
     "RoiResponseTrial",
     "RoiSet",
     "RoiTraces",
-    "roi_label_image_from_layer",
     "roi_set_to_label_image",
     "save_analysis_outputs",
     "save_response_map_data",
     "save_manual_fov_group_rows",
     "save_manual_roi_match_rows",
-    "save_napari_label_rois",
     "save_roi_set",
     "select_baseline_frame_windows",
     "select_pixel_calibration_group",

{twopy-0.2.1 → twopy-0.3.1}/src/twopy/analysis/__init__.py

@@ -66,6 +66,13 @@ from twopy.analysis.response_maps import (
     load_response_map_data,
     save_response_map_data,
 )
+from twopy.analysis.response_plotting import (
+    EpochResponsePlotData,
+    ResponsePlotData,
+    filter_response_plot_data_rois,
+    response_plot_data_from_grouped,
+    response_plot_window_options_from_grouped,
+)
 from twopy.analysis.response_processing import (
     CorrelationFilterOptions,
     LowPassFilterOptions,
@@ -130,6 +137,7 @@ __all__ = [
     "DeltaFOverFOptions",
     "DeltaFOverFFitMode",
     "EpochResponseMap",
+    "EpochResponsePlotData",
     "EpochFrameWindow",
     "extract_background_corrected_roi_traces",
     "fit_recording_stimulus_kernels",
@@ -163,6 +171,7 @@ __all__ = [
     "ResponseMapData",
     "ResponseMapMode",
     "ResponseMapOptions",
+    "ResponsePlotData",
     "ResponseProcessingOptions",
     "RoiCorrelationScores",
     "RoiResponseSummary",
@@ -181,9 +190,12 @@ __all__ = [
     "save_manual_roi_match_rows",
     "select_baseline_frame_windows",
     "finite_mean_and_sem",
+    "filter_response_plot_data_rois",
     "split_traces_by_frame_windows",
     "StimulusKernelOptions",
     "SmoothingOptions",
+    "response_plot_data_from_grouped",
+    "response_plot_window_options_from_grouped",
     "summarize_epoch_roi_responses",
     "summarize_grouped_responses",
     "TimingSource",

{twopy-0.2.1 → twopy-0.3.1}/src/twopy/analysis/persistence.py

@@ -10,7 +10,9 @@ MATLAB/TIFF files or decide analysis parameters.
 
 import csv
 import json
-from collections.abc import Mapping, Sequence
+import os
+import tempfile
+from collections.abc import Callable, Iterator, Mapping, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -48,6 +50,10 @@ from twopy.hdf5_utils import (
     write_string_dataset as _write_string_dataset,
 )
 from twopy.roi import RoiSet, TraceStatistic, make_roi_set
+from twopy.spatial_orientation import (
+    require_twopy_spatial_orientation,
+    write_twopy_spatial_orientation,
+)
 from twopy.typing_guards import (
     require_bool_array,
     require_float64_array,
@@ -153,8 +159,11 @@ def save_analysis_outputs(
         None.
 
     The HDF5 file stores arrays with gzip compression where arrays can be large.
-    The HDF5 file is the complete audit trail. CSV files duplicate response
-    time series in a spreadsheet-friendly layout for quick plotting and checks.
+    The HDF5 file is the complete audit trail. CSV files are derived exports for
+    quick spreadsheet plotting and checks, and are written after the HDF5 file.
+    Each output file is written through a temporary sibling path so a failed
+    write leaves the previous complete file in place; the HDF5 and CSV files are
+    not replaced as one multi-file transaction.
     """
     summary_outputs = (
         response_summary_trials_csv,
@@ -171,35 +180,40 @@ def save_analysis_outputs(
     if grouped_responses is not None:
         validate_grouped_roi_responses(grouped_responses)
 
-    output_path = path.expanduser()
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    with h5py.File(output_path, "w") as h5_file:
-        h5_file.attrs["twopy_format"] = ANALYSIS_OUTPUT_FILE_FORMAT
-        if roi_set is not None:
-            _write_roi_set(h5_file.create_group("roi_set"), roi_set)
-        if traces is not None:
-            _write_background_traces(h5_file.create_group("traces"), traces)
-        if dff is not None:
-            _write_dff(h5_file.create_group("dff"), dff)
-        if len(epoch_windows) > 0:
-            _write_epoch_windows(h5_file.create_group("epoch_windows"), epoch_windows)
-        if len(baseline_windows) > 0:
-            _write_frame_windows(
-                h5_file.create_group("baseline_windows"),
-                baseline_windows,
-            )
-        if grouped_responses is not None:
-            _write_grouped_responses(
-                h5_file.create_group("responses"),
-                grouped_responses,
-            )
-        if response_processing_options is not None:
-            write_response_processing_group(
-                h5_file.create_group("response_processing"),
-                options=response_processing_options,
-                normalization_factors=normalization_factors,
-                correlation_scores=correlation_scores,
-            )
+    def write_hdf5(output_path: Path) -> None:
+        """Write the analysis HDF5 contents to one already-created path."""
+        with h5py.File(output_path, "w") as h5_file:
+            h5_file.attrs["twopy_format"] = ANALYSIS_OUTPUT_FILE_FORMAT
+            if roi_set is not None:
+                _write_roi_set(h5_file.create_group("roi_set"), roi_set)
+            if traces is not None:
+                _write_background_traces(h5_file.create_group("traces"), traces)
+            if dff is not None:
+                _write_dff(h5_file.create_group("dff"), dff)
+            if len(epoch_windows) > 0:
+                _write_epoch_windows(
+                    h5_file.create_group("epoch_windows"),
+                    epoch_windows,
+                )
+            if len(baseline_windows) > 0:
+                _write_frame_windows(
+                    h5_file.create_group("baseline_windows"),
+                    baseline_windows,
+                )
+            if grouped_responses is not None:
+                _write_grouped_responses(
+                    h5_file.create_group("responses"),
+                    grouped_responses,
+                )
+            if response_processing_options is not None:
+                write_response_processing_group(
+                    h5_file.create_group("response_processing"),
+                    options=response_processing_options,
+                    normalization_factors=normalization_factors,
+                    correlation_scores=correlation_scores,
+                )
+
+    _write_file_atomically(path, write_hdf5)
 
     if grouped_responses is not None:
         if response_summary_trials_csv is not None:
@@ -214,6 +228,58 @@ def save_analysis_outputs(
             )
 
 
+def _write_file_atomically(
+    path: Path,
+    write_file: Callable[[Path], None],
+) -> None:
+    """Write a file beside its final path, then replace the old file.
+
+    Args:
+        path: Final destination path.
+        write_file: Callback that writes a complete file at the provided
+            temporary path.
+
+    Returns:
+        None.
+
+    Existing analysis files are useful audit records. Writing through a sibling
+    temporary path keeps a failed save from replacing the last complete output.
+    """
+    output_path = path.expanduser()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    temp_descriptor, temp_name = tempfile.mkstemp(
+        prefix=f".{output_path.name}.",
+        suffix=".tmp",
+        dir=output_path.parent,
+    )
+    os.close(temp_descriptor)
+    temp_path = Path(temp_name)
+    try:
+        write_file(temp_path)
+        temp_path.chmod(_replacement_file_mode(output_path))
+        temp_path.replace(output_path)
+    except Exception:
+        temp_path.unlink(missing_ok=True)
+        raise
+
+
+def _replacement_file_mode(path: Path) -> int:
+    """Return the file mode an atomic replacement should keep.
+
+    Args:
+        path: Final destination path.
+
+    Returns:
+        Existing file permissions, or normal new-file permissions after the
+        process umask.
+    """
+    if path.exists():
+        return path.stat().st_mode & 0o777
+    current_umask = os.umask(0)
+    os.umask(current_umask)
+    return 0o666 & ~current_umask
+
+
 def load_analysis_outputs(path: Path) -> LoadedAnalysisOutputs:
     """Load twopy analysis outputs from HDF5.
 
@@ -238,7 +304,9 @@ def load_analysis_outputs(path: Path) -> LoadedAnalysisOutputs:
         return LoadedAnalysisOutputs(
             path=input_path,
             roi_set=(
-                _read_roi_set(h5_file["roi_set"]) if "roi_set" in h5_file else None
+                _read_roi_set(h5_file["roi_set"], path=input_path)
+                if "roi_set" in h5_file
+                else None
             ),
             traces=(
                 _read_background_traces(h5_file["traces"])
@@ -291,25 +359,31 @@ def write_response_summary_trials_csv(
 
     Returns:
         None.
+
+    The CSV is written through a temporary sibling path so a failed write leaves
+    the previous complete file in place.
     """
-    output_path = path.expanduser()
-    output_path.parent.mkdir(parents=True, exist_ok=True)
     validate_grouped_roi_responses(grouped_responses)
     time_columns = _time_columns(grouped_responses.trials)
     fieldnames = (*_TRIAL_RESPONSE_CSV_BASE_COLUMNS, *time_columns)
-    with output_path.open("w", encoding="utf-8", newline="") as csv_file:
-        writer = csv.DictWriter(csv_file, fieldnames=fieldnames)
-        writer.writeheader()
-        for trial in grouped_responses.trials:
-            for roi_index, roi_label in enumerate(grouped_responses.roi_labels):
-                writer.writerow(
-                    _trial_response_row(
-                        trial,
-                        roi_index=roi_index,
-                        roi_label=roi_label,
-                        time_columns=time_columns,
-                    ),
-                )
+
+    def write_csv(output_path: Path) -> None:
+        """Write trial-level rows to one complete CSV file."""
+        with output_path.open("w", encoding="utf-8", newline="") as csv_file:
+            writer = csv.DictWriter(csv_file, fieldnames=fieldnames)
+            writer.writeheader()
+            for trial in grouped_responses.trials:
+                for roi_index, roi_label in enumerate(grouped_responses.roi_labels):
+                    writer.writerow(
+                        _trial_response_row(
+                            trial,
+                            roi_index=roi_index,
+                            roi_label=roi_label,
+                            time_columns=time_columns,
+                        ),
+                    )
+
+    _write_file_atomically(path, write_csv)
 
 
 def write_response_summary_grouped_csv(
@@ -324,17 +398,23 @@ def write_response_summary_grouped_csv(
 
     Returns:
         None.
+
+    The CSV is written through a temporary sibling path so a failed write leaves
+    the previous complete file in place.
     """
-    output_path = path.expanduser()
-    output_path.parent.mkdir(parents=True, exist_ok=True)
     validate_grouped_roi_responses(grouped_responses)
     time_columns = _time_columns(grouped_responses.trials)
     fieldnames = (*_GROUPED_RESPONSE_CSV_BASE_COLUMNS, *time_columns)
-    with output_path.open("w", encoding="utf-8", newline="") as csv_file:
-        writer = csv.DictWriter(csv_file, fieldnames=fieldnames)
-        writer.writeheader()
-        for row in _grouped_response_rows(grouped_responses, time_columns):
-            writer.writerow(row)
+
+    def write_csv(output_path: Path) -> None:
+        """Write grouped rows to one complete CSV file."""
+        with output_path.open("w", encoding="utf-8", newline="") as csv_file:
+            writer = csv.DictWriter(csv_file, fieldnames=fieldnames)
+            writer.writeheader()
+            for row in _iter_grouped_response_rows(grouped_responses, time_columns):
+                writer.writerow(row)
+
+    _write_file_atomically(path, write_csv)
 
 
 def _write_roi_set(group: h5py.Group, roi_set: RoiSet) -> None:
@@ -347,19 +427,28 @@ def _write_roi_set(group: h5py.Group, roi_set: RoiSet) -> None:
     Returns:
         None.
     """
-    group.create_dataset("masks", data=roi_set.masks, compression="gzip")
+    write_twopy_spatial_orientation(group)
+    masks = group.create_dataset("masks", data=roi_set.masks, compression="gzip")
+    write_twopy_spatial_orientation(masks)
     _write_string_dataset(group, "labels", roi_set.labels)
 
 
-def _read_roi_set(group: h5py.Group) -> RoiSet:
+def _read_roi_set(group: h5py.Group, *, path: Path) -> RoiSet:
     """Read a persisted ROI set.
 
     Args:
         group: HDF5 ``roi_set`` group.
+        path: Analysis output path used in validation errors.
 
     Returns:
         ``RoiSet`` with validated masks and labels.
     """
+    require_twopy_spatial_orientation(group, path=path, label="roi_set")
+    require_twopy_spatial_orientation(
+        group["masks"],
+        path=path,
+        label="roi_set/masks",
+    )
     return make_roi_set(
         require_bool_array(group["masks"][()], name="roi_set/masks", ndim=3),
         labels=_read_string_dataset(group, "labels"),
@@ -879,10 +968,10 @@ def _trial_response_row(
     return row
 
 
-def _grouped_response_rows(
+def _iter_grouped_response_rows(
     grouped: GroupedRoiResponses,
     time_columns: tuple[str, ...],
-) -> tuple[dict[str, str | int | float], ...]:
+) -> Iterator[dict[str, str | int | float]]:
     """Convert grouped trial responses to mean, SEM, and count CSV rows.
 
     Args:
@@ -890,12 +979,12 @@ def _grouped_response_rows(
         time_columns: Complete CSV time-column union.
 
     Returns:
-        Rows keyed by epoch, ROI, statistic, and relative timepoint.
+        Iterator over rows keyed by epoch, ROI, statistic, and relative
+        timepoint.
 
     Counts are per timepoint rather than one scalar because pre/post context or
     clipped recording edges can make some trials shorter than others.
     """
-    rows: list[dict[str, str | int | float]] = []
     for epoch_number, epoch_name, trials in _trials_by_epoch(grouped.trials):
         for roi_index, roi_label in enumerate(grouped.roi_labels):
             values_by_time = _values_by_time_column(
@@ -903,16 +992,13 @@ def _grouped_response_rows(
                 roi_index=roi_index,
                 time_columns=time_columns,
             )
-            rows.extend(
-                _epoch_roi_statistic_rows(
-                    epoch_number=epoch_number,
-                    epoch_name=epoch_name,
-                    roi_label=roi_label,
-                    values_by_time=values_by_time,
-                    time_columns=time_columns,
-                ),
+            yield from _epoch_roi_statistic_rows(
+                epoch_number=epoch_number,
+                epoch_name=epoch_name,
+                roi_label=roi_label,
+                values_by_time=values_by_time,
+                time_columns=time_columns,
             )
-    return tuple(rows)
 
 
 def _trials_by_epoch(

{twopy-0.2.1 → twopy-0.3.1}/src/twopy/analysis/response_maps.py

@@ -43,6 +43,10 @@ from twopy.analysis.timing import resolve_recording_timing
 from twopy.analysis.trials import EpochFrameWindow, is_baseline_epoch_name
 from twopy.converted import RecordingData, recording_frame_rate_hz
 from twopy.spatial import SpatialCrop
+from twopy.spatial_orientation import (
+    require_twopy_spatial_orientation,
+    write_twopy_spatial_orientation,
+)
 
 __all__ = [
     "EpochResponseMap",
@@ -247,29 +251,33 @@ def save_response_map_data(path: Path, map_data: ResponseMapData) -> None:
     recording-level movie products. Values are stored as normalized signed maps
     with the original dF/F scale in ``response_scale`` for audit.
     """
+    _require_response_map_shapes(map_data)
     output_path = path.expanduser()
     output_path.parent.mkdir(parents=True, exist_ok=True)
     with h5py.File(output_path, "w") as h5_file:
         h5_file.attrs["twopy_format"] = RESPONSE_MAP_FILE_FORMAT
         h5_file.attrs["response_scale"] = map_data.response_scale
+        write_twopy_spatial_orientation(h5_file)
         _write_response_map_options(h5_file.create_group("options"), map_data.options)
         _write_spatial_crop(h5_file.create_group("spatial_crop"), map_data.spatial_crop)
-        h5_file.create_dataset(
+        mean_image = h5_file.create_dataset(
             "mean_image",
             data=map_data.mean_image,
             compression="gzip",
         )
+        write_twopy_spatial_orientation(mean_image)
         epochs_group = h5_file.create_group("epochs")
         for index, epoch in enumerate(map_data.epochs):
             epoch_group = epochs_group.create_group(f"{index:04d}")
             epoch_group.attrs["epoch_name"] = epoch.epoch_name
             epoch_group.attrs["epoch_number"] = epoch.epoch_number
             epoch_group.attrs["trial_count"] = epoch.trial_count
-            epoch_group.create_dataset(
+            response_values = epoch_group.create_dataset(
                 "response_values",
                 data=epoch.response_values,
                 compression="gzip",
             )
+            write_twopy_spatial_orientation(response_values)
 
 
 def load_response_map_data(path: Path) -> ResponseMapData:
@@ -287,21 +295,34 @@ def load_response_map_data(path: Path) -> ResponseMapData:
     input_path = path.expanduser()
     with h5py.File(input_path, "r") as h5_file:
         _require_response_map_format(h5_file, input_path)
+        require_twopy_spatial_orientation(
+            h5_file,
+            path=input_path,
+            label="response heatmap file",
+        )
         options = _read_response_map_options(h5_file["options"])
         spatial_crop = _read_spatial_crop(h5_file["spatial_crop"])
-        mean_image = np.asarray(h5_file["mean_image"], dtype=np.float64)
+        mean_image_dataset = h5_file["mean_image"]
+        require_twopy_spatial_orientation(
+            mean_image_dataset,
+            path=input_path,
+            label="mean_image",
+        )
+        mean_image = np.asarray(mean_image_dataset, dtype=np.float64)
         epochs_group = h5_file["epochs"]
         epochs = tuple(
-            _read_epoch_response_map(epochs_group[name])
+            _read_epoch_response_map(epochs_group[name], path=input_path)
             for name in sorted(epochs_group.keys())
         )
-        return ResponseMapData(
+        map_data = ResponseMapData(
             mean_image=mean_image,
             epochs=epochs,
             options=options,
             spatial_crop=spatial_crop,
             response_scale=float(h5_file.attrs["response_scale"]),
         )
+        _require_response_map_shapes(map_data)
+        return map_data
 
 
 def _write_response_map_options(
@@ -357,16 +378,45 @@ def _read_spatial_crop(group: h5py.Group) -> SpatialCrop:
     )
 
 
-def _read_epoch_response_map(group: h5py.Group) -> EpochResponseMap:
+def _read_epoch_response_map(group: h5py.Group, *, path: Path) -> EpochResponseMap:
     """Read one persisted epoch response map."""
+    response_values = group["response_values"]
+    require_twopy_spatial_orientation(
+        response_values,
+        path=path,
+        label=f"{group.name}/response_values",
+    )
     return EpochResponseMap(
         epoch_name=_string_attr(group, "epoch_name"),
         epoch_number=int(group.attrs["epoch_number"]),
-        response_values=np.asarray(group["response_values"], dtype=np.float64),
+        response_values=np.asarray(response_values, dtype=np.float64),
         trial_count=int(group.attrs["trial_count"]),
     )
 
 
+def _require_response_map_shapes(map_data: ResponseMapData) -> None:
+    """Require heatmap spatial arrays to match their recorded crop."""
+    if map_data.mean_image.ndim != 2:
+        msg = (
+            f"response heatmap mean_image must be 2-D; got {map_data.mean_image.shape}"
+        )
+        raise ValueError(msg)
+    if map_data.mean_image.shape != map_data.spatial_crop.shape:
+        msg = (
+            "response heatmap mean_image shape must match spatial_crop shape; "
+            f"got {map_data.mean_image.shape} and {map_data.spatial_crop.shape}"
+        )
+        raise ValueError(msg)
+    for epoch in map_data.epochs:
+        if epoch.response_values.shape != map_data.mean_image.shape:
+            msg = (
+                "response heatmap response_values shape must match mean_image "
+                f"shape; got {epoch.response_values.shape} for "
+                f"{epoch.epoch_name!r} and {map_data.mean_image.shape}"
+            )
+            raise ValueError(msg)
+
+
 def _require_response_map_format(h5_file: h5py.File, path: Path) -> None:
     """Raise when an HDF5 file is not a twopy response heatmap file."""
     actual = _string_attr(h5_file, "twopy_format")