TwoPy 0.4.1__tar.gz → 0.4.2__tar.gz

{twopy-0.4.1 → twopy-0.4.2}/PKG-INFO

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

{twopy-0.4.1 → twopy-0.4.2}/pyproject.toml

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

{twopy-0.4.1 → twopy-0.4.2}/src/twopy/analysis/persistence.py

@@ -102,7 +102,7 @@ class LoadedAnalysisOutputs:
 
     Inputs: one file written by ``save_analysis_outputs``.
     Outputs: optional ROI, trace, dF/F, window, response objects, and a warning
-        when an old file uses a setting twopy no longer uses.
+        when saved calculation rules are unknown or no longer supported.
 
     Groups are optional because scripts can save only the products they have
     computed. Missing groups load as ``None`` or an empty window tuple.
@@ -768,6 +768,9 @@ def _write_grouped_responses(
         trial_group.attrs["window_index"] = trial.window_index
         trial_group.attrs["start_frame"] = trial.start_frame
         trial_group.attrs["stop_frame"] = trial.stop_frame
+        if trial.epoch_frame_range is not None:
+            trial_group.attrs["epoch_start_frame"] = trial.epoch_frame_range[0]
+            trial_group.attrs["epoch_stop_frame"] = trial.epoch_frame_range[1]
         trial_group.create_dataset("frame_numbers", data=trial.frame_numbers)
         trial_group.create_dataset("time_seconds", data=trial.time_seconds)
         trial_group.create_dataset("values", data=trial.values, compression="gzip")
@@ -831,9 +834,28 @@ def _read_response_trial(group: h5py.Group) -> RoiResponseTrial:
             name="responses/trial/values",
             ndim=2,
         ),
+        epoch_frame_range=_read_trial_epoch_frame_range(group),
     )
 
 
+def _read_trial_epoch_frame_range(group: h5py.Group) -> tuple[int, int] | None:
+    """Read exact epoch bounds, preserving unknown bounds in historical files."""
+    names = ("epoch_start_frame", "epoch_stop_frame")
+    if not any(name in group.attrs for name in names):
+        return None
+    bounds: list[int] = []
+    for name in names:
+        if name not in group.attrs:
+            msg = f"Saved response trial is missing {name}"
+            raise ValueError(msg)
+        value = plain_hdf5_attr_value(group.attrs[name], scalar_only=True)
+        if isinstance(value, bool) or not isinstance(value, int):
+            msg = f"Saved response trial {name} must be an integer"
+            raise ValueError(msg)
+        bounds.append(value)
+    return bounds[0], bounds[1]
+
+
 def _optional_float_attr(group: h5py.Group, name: str) -> float | None:
     """Read one optional float HDF5 attribute.
 

{twopy-0.4.1 → twopy-0.4.2}/src/twopy/analysis/response_plotting.py

@@ -10,7 +10,7 @@ custom workflows can share the same response-plot data contract.
 """
 
 from collections.abc import Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 
 import numpy as np
@@ -274,13 +274,11 @@ def _filter_correlation_scores(
     if scores is None:
         return None
     keep_rows = list(keep_indices)
-    return RoiCorrelationScores(
+    return replace(
+        scores,
         roi_labels=tuple(scores.roi_labels[index] for index in keep_indices),
         scores=scores.scores[keep_rows],
         included_mask=scores.included_mask[keep_rows],
-        minimum_correlation=scores.minimum_correlation,
-        reference=scores.reference,
-        window_seconds=scores.window_seconds,
     )
 
 

{twopy-0.4.1 → twopy-0.4.2}/src/twopy/analysis/response_processing/apply.py

@@ -8,7 +8,7 @@ not know how options were selected, where outputs are saved, or how plots are
 drawn.
 """
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 
 import numpy as np
 import numpy.typing as npt
@@ -198,7 +198,7 @@ def normalize_grouped_roi_responses_by_epoch_abs_peak(
         raise ValueError(msg)
     factors = _normalization_factors(grouped, options=options)
     trials = tuple(
-        _copy_trial_with_values(trial, trial.values / factors.factors)
+        replace(trial, values=trial.values / factors.factors)
         for trial in grouped.trials
     )
     return (
@@ -313,9 +313,9 @@ def _copy_grouped_with_processed_values(
 ) -> GroupedRoiResponses:
     """Return grouped responses with each trial value matrix processed."""
     trials = tuple(
-        _copy_trial_with_values(
+        replace(
             trial,
-            _process_values(
+            values=_process_values(
                 trial.values,
                 options=options,
                 data_rate_hz=grouped.data_rate_hz,
@@ -395,7 +395,7 @@ def _mask_excluded_rois(
     for trial in grouped.trials:
         values = trial.values.copy()
         values[:, ~included_mask] = np.nan
-        trials.append(_copy_trial_with_values(trial, values))
+        trials.append(replace(trial, values=values))
     return GroupedRoiResponses(
         roi_labels=grouped.roi_labels,
         data_rate_hz=grouped.data_rate_hz,
@@ -406,24 +406,6 @@ def _mask_excluded_rois(
     )
 
 
-def _copy_trial_with_values(
-    trial: RoiResponseTrial,
-    values: npt.NDArray[np.float64],
-) -> RoiResponseTrial:
-    """Return one trial response with replacement values."""
-    return RoiResponseTrial(
-        epoch_number=trial.epoch_number,
-        epoch_name=trial.epoch_name,
-        trial_index=trial.trial_index,
-        window_index=trial.window_index,
-        start_frame=trial.start_frame,
-        stop_frame=trial.stop_frame,
-        frame_numbers=trial.frame_numbers,
-        time_seconds=trial.time_seconds,
-        values=values,
-    )
-
-
 def _validate_dff_for_processing(dff: RoiDeltaFOverF) -> None:
     """Validate a dF/F object before value-only processing."""
     if dff.values.ndim != 2:

{twopy-0.4.1 → twopy-0.4.2}/src/twopy/analysis/response_processing/options.py

@@ -99,8 +99,9 @@ class CorrelationFilterOptions:
     available elsewhere in the analysis record.
 
     ``window_seconds`` is a half-open ``(start, stop)`` interval on each trial's
-    epoch-relative time axis. ``None`` on the stop side leaves it unbounded, so
-    the default starts at epoch onset and uses the full stored epoch response.
+    epoch-relative time axis. The window is intersected with each trial's exact
+    epoch bounds. ``None`` on the stop side uses the epoch end. Plot context
+    never contributes, even when the requested window extends beyond an epoch.
     """
 
     reference: CorrelationFilterReference = "none"

{twopy-0.4.1 → twopy-0.4.2}/src/twopy/analysis/response_processing/persistence.py

@@ -25,7 +25,10 @@ from twopy.analysis.response_processing.options import (
     SmoothingMethod,
     SmoothingOptions,
 )
-from twopy.analysis.response_processing.qc import RoiCorrelationScores
+from twopy.analysis.response_processing.qc import (
+    CORRELATION_SCORING_RULE,
+    RoiCorrelationScores,
+)
 from twopy.hdf5_utils import (
     plain_hdf5_attr_value,
     write_string_dataset,
@@ -65,7 +68,7 @@ class PersistedResponseProcessing:
 
     Inputs: one ``response_processing`` HDF5 group.
     Outputs: typed options plus optional factors, ROI correlation scores, and a
-        warning when an old file uses a setting twopy no longer uses.
+        warning when saved calculation rules are unknown or no longer supported.
     """
 
     options: ResponseProcessingOptions
@@ -137,6 +140,8 @@ def write_response_processing_group(
             correlation_scores.minimum_correlation
         )
         scores_group.attrs["reference"] = correlation_scores.reference
+        if correlation_scores.scoring_rule is not None:
+            scores_group.attrs["scoring_rule"] = correlation_scores.scoring_rule
         scores_group.attrs["window_start_seconds"] = _optional_float_attr(
             correlation_scores.window_seconds[0],
         )
@@ -175,6 +180,21 @@ def read_response_processing_group(group: h5py.Group) -> PersistedResponseProces
             group["correlation_filter"],
         ),
     )
+    correlation_scores = (
+        _read_correlation_scores(group["correlation_scores"])
+        if "correlation_scores" in group
+        else None
+    )
+    warnings = [normalization_load_warning] if normalization_load_warning else []
+    if (
+        correlation_scores is not None
+        and correlation_scores.scoring_rule != CORRELATION_SCORING_RULE
+    ):
+        warnings.append(
+            "The scoring rule for these saved correlation scores is missing or "
+            "not supported. Twopy is showing the saved responses as stored. "
+            "Recompute responses to use stimulus-only correlation QC."
+        )
     return PersistedResponseProcessing(
         options=options,
         normalization_factors=(
@@ -189,12 +209,8 @@ def read_response_processing_group(group: h5py.Group) -> PersistedResponseProces
             )
             else None
         ),
-        correlation_scores=(
-            _read_correlation_scores(group["correlation_scores"])
-            if "correlation_scores" in group
-            else None
-        ),
-        load_warning=normalization_load_warning,
+        correlation_scores=correlation_scores,
+        load_warning=" ".join(warnings) or None,
     )
 
 
@@ -289,6 +305,13 @@ def _read_normalization_factors(
 
 def _read_correlation_scores(group: h5py.Group) -> RoiCorrelationScores:
     """Read persisted ROI correlation QC scores."""
+    scoring_rule = None
+    if "scoring_rule" in group.attrs:
+        value = plain_hdf5_attr_value(group.attrs["scoring_rule"], scalar_only=True)
+        if not isinstance(value, str) or not value.strip():
+            msg = "Saved correlation scoring_rule must be a non-empty string"
+            raise ValueError(msg)
+        scoring_rule = value
     return RoiCorrelationScores(
         roi_labels=_read_string_dataset(group, "roi_labels"),
         scores=require_float64_array(
@@ -308,6 +331,7 @@ def _read_correlation_scores(group: h5py.Group) -> RoiCorrelationScores:
             allowed=_CORRELATION_REFERENCES,
         ),
         window_seconds=_window_seconds_from_attrs(group),
+        scoring_rule=scoring_rule,
     )
 
 

{twopy-0.4.1 → twopy-0.4.2}/src/twopy/analysis/response_processing/qc.py

@@ -22,12 +22,16 @@ from twopy.analysis.responses import (
     RoiResponseTrial,
     validate_grouped_roi_responses,
 )
+from twopy.analysis.trials import is_baseline_epoch_name
 
 __all__ = [
+    "CORRELATION_SCORING_RULE",
     "RoiCorrelationScores",
     "score_roi_correlations",
 ]
 
+CORRELATION_SCORING_RULE = "stimulus_frames_without_interleave"
+
 
 @dataclass(frozen=True)
 class RoiCorrelationScores:
@@ -36,8 +40,12 @@ class RoiCorrelationScores:
     Inputs: grouped responses, a reference strategy, and a time window.
     Outputs: one score per ROI plus a Boolean inclusion mask.
 
-    Scores are averaged across repeated epoch trials. ROIs with no estimable
-    score are excluded when correlation filtering is enabled.
+    Scores average trial correlations across epochs except gray, grey, and
+    interleave epochs. Blank epochs contribute. ROIs with no estimable score
+    are excluded when correlation filtering is enabled.
+
+    ``scoring_rule`` identifies the calculation that produced these scores.
+    ``None`` marks scores whose calculation rule is unknown.
     """
 
     roi_labels: tuple[str, ...]
@@ -46,6 +54,7 @@ class RoiCorrelationScores:
     minimum_correlation: float
     reference: CorrelationFilterReference
     window_seconds: CorrelationWindowSeconds
+    scoring_rule: str | None = None
 
 
 def score_roi_correlations(
@@ -58,7 +67,8 @@ def score_roi_correlations(
     """Score each ROI by correlation to repeated epoch responses.
 
     Args:
-        grouped: Trial responses grouped by stimulus epoch.
+        grouped: Trial responses grouped by stimulus epoch, with exact
+            ``epoch_frame_range`` bounds on each scored trial.
         minimum_correlation: Minimum score required for inclusion.
         reference: Reference strategy. ``"epoch_mean"`` compares each trial to
             the other trials' mean. ``"epoch_peak"`` compares each non-peak
@@ -71,11 +81,15 @@ def score_roi_correlations(
 
     Raises:
         ValueError: If grouped response shapes, threshold, or reference are
-            invalid.
+            invalid, or a scored trial has no exact epoch bounds.
 
-    Correlations are computed only over samples inside ``window_seconds``. Mean
+    Correlations use only original epoch frames inside ``window_seconds``.
+    Pre- and post-stimulus plot context never contributes. Mean
     references are leave-one-out when an epoch has more than one trial, which
     avoids scoring a trial against itself.
+
+    Gray, grey, and interleave epochs do not contribute to either reference
+    strategy. Blank epochs contribute correlations within their own trial type.
     """
     _validate_correlation_inputs(grouped, minimum_correlation, reference)
     correlations: list[list[float]] = [[] for _ in grouped.roi_labels]
@@ -102,6 +116,7 @@ def score_roi_correlations(
         minimum_correlation=float(minimum_correlation),
         reference=reference,
         window_seconds=window_seconds,
+        scoring_rule=CORRELATION_SCORING_RULE,
     )
 
 
@@ -190,9 +205,12 @@ def _validate_correlation_inputs(
 def _trials_by_epoch(
     grouped: GroupedRoiResponses,
 ) -> dict[tuple[int, str], list[RoiResponseTrial]]:
-    """Group trials by stable epoch identity."""
+    """Group scored trials by epoch, excluding gray and interleave epochs."""
     by_epoch: dict[tuple[int, str], list[RoiResponseTrial]] = {}
     for trial in grouped.trials:
+        # Interleave responses do not measure stimulus response consistency.
+        if is_baseline_epoch_name(trial.epoch_name):
+            continue
         by_epoch.setdefault((trial.epoch_number, trial.epoch_name), []).append(trial)
     return by_epoch
 
@@ -201,23 +219,30 @@ def _aligned_epoch_cube(
     trials: list[RoiResponseTrial],
     grouped: GroupedRoiResponses,
 ) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
-    """Return trials aligned onto one relative-time frame axis."""
-    first_time = min(float(trial.time_seconds[0]) for trial in trials)
-    last_time = max(float(trial.time_seconds[-1]) for trial in trials)
-    frame_count = int(round((last_time - first_time) * grouped.data_rate_hz)) + 1
+    """Align original epoch frames without pre- or post-stimulus plot context."""
+    bounds = []
+    for trial in trials:
+        if trial.epoch_frame_range is None:
+            msg = (
+                "Correlation QC requires epoch_frame_range on each scored trial. "
+                "Recompute responses from epoch windows."
+            )
+            raise ValueError(msg)
+        bounds.append(trial.epoch_frame_range)
+    frame_count = max(stop - start for start, stop in bounds)
     cube = np.full(
         (len(trials), frame_count, len(grouped.roi_labels)),
         np.nan,
         dtype=np.float64,
     )
-    for trial_index, trial in enumerate(trials):
-        offsets = np.rint(
-            (trial.time_seconds - first_time) * grouped.data_rate_hz
-        ).astype(np.int64, copy=False)
-        cube[trial_index, offsets, :] = trial.values
-    time_seconds = first_time + (
-        np.arange(frame_count, dtype=np.float64) / grouped.data_rate_hz
-    )
+    for trial_index, (trial, (start, stop)) in enumerate(
+        zip(trials, bounds, strict=True)
+    ):
+        # Each trial contributes only its own epoch, even when durations differ.
+        cube[trial_index, : stop - start, :] = trial.values[
+            start - trial.start_frame : stop - trial.start_frame, :
+        ]
+    time_seconds = np.arange(frame_count, dtype=np.float64) / grouped.data_rate_hz
     return cube, time_seconds
 
 

{twopy-0.4.1 → twopy-0.4.2}/src/twopy/analysis/responses.py

@@ -41,6 +41,9 @@ class RoiResponseTrial:
 
     ``trial_index`` is one-based within each epoch because that is the number a
     scientist naturally uses when checking repeated presentations.
+
+    ``epoch_frame_range`` stores the original half-open epoch bounds without
+    plot context. ``None`` marks unknown bounds and prevents correlation QC.
     """
 
     epoch_number: int
@@ -52,6 +55,7 @@ class RoiResponseTrial:
     frame_numbers: npt.NDArray[np.int64]
     time_seconds: npt.NDArray[np.float64]
     values: npt.NDArray[np.float64]
+    epoch_frame_range: tuple[int, int] | None = None
 
 
 @dataclass(frozen=True)
@@ -203,6 +207,7 @@ def group_delta_f_over_f_by_epoch(
                 frame_numbers=frame_numbers,
                 time_seconds=time_seconds.astype(np.float64, copy=False),
                 values=dff.values[local_start:local_stop, :],
+                epoch_frame_range=(window.start_frame, window.stop_frame),
             ),
         )
 
@@ -347,11 +352,11 @@ def summarize_roi_response_trials(
     if len(trials) == 0:
         msg = "At least one trial is required for response trace summary"
         raise ValueError(msg)
-    for trial in trials:
-        _validate_grouped_response_trial(trial, roi_labels)
     if data_rate_hz <= 0:
         msg = f"data_rate_hz must be positive. Got {data_rate_hz}"
         raise ValueError(msg)
+    for trial in trials:
+        _validate_grouped_response_trial(trial, roi_labels, data_rate_hz)
 
     trial_tuple = tuple(trials)
     time_seconds = _shared_trial_time_axis(trial_tuple, data_rate_hz)
@@ -429,12 +434,15 @@ def validate_grouped_roi_responses(grouped: GroupedRoiResponses) -> None:
         msg = f"data_rate_hz must be positive. Got {grouped.data_rate_hz}"
         raise ValueError(msg)
     for trial in grouped.trials:
-        _validate_grouped_response_trial(trial, grouped.roi_labels)
+        _validate_grouped_response_trial(
+            trial, grouped.roi_labels, grouped.data_rate_hz
+        )
 
 
 def _validate_grouped_response_trial(
     trial: RoiResponseTrial,
     roi_labels: tuple[str, ...],
+    data_rate_hz: float,
 ) -> None:
     """Validate one grouped response trial against shared ROI labels."""
     if not np.issubdtype(trial.values.dtype, np.floating):
@@ -507,6 +515,21 @@ def _validate_grouped_response_trial(
     if not np.all(np.isfinite(trial.time_seconds)):
         msg = "trial time_seconds must be finite"
         raise ValueError(msg)
+    if trial.epoch_frame_range is not None:
+        if any(
+            isinstance(bound, bool) or not isinstance(bound, (int, np.integer))
+            for bound in trial.epoch_frame_range
+        ):
+            msg = "trial epoch_frame_range bounds must be integers"
+            raise ValueError(msg)
+        epoch_start, epoch_stop = trial.epoch_frame_range
+        if not trial.start_frame <= epoch_start < epoch_stop <= trial.stop_frame:
+            msg = "trial epoch_frame_range must lie within the response frame range"
+            raise ValueError(msg)
+        expected_time = (trial.frame_numbers - epoch_start) / data_rate_hz
+        if not np.allclose(trial.time_seconds, expected_time):
+            msg = "trial time_seconds must be relative to epoch_frame_range start"
+            raise ValueError(msg)
 
 
 def _validate_grouping_inputs(

{twopy-0.4.1 → twopy-0.4.2}/src/twopy/napari/plotting/docks/response_plot_widget.py

@@ -1047,10 +1047,12 @@ class _ResponsePlotWidget(QWidget):
             return
         roi_error = self._reload_saved_rois()
         self.set_response_plot_data(result, reset_axes=True)
+        messages = ["Reloaded saved analysis."]
+        if result.load_warning is not None:
+            messages.append(result.load_warning)
         if roi_error is not None:
-            self._update_status_label.setText(f"Reloaded saved analysis. {roi_error}")
-        elif result.load_warning is None:
-            self._update_status_label.setText("Reloaded saved analysis.")
+            messages.append(roi_error)
+        self._update_status_label.setText(" ".join(messages))
 
     def _reload_saved_rois(self) -> str | None:
         """Replace the active Labels layer with the saved ROI HDF5 file."""

{twopy-0.4.1 → twopy-0.4.2}/src/twopy.egg-info/PKG-INFO

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

{twopy-0.4.1 → twopy-0.4.2}/src/twopy.egg-info/SOURCES.txt

@@ -198,6 +198,7 @@ tests/test_cache_inventory.py
 tests/test_config.py
 tests/test_conversion.py
 tests/test_converted.py
+tests/test_correlation_qc.py
 tests/test_custom_workflows.py
 tests/test_database.py
 tests/test_database_date_filters.py
@@ -215,6 +216,7 @@ tests/test_load_workflow.py
 tests/test_matlab.py
 tests/test_motion.py
 tests/test_napari.py
+tests/test_napari_correlation_qc.py
 tests/test_napari_database_search.py
 tests/test_napari_display.py
 tests/test_napari_export.py