TwoPy 0.1.7__tar.gz → 0.1.9__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twopy
-Version: 0.1.7
+Version: 0.1.9
 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.9}/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.9}/pyproject.toml

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

@@ -14,15 +14,23 @@ from twopy.analysis import (
     BackgroundCorrectedRoiTraces,
     BackgroundCorrectionMethod,
     CorrelationFilterOptions,
+    DeltaFOverFBaselineMode,
     DeltaFOverFFitMode,
     DeltaFOverFOptions,
     EpochFrameWindow,
+    EpochResponseMap,
     FrameWindow,
     GroupedRoiResponses,
     GroupedRoiResponseSummary,
     InterpolatedEpochMapping,
     LoadedAnalysisOutputs,
     LowPassFilterOptions,
+    ManualFovGroupRow,
+    ManualRoiMatchRow,
+    ManualRoiMatchStatus,
+    ResponseMapData,
+    ResponseMapMode,
+    ResponseMapOptions,
     ResponseProcessingOptions,
     RoiCorrelationScores,
     RoiDeltaFOverF,
@@ -31,20 +39,33 @@ from twopy.analysis import (
     SmoothingOptions,
     WindowedRoiResponse,
     analyze_recording_responses,
+    append_manual_roi_match_rows,
     apply_motion_artifact_mask_to_delta_f_over_f,
+    compute_recording_response_maps,
     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,
     interpolate_stimulus_epochs_to_frame_windows,
     is_baseline_epoch_name,
     load_analysis_outputs,
+    load_manual_fov_group_rows,
+    load_manual_roi_match_rows,
+    load_response_map_data,
     make_frame_windows,
+    make_manual_fov_group_rows,
+    make_manual_roi_match_rows,
     map_stimulus_epochs_to_frame_windows,
+    next_group_cell_id,
+    no_baseline_epoch_frame_windows,
     resolve_baseline_frame_windows,
     save_analysis_outputs,
+    save_manual_fov_group_rows,
+    save_manual_roi_match_rows,
+    save_response_map_data,
     select_baseline_frame_windows,
     split_traces_by_frame_windows,
     summarize_epoch_roi_responses,
@@ -73,6 +94,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 +131,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,
@@ -106,6 +163,7 @@ __all__ = [
     "AnalysisResponseComputation",
     "analyze_recording_responses",
     "add_twopy_magicgui_controls",
+    "append_manual_roi_match_rows",
     "apply_motion_artifact_mask_to_delta_f_over_f",
     "BackgroundCorrectedRoiTraces",
     "BackgroundCorrectionMethod",
@@ -114,18 +172,26 @@ __all__ = [
     "ClassifiedStimulusWindow",
     "classify_recording_photodiode_events",
     "compute_roi_delta_f_over_f",
+    "compute_recording_response_maps",
     "compute_recording_responses",
     "CorrelationFilterOptions",
     "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",
+    "EpochResponseMap",
     "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,20 +200,35 @@ __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_response_map_data",
+    "load_manual_fov_group_rows",
+    "load_manual_roi_match_rows",
     "load_converted_recording",
+    "load_pixel_calibrations",
+    "load_pixel_calibration_profile_mappings",
     "load_roi_set",
     "load_source_conversion_inputs",
     "LoadedAnalysisOutputs",
     "LowPassFilterOptions",
+    "ManualFovGroupRow",
+    "ManualRoiMatchRow",
+    "ManualRoiMatchStatus",
     "make_roi_set_from_label_image",
     "make_frame_windows",
+    "make_manual_fov_group_rows",
+    "make_manual_roi_match_rows",
     "make_roi_set",
     "map_stimulus_epochs_to_frame_windows",
+    "next_group_cell_id",
+    "no_baseline_epoch_frame_windows",
     "map_stimulus_specific_column",
     "NapariRecordingView",
     "NapariSidebarWidgets",
@@ -158,9 +239,29 @@ __all__ = [
     "PhotodiodeEvent",
     "PhotodiodeEventType",
     "PhotodiodeEventSet",
+    "PixelCalibrationResolution",
+    "PixelCalibrationResolutionMethod",
+    "PixelCalibrationGroup",
+    "PixelCalibrationProfile",
+    "PixelCalibrationProfileMapping",
+    "PixelCalibrationProfileSource",
+    "PixelCalibrationRow",
+    "ResponseNormalization",
+    "ResponsePolarity",
+    "ResponseMapData",
+    "ResponseMapMode",
+    "ResponseMapOptions",
     "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",
@@ -170,9 +271,13 @@ __all__ = [
     "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",
     "split_traces_by_frame_windows",
     "SmoothingOptions",
     "SpatialCrop",
@@ -182,6 +287,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.9}/src/twopy/analysis/__init__.py

@@ -18,11 +18,24 @@ 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,
 )
+from twopy.analysis.group_matching import (
+    ManualFovGroupRow,
+    ManualRoiMatchRow,
+    ManualRoiMatchStatus,
+    append_manual_roi_match_rows,
+    load_manual_fov_group_rows,
+    load_manual_roi_match_rows,
+    make_manual_fov_group_rows,
+    make_manual_roi_match_rows,
+    next_group_cell_id,
+    save_manual_fov_group_rows,
+    save_manual_roi_match_rows,
+)
 from twopy.analysis.motion import apply_motion_artifact_mask_to_delta_f_over_f
 from twopy.analysis.persistence import (
     ANALYSIS_OUTPUT_FILE_FORMAT,
@@ -32,6 +45,16 @@ 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_maps import (
+    EpochResponseMap,
+    ResponseMapData,
+    ResponseMapMode,
+    ResponseMapOptions,
+    compute_recording_response_maps,
+    load_response_map_data,
+    save_response_map_data,
+)
 from twopy.analysis.response_processing import (
     CorrelationFilterOptions,
     LowPassFilterOptions,
@@ -58,6 +81,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,
@@ -83,10 +107,14 @@ __all__ = [
     "BackgroundCorrectionMethod",
     "compute_roi_delta_f_over_f",
     "compute_recording_responses",
+    "compute_recording_response_maps",
     "CorrelationFilterOptions",
     "default_baseline_epoch_number",
+    "default_recording_baseline_epoch_number",
+    "DeltaFOverFBaselineMode",
     "DeltaFOverFOptions",
     "DeltaFOverFFitMode",
+    "EpochResponseMap",
     "EpochFrameWindow",
     "extract_background_corrected_roi_traces",
     "frame_windows_from_photodiode_alignment",
@@ -98,17 +126,34 @@ __all__ = [
     "interpolate_stimulus_epochs_to_frame_windows",
     "is_baseline_epoch_name",
     "load_analysis_outputs",
+    "load_response_map_data",
     "LoadedAnalysisOutputs",
     "LowPassFilterOptions",
+    "ManualFovGroupRow",
+    "ManualRoiMatchRow",
+    "ManualRoiMatchStatus",
     "make_frame_windows",
+    "make_manual_fov_group_rows",
+    "make_manual_roi_match_rows",
     "map_stimulus_epochs_to_frame_windows",
+    "no_baseline_epoch_frame_windows",
+    "next_group_cell_id",
     "RoiDeltaFOverF",
+    "ResponseMapData",
+    "ResponseMapMode",
+    "ResponseMapOptions",
     "ResponseProcessingOptions",
     "RoiCorrelationScores",
     "RoiResponseSummary",
     "RoiResponseTrial",
     "resolve_baseline_frame_windows",
+    "append_manual_roi_match_rows",
+    "load_manual_fov_group_rows",
+    "load_manual_roi_match_rows",
     "save_analysis_outputs",
+    "save_response_map_data",
+    "save_manual_fov_group_rows",
+    "save_manual_roi_match_rows",
     "select_baseline_frame_windows",
     "split_traces_by_frame_windows",
     "SmoothingOptions",

{twopy-0.1.7 → twopy-0.1.9}/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.9}/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"