TwoPy 0.1.9__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twopy
-Version: 0.1.9
+Version: 0.2.0
 Summary: Two-photon imaging analysis tool with a napari interface.
 Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
 License-Expression: MIT
@@ -75,6 +75,7 @@ When a source recording has not been converted yet, twopy converts it first. Con
 
 - [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.
+- [Custom workflow guide](docs/custom_workflows.md): add versioned local analyses to the napari Custom tab.
 - [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.

{twopy-0.1.9 → twopy-0.2.0}/README.md

@@ -55,6 +55,7 @@ When a source recording has not been converted yet, twopy converts it first. Con
 
 - [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.
+- [Custom workflow guide](docs/custom_workflows.md): add versioned local analyses to the napari Custom tab.
 - [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.

{twopy-0.1.9 → twopy-0.2.0}/pyproject.toml

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

{twopy-0.1.9 → twopy-0.2.0}/src/twopy/__init__.py

@@ -22,12 +22,17 @@ from twopy.analysis import (
     FrameWindow,
     GroupedRoiResponses,
     GroupedRoiResponseSummary,
-    InterpolatedEpochMapping,
+    Hemisphere,
+    KernelFitMethod,
+    KernelStimulusModality,
     LoadedAnalysisOutputs,
     LowPassFilterOptions,
     ManualFovGroupRow,
+    ManualRoiMatchGroup,
     ManualRoiMatchRow,
     ManualRoiMatchStatus,
+    RecordingKernelFit,
+    RecordingTiming,
     ResponseMapData,
     ResponseMapMode,
     ResponseMapOptions,
@@ -37,7 +42,10 @@ from twopy.analysis import (
     RoiResponseSummary,
     RoiResponseTrial,
     SmoothingOptions,
+    StimulusKernelOptions,
+    TimingSource,
     WindowedRoiResponse,
+    add_manual_roi_match_group,
     analyze_recording_responses,
     append_manual_roi_match_rows,
     apply_motion_artifact_mask_to_delta_f_over_f,
@@ -45,11 +53,13 @@ from twopy.analysis import (
     compute_recording_responses,
     compute_roi_delta_f_over_f,
     default_baseline_epoch_number,
+    default_kernel_stimulus_column,
     default_recording_baseline_epoch_number,
     extract_background_corrected_roi_traces,
-    frame_windows_from_photodiode_alignment,
+    finite_mean_and_sem,
+    fit_recording_stimulus_kernels,
+    fit_stimulus_kernel,
     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,
@@ -58,10 +68,13 @@ from twopy.analysis import (
     make_frame_windows,
     make_manual_fov_group_rows,
     make_manual_roi_match_rows,
-    map_stimulus_epochs_to_frame_windows,
+    matched_manual_roi_groups,
     next_group_cell_id,
     no_baseline_epoch_frame_windows,
+    remove_manual_roi_match_group,
+    replace_manual_roi_match_group,
     resolve_baseline_frame_windows,
+    resolve_recording_timing,
     save_analysis_outputs,
     save_manual_fov_group_rows,
     save_manual_roi_match_rows,
@@ -76,7 +89,11 @@ from twopy.analysis import (
 )
 from twopy.api import find_recordings
 from twopy.conversion import convert_recording_to_twopy, load_source_conversion_inputs
-from twopy.converted import load_converted_recording, recording_frame_rate_hz
+from twopy.converted import (
+    load_converted_recording,
+    recording_frame_rate_hz,
+    recording_hemisphere,
+)
 from twopy.napari import (
     NapariRecordingView,
     NapariSidebarWidgets,
@@ -161,6 +178,7 @@ __all__ = [
     "AlignedPhotodiodeEvent",
     "AnalysisResponseRun",
     "AnalysisResponseComputation",
+    "add_manual_roi_match_group",
     "analyze_recording_responses",
     "add_twopy_magicgui_controls",
     "append_manual_roi_match_rows",
@@ -181,6 +199,7 @@ __all__ = [
     "DEFAULT_PIXEL_CALIBRATION_PATH",
     "DEFAULT_PIXEL_CALIBRATION_PROFILE_PATH",
     "default_baseline_epoch_number",
+    "default_kernel_stimulus_column",
     "default_recording_baseline_epoch_number",
     "detect_photodiode_events",
     "detect_recording_photodiode_events",
@@ -194,18 +213,20 @@ __all__ = [
     "extract_rois_from_image",
     "extract_roi_traces",
     "find_recordings",
-    "frame_windows_from_photodiode_alignment",
+    "fit_recording_stimulus_kernels",
+    "fit_stimulus_kernel",
     "FrameWindow",
     "full_frame_crop",
     "group_delta_f_over_f_by_epoch",
     "GroupedRoiResponseSummary",
     "GroupedRoiResponses",
+    "Hemisphere",
     "grid_roi_set",
     "grid_roi_set_microns",
     "grid_size_pixels_from_microns",
-    "InterpolatedEpochMapping",
-    "interpolate_stimulus_epochs_to_frame_windows",
     "is_baseline_epoch_name",
+    "KernelFitMethod",
+    "KernelStimulusModality",
     "launch_napari",
     "load_analysis_outputs",
     "load_response_map_data",
@@ -219,16 +240,19 @@ __all__ = [
     "LoadedAnalysisOutputs",
     "LowPassFilterOptions",
     "ManualFovGroupRow",
+    "ManualRoiMatchGroup",
     "ManualRoiMatchRow",
     "ManualRoiMatchStatus",
+    "matched_manual_roi_groups",
     "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",
+    "remove_manual_roi_match_group",
+    "replace_manual_roi_match_group",
     "map_stimulus_specific_column",
     "NapariRecordingView",
     "NapariSidebarWidgets",
@@ -255,10 +279,14 @@ __all__ = [
     "ResponseStatistic",
     "ResponseWatershedExtraction",
     "ResponseWatershedScoreImages",
+    "RecordingKernelFit",
+    "RecordingTiming",
     "recording_frame_rate_hz",
+    "recording_hemisphere",
     "resolve_pixel_size_um",
     "resolve_pixel_calibration_profile",
     "resolve_baseline_frame_windows",
+    "resolve_recording_timing",
     "response_watershed_roi_set",
     "RoiExtractionConfig",
     "RoiExtractionMethod",
@@ -282,10 +310,13 @@ __all__ = [
     "SmoothingOptions",
     "SpatialCrop",
     "SpatialDomain",
+    "StimulusKernelOptions",
     "StimulusSpecificColumnMapping",
     "stimulus_epoch_names_by_number",
+    "finite_mean_and_sem",
     "summarize_epoch_roi_responses",
     "summarize_grouped_responses",
+    "TimingSource",
     "validate_grouped_roi_responses",
     "watershed_roi_set",
     "WindowedRoiResponse",

{twopy-0.1.9 → twopy-0.2.0}/src/twopy/analysis/__init__.py

@@ -19,23 +19,34 @@ from twopy.analysis.dff import (
     compute_roi_delta_f_over_f,
 )
 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,
+    ManualRoiMatchGroup,
     ManualRoiMatchRow,
     ManualRoiMatchStatus,
+    add_manual_roi_match_group,
     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,
+    matched_manual_roi_groups,
     next_group_cell_id,
+    remove_manual_roi_match_group,
+    replace_manual_roi_match_group,
     save_manual_fov_group_rows,
     save_manual_roi_match_rows,
 )
+from twopy.analysis.kernels import (
+    Hemisphere,
+    KernelFitMethod,
+    KernelStimulusModality,
+    RecordingKernelFit,
+    StimulusKernelOptions,
+    default_kernel_stimulus_column,
+    fit_recording_stimulus_kernels,
+    fit_stimulus_kernel,
+)
 from twopy.analysis.motion import apply_motion_artifact_mask_to_delta_f_over_f
 from twopy.analysis.persistence import (
     ANALYSIS_OUTPUT_FILE_FORMAT,
@@ -67,20 +78,24 @@ from twopy.analysis.responses import (
     GroupedRoiResponseSummary,
     RoiResponseSummary,
     RoiResponseTrial,
+    finite_mean_and_sem,
     group_delta_f_over_f_by_epoch,
     summarize_epoch_roi_responses,
     summarize_grouped_responses,
     validate_grouped_roi_responses,
 )
+from twopy.analysis.timing import (
+    RecordingTiming,
+    TimingSource,
+    resolve_recording_timing,
+)
 from twopy.analysis.trials import (
     EpochFrameWindow,
     FrameWindow,
     WindowedRoiResponse,
     default_baseline_epoch_number,
-    frame_windows_from_photodiode_alignment,
     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,
@@ -117,27 +132,33 @@ __all__ = [
     "EpochResponseMap",
     "EpochFrameWindow",
     "extract_background_corrected_roi_traces",
-    "frame_windows_from_photodiode_alignment",
+    "fit_recording_stimulus_kernels",
+    "fit_stimulus_kernel",
+    "default_kernel_stimulus_column",
+    "Hemisphere",
     "FrameWindow",
     "group_delta_f_over_f_by_epoch",
     "GroupedRoiResponseSummary",
     "GroupedRoiResponses",
-    "InterpolatedEpochMapping",
-    "interpolate_stimulus_epochs_to_frame_windows",
     "is_baseline_epoch_name",
+    "KernelFitMethod",
+    "KernelStimulusModality",
     "load_analysis_outputs",
     "load_response_map_data",
     "LoadedAnalysisOutputs",
     "LowPassFilterOptions",
     "ManualFovGroupRow",
+    "ManualRoiMatchGroup",
     "ManualRoiMatchRow",
     "ManualRoiMatchStatus",
+    "matched_manual_roi_groups",
     "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",
+    "RecordingKernelFit",
+    "RecordingTiming",
     "RoiDeltaFOverF",
     "ResponseMapData",
     "ResponseMapMode",
@@ -147,18 +168,25 @@ __all__ = [
     "RoiResponseSummary",
     "RoiResponseTrial",
     "resolve_baseline_frame_windows",
+    "resolve_recording_timing",
+    "add_manual_roi_match_group",
     "append_manual_roi_match_rows",
     "load_manual_fov_group_rows",
     "load_manual_roi_match_rows",
+    "remove_manual_roi_match_group",
+    "replace_manual_roi_match_group",
     "save_analysis_outputs",
     "save_response_map_data",
     "save_manual_fov_group_rows",
     "save_manual_roi_match_rows",
     "select_baseline_frame_windows",
+    "finite_mean_and_sem",
     "split_traces_by_frame_windows",
+    "StimulusKernelOptions",
     "SmoothingOptions",
     "summarize_epoch_roi_responses",
     "summarize_grouped_responses",
+    "TimingSource",
     "validate_grouped_roi_responses",
     "WindowedRoiResponse",
     "write_response_summary_grouped_csv",

{twopy-0.1.9 → twopy-0.2.0}/src/twopy/analysis/group_matching.py

@@ -17,14 +17,19 @@ from typing import Literal
 
 __all__ = [
     "ManualFovGroupRow",
+    "ManualRoiMatchGroup",
     "ManualRoiMatchRow",
     "ManualRoiMatchStatus",
+    "add_manual_roi_match_group",
     "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",
+    "matched_manual_roi_groups",
     "next_group_cell_id",
+    "remove_manual_roi_match_group",
+    "replace_manual_roi_match_group",
     "save_manual_fov_group_rows",
     "save_manual_roi_match_rows",
 ]
@@ -87,6 +92,19 @@ class ManualRoiMatchRow:
     note: str = ""
 
 
+@dataclass(frozen=True)
+class ManualRoiMatchGroup:
+    """Matched rows for one manually assigned cell group.
+
+    Inputs: existing ``ManualRoiMatchRow`` objects from a match table.
+    Outputs: one grouped decision for display or downstream group analysis.
+    """
+
+    group_cell_id: int
+    rows: tuple[ManualRoiMatchRow, ...]
+    note: str = ""
+
+
 def make_manual_fov_group_rows(
     recording_groups: Mapping[Path, str],
     *,
@@ -171,6 +189,112 @@ def make_manual_roi_match_rows(
     return tuple(rows)
 
 
+def matched_manual_roi_groups(
+    rows: Sequence[ManualRoiMatchRow],
+    *,
+    fov_group_id: str,
+) -> tuple[ManualRoiMatchGroup, ...]:
+    """Return matched ROI groups for one FOV id.
+
+    Args:
+        rows: Manual ROI match rows from memory or CSV.
+        fov_group_id: FOV id whose matched groups should be returned.
+
+    Returns:
+        Groups sorted by ``group_cell_id``. Non-matched statuses and other FOVs
+        are ignored.
+    """
+    _validate_fov_group_id(fov_group_id)
+    grouped: dict[int, list[ManualRoiMatchRow]] = {}
+    for row in rows:
+        if row.status != "matched" or row.fov_group_id != fov_group_id:
+            continue
+        grouped.setdefault(row.group_cell_id, []).append(row)
+    groups: list[ManualRoiMatchGroup] = []
+    for group_cell_id, group_rows in sorted(grouped.items()):
+        row_tuple = tuple(group_rows)
+        groups.append(
+            ManualRoiMatchGroup(
+                group_cell_id=group_cell_id,
+                rows=row_tuple,
+                note=_shared_row_note(row_tuple),
+            ),
+        )
+    return tuple(groups)
+
+
+def add_manual_roi_match_group(
+    rows: Sequence[ManualRoiMatchRow],
+    recording_rois: Mapping[Path, str],
+    *,
+    fov_group_id: str,
+    note: str = "",
+) -> tuple[tuple[ManualRoiMatchRow, ...], int]:
+    """Append one new matched ROI group to existing rows.
+
+    Args:
+        rows: Existing manual ROI match rows.
+        recording_rois: Mapping from recording path to selected ROI label.
+        fov_group_id: FOV id for the new matched group.
+        note: Optional note copied to every new row.
+
+    Returns:
+        Updated row tuple and the assigned ``group_cell_id``.
+    """
+    _validate_fov_group_id(fov_group_id)
+    group_cell_id = next_group_cell_id(rows)
+    group_rows = make_manual_roi_match_rows(
+        recording_rois,
+        group_cell_id=group_cell_id,
+        fov_group_id=fov_group_id,
+        status="matched",
+        note=note,
+    )
+    return (*tuple(rows), *group_rows), group_cell_id
+
+
+def replace_manual_roi_match_group(
+    rows: Sequence[ManualRoiMatchRow],
+    recording_rois: Mapping[Path, str],
+    *,
+    fov_group_id: str,
+    group_cell_id: int,
+    note: str = "",
+) -> tuple[ManualRoiMatchRow, ...]:
+    """Replace one matched group inside one FOV while preserving other rows.
+
+    Args:
+        rows: Existing manual ROI match rows.
+        recording_rois: Replacement recording-to-ROI selections.
+        fov_group_id: FOV id containing the group.
+        group_cell_id: Existing group id to replace.
+        note: Optional note copied to every replacement row.
+
+    Returns:
+        Updated row tuple.
+    """
+    _validate_fov_group_id(fov_group_id)
+    replacement_rows = make_manual_roi_match_rows(
+        recording_rois,
+        group_cell_id=group_cell_id,
+        fov_group_id=fov_group_id,
+        status="matched",
+        note=note,
+    )
+    retained_rows = _rows_without_matched_group(rows, fov_group_id, group_cell_id)
+    return (*retained_rows, *replacement_rows)
+
+
+def remove_manual_roi_match_group(
+    rows: Sequence[ManualRoiMatchRow],
+    *,
+    fov_group_id: str,
+    group_cell_id: int,
+) -> tuple[ManualRoiMatchRow, ...]:
+    """Remove one matched group inside one FOV while preserving other rows."""
+    return _rows_without_matched_group(rows, fov_group_id, group_cell_id)
+
+
 def save_manual_fov_group_rows(
     rows: Iterable[ManualFovGroupRow],
     path: Path,
@@ -289,6 +413,31 @@ def next_group_cell_id(rows: Sequence[ManualRoiMatchRow]) -> int:
     return max(row.group_cell_id for row in rows) + 1
 
 
+def _rows_without_matched_group(
+    rows: Sequence[ManualRoiMatchRow],
+    fov_group_id: str,
+    group_cell_id: int,
+) -> tuple[ManualRoiMatchRow, ...]:
+    """Return rows after removing one matched group in one FOV."""
+    _validate_fov_group_id(fov_group_id)
+    _validate_group_cell_id(group_cell_id)
+    return tuple(
+        row
+        for row in rows
+        if not (
+            row.status == "matched"
+            and row.fov_group_id == fov_group_id
+            and row.group_cell_id == group_cell_id
+        )
+    )
+
+
+def _shared_row_note(rows: tuple[ManualRoiMatchRow, ...]) -> str:
+    """Return the common note for one matched group."""
+    notes = {row.note for row in rows}
+    return notes.pop() if len(notes) == 1 else ""
+
+
 def _write_csv_rows(
     path: Path,
     *,