TwoPy 0.1.0__py3-none-any.whl

twopy/spatial.py

@@ -0,0 +1,154 @@
+"""Spatial crop contracts for converted two-photon recordings.
+
+Inputs: movie spatial shapes, alignment-derived crop bounds, and ROI masks.
+Outputs: typed crop objects and helpers that keep full-frame and cropped
+analysis coordinates explicit.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import numpy as np
+import numpy.typing as npt
+
+__all__ = [
+    "SpatialCrop",
+    "SpatialDomain",
+    "full_frame_crop",
+]
+
+SpatialDomain = Literal["alignment_valid_crop", "full_frame"]
+
+
+@dataclass(frozen=True)
+class SpatialCrop:
+    """A rectangular spatial domain inside a full movie frame.
+
+    Inputs: half-open bounds along the two spatial movie axes plus the original
+    full-frame shape.
+    Outputs: validated crop metadata and array slicing helpers.
+
+    ``axis0`` and ``axis1`` name NumPy movie axes directly. twopy avoids
+    top/left/x/y here because source files and display tools can disagree about
+    image orientation, while the array axes are unambiguous.
+    """
+
+    axis0_start: int
+    axis0_stop: int
+    axis1_start: int
+    axis1_stop: int
+    original_shape: tuple[int, int]
+    source: str
+
+    def __post_init__(self) -> None:
+        """Validate crop bounds immediately after construction.
+
+        Inputs: dataclass field values.
+        Outputs: ``None`` or a clear ``ValueError``.
+        """
+        axis0_length, axis1_length = self.original_shape
+        if (
+            self.axis0_start < 0
+            or self.axis1_start < 0
+            or self.axis0_stop > axis0_length
+            or self.axis1_stop > axis1_length
+            or self.axis0_start >= self.axis0_stop
+            or self.axis1_start >= self.axis1_stop
+        ):
+            msg = (
+                "Invalid spatial crop "
+                f"axis0=[{self.axis0_start}, {self.axis0_stop}), "
+                f"axis1=[{self.axis1_start}, {self.axis1_stop}) for "
+                f"shape {self.original_shape}"
+            )
+            raise ValueError(msg)
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """Return the spatial shape of this crop.
+
+        Inputs: crop bounds.
+        Outputs: ``(axis0_length, axis1_length)``.
+        """
+        return (
+            self.axis0_stop - self.axis0_start,
+            self.axis1_stop - self.axis1_start,
+        )
+
+    @property
+    def is_full_frame(self) -> bool:
+        """Return whether this crop covers the whole source frame.
+
+        Inputs: crop bounds and original shape.
+        Outputs: ``True`` for full-frame domains, otherwise ``False``.
+        """
+        return (
+            self.axis0_start == 0
+            and self.axis1_start == 0
+            and self.axis0_stop == self.original_shape[0]
+            and self.axis1_stop == self.original_shape[1]
+        )
+
+    def crop_image(
+        self,
+        image: npt.NDArray[Any],
+    ) -> npt.NDArray[Any]:
+        """Return the crop view from a full-frame image.
+
+        Args:
+            image: Two-dimensional full-frame image with ``original_shape``.
+
+        Returns:
+            View of ``image`` inside this crop.
+        """
+        if image.shape != self.original_shape:
+            msg = f"Image shape {image.shape} does not match {self.original_shape}"
+            raise ValueError(msg)
+        return image[
+            self.axis0_start : self.axis0_stop,
+            self.axis1_start : self.axis1_stop,
+        ]
+
+    def crop_masks(
+        self,
+        masks: npt.NDArray[np.bool_],
+    ) -> npt.NDArray[np.bool_]:
+        """Return ROI masks restricted to this crop.
+
+        Args:
+            masks: Boolean masks shaped ``(rois, axis0, axis1)`` in full-frame
+                movie coordinates.
+
+        Returns:
+            Boolean mask view shaped ``(rois, cropped_axis0, cropped_axis1)``.
+        """
+        if masks.ndim != 3 or masks.shape[1:] != self.original_shape:
+            msg = (
+                f"ROI mask shape {masks.shape} does not match crop source "
+                f"shape {self.original_shape}"
+            )
+            raise ValueError(msg)
+        return masks[
+            :,
+            self.axis0_start : self.axis0_stop,
+            self.axis1_start : self.axis1_stop,
+        ]
+
+
+def full_frame_crop(spatial_shape: tuple[int, int]) -> SpatialCrop:
+    """Create a crop object that covers an entire movie frame.
+
+    Args:
+        spatial_shape: Full movie spatial shape.
+
+    Returns:
+        ``SpatialCrop`` spanning the full frame.
+    """
+    return SpatialCrop(
+        axis0_start=0,
+        axis0_stop=spatial_shape[0],
+        axis1_start=0,
+        axis1_stop=spatial_shape[1],
+        original_shape=spatial_shape,
+        source="full_frame",
+    )

twopy/stimulus.py

@@ -0,0 +1,233 @@
+"""Helpers for interpreting converted stimulus data columns.
+
+Inputs: a loaded twopy ``RecordingData`` object.
+Outputs: small typed mappings from stable ``stimulus/data`` column names to the
+experiment-specific MATLAB code that wrote those columns.
+
+The stable HDF5 column name stays generic because different ``stimtype`` values
+can reuse the same slot for different meanings. These helpers make that
+per-``stimtype`` mapping explicit for scripts and analysis code.
+"""
+
+from dataclasses import dataclass
+from typing import cast
+
+from twopy.converted import RecordingData
+
+__all__ = [
+    "StimulusSpecificColumnMapping",
+    "map_stimulus_specific_column",
+    "stimulus_column_index",
+    "stimulus_epoch_names_by_number",
+]
+
+
+@dataclass(frozen=True)
+class StimulusSpecificColumnMapping:
+    """Meaning of one stable stimulus-specific column for one ``stimtype``.
+
+    Inputs: decoded metadata from ``stimulus/stimulus_specific_columns_json``.
+    Outputs: a script-friendly record containing the stable column name, the
+    ``stimtype``, the backed-up MATLAB function, and the source assignment.
+
+    ``specific_name`` is the most readable available label: an inline MATLAB
+    comment when present, otherwise the right-hand source expression.
+    """
+
+    stable_column_name: str
+    stimtype: str
+    specific_name: str
+    source_expression: str
+    source_comment: str | None
+    source_line: int
+    source_path: str
+    stimulus_function: str
+
+
+def map_stimulus_specific_column(
+    recording: RecordingData,
+    stable_column_name: str,
+    *,
+    stimtype: int | str | None = None,
+) -> tuple[StimulusSpecificColumnMapping, ...]:
+    """Map a stable stimulus column to experiment-specific meanings.
+
+    Args:
+        recording: Loaded converted recording.
+        stable_column_name: Stable name such as ``stimulus_specific_04``.
+        stimtype: Optional stimulus type. When omitted, mappings for all
+            ``stimtype`` values in the recording are returned.
+
+    Returns:
+        One mapping per matching ``stimtype``. An unused stimulus-specific slot
+        returns an empty tuple.
+
+    Raises:
+        ValueError: If ``stable_column_name`` is not a stimulus-specific column.
+        KeyError: If the requested ``stimtype`` is not present in the recording.
+
+    This function exists so analysis code can use the simple stable column
+    names for data access while still showing the exact experiment-specific
+    meaning from the backed-up MATLAB code.
+    """
+    if not stable_column_name.startswith("stimulus_specific_"):
+        msg = f"Expected stimulus_specific_* column; got {stable_column_name!r}"
+        raise ValueError(msg)
+
+    selected_stimtypes = _selected_stimtypes(recording, stimtype)
+    mappings: list[StimulusSpecificColumnMapping] = []
+    for stimtype_key in selected_stimtypes:
+        metadata = recording.stimulus_specific_columns[stimtype_key]
+        mappings.extend(
+            _mappings_from_metadata(
+                stable_column_name=stable_column_name,
+                stimtype=stimtype_key,
+                metadata=metadata,
+            ),
+        )
+    return tuple(mappings)
+
+
+def stimulus_column_index(recording: RecordingData, column_name: str) -> int:
+    """Return the index for one converted stimulus data column.
+
+    Args:
+        recording: Loaded converted recording.
+        column_name: Required column name from ``stimulus/data_column_names``.
+
+    Returns:
+        Integer column index.
+
+    Raises:
+        ValueError: If the column is not present.
+
+    Keeping this lookup in one helper avoids slightly different error handling
+    in timing, classification, and script-facing analysis code.
+    """
+    try:
+        return recording.stimulus_data_column_names.index(column_name)
+    except ValueError as error:
+        msg = f"stimulus/data is missing required column {column_name!r}"
+        raise ValueError(msg) from error
+
+
+def stimulus_epoch_names_by_number(recording: RecordingData) -> dict[int, str]:
+    """Map one-based stimulus epoch numbers to readable epoch names.
+
+    Args:
+        recording: Loaded converted recording with stimulus parameter metadata.
+
+    Returns:
+        Dictionary mapping epoch number to name.
+
+    Epoch numbers in ``stimulus/data`` are one-based because they come from the
+    stimulus computer. Missing names fall back to ``epoch_N`` at the call site.
+    """
+    names: dict[int, str] = {}
+    for index, parameters in enumerate(recording.stimulus_parameters, start=1):
+        epoch_name = parameters.get("epochName", f"epoch_{index}")
+        names[index] = str(epoch_name)
+    return names
+
+
+def _selected_stimtypes(
+    recording: RecordingData,
+    stimtype: int | str | None,
+) -> tuple[str, ...]:
+    """Choose which ``stimtype`` entries to inspect.
+
+    Args:
+        recording: Loaded converted recording.
+        stimtype: Optional requested stimulus type.
+
+    Returns:
+        Tuple of stimulus type keys present in ``recording``.
+    """
+    if stimtype is None:
+        return tuple(recording.stimulus_specific_columns)
+
+    stimtype_key = str(int(stimtype)) if isinstance(stimtype, int) else str(stimtype)
+    if stimtype_key not in recording.stimulus_specific_columns:
+        msg = f"stimtype {stimtype_key!r} is not present in this recording"
+        raise KeyError(msg)
+    return (stimtype_key,)
+
+
+def _mappings_from_metadata(
+    *,
+    stable_column_name: str,
+    stimtype: str,
+    metadata: dict[str, object],
+) -> tuple[StimulusSpecificColumnMapping, ...]:
+    """Build mappings from one decoded stimulus-function metadata block.
+
+    Args:
+        stable_column_name: Stable HDF5 column name to find.
+        stimtype: Stimulus type key for this metadata block.
+        metadata: Decoded JSON dictionary for one stimulus function.
+
+    Returns:
+        Matching column mappings.
+    """
+    columns = metadata.get("columns")
+    if not isinstance(columns, list):
+        msg = f"stimulus metadata for stimtype {stimtype!r} has no column list"
+        raise ValueError(msg)
+
+    mappings: list[StimulusSpecificColumnMapping] = []
+    for column in columns:
+        if not isinstance(column, dict):
+            msg = f"stimulus metadata for stimtype {stimtype!r} is malformed"
+            raise ValueError(msg)
+        column_metadata = cast(dict[str, object], column)
+        if column_metadata.get("column_name") != stable_column_name:
+            continue
+
+        source_comment = _optional_text(column_metadata.get("source_comment"))
+        source_expression = str(column_metadata["source_expression"])
+        source_line = _required_int(column_metadata["source_line"])
+        mappings.append(
+            StimulusSpecificColumnMapping(
+                stable_column_name=stable_column_name,
+                stimtype=stimtype,
+                specific_name=source_comment or source_expression,
+                source_expression=source_expression,
+                source_comment=source_comment,
+                source_line=source_line,
+                source_path=str(metadata["source_path"]),
+                stimulus_function=str(metadata["function"]),
+            ),
+        )
+    return tuple(mappings)
+
+
+def _optional_text(value: object) -> str | None:
+    """Return optional metadata text as ``str | None``.
+
+    Args:
+        value: Raw decoded JSON value.
+
+    Returns:
+        Text when present, otherwise ``None``.
+    """
+    if value is None:
+        return None
+    return str(value)
+
+
+def _required_int(value: object) -> int:
+    """Return a required JSON metadata integer.
+
+    Args:
+        value: Raw decoded JSON value.
+
+    Returns:
+        Integer value.
+
+    Raises:
+        ValueError: If the value cannot honestly be read as an integer.
+    """
+    if isinstance(value, bool) or not isinstance(value, int | str):
+        msg = f"Expected integer metadata value; got {value!r}"
+        raise ValueError(msg)
+    return int(value)

twopy/synchronization.py

@@ -0,0 +1,235 @@
+"""Detect photodiode events and map them to imaging frames.
+
+Inputs: converted photodiode signals from ``RecordingData``.
+Outputs: photodiode event segments and high-resolution events paired with
+frame-resolution imaging events.
+
+The stimulus and imaging computers have separate clocks. This module uses the
+photodiode signals as the shared evidence for alignment instead of relying on
+nominal frame rates.
+"""
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy.typing as npt
+
+from twopy.converted import RecordingData
+from twopy.photodiode import (
+    DEFAULT_PHOTODIODE_THRESHOLD_FRACTION,
+    PhotodiodeEvent,
+    PhotodiodePolarity,
+    detect_photodiode_event_segments,
+)
+
+__all__ = [
+    "AlignedPhotodiodeEvent",
+    "PhotodiodeAlignment",
+    "PhotodiodeEvent",
+    "PhotodiodeEventSet",
+    "PhotodiodePolarity",
+    "detect_photodiode_events",
+    "detect_recording_photodiode_events",
+    "pair_photodiode_events_to_imaging_frames",
+]
+
+PhotodiodeSignalName = Literal["high_res_pd", "imaging_res_pd"]
+
+
+@dataclass(frozen=True)
+class PhotodiodeEventSet:
+    """Detected events for one photodiode signal.
+
+    Inputs: signal name, thresholding options, and detected event segments.
+    Outputs: auditable event list plus the threshold that produced it.
+
+    Keeping the threshold with the events makes later trial alignment easier to
+    inspect and reproduce.
+    """
+
+    signal_name: PhotodiodeSignalName
+    events: tuple[PhotodiodeEvent, ...]
+    threshold: float
+    polarity: PhotodiodePolarity
+
+
+@dataclass(frozen=True)
+class AlignedPhotodiodeEvent:
+    """One high-resolution event paired with one imaging-frame event.
+
+    Inputs: detected high-resolution and imaging-resolution photodiode events.
+    Outputs: the imaging frame assigned to the high-resolution event.
+
+    The imaging frame is the first frame-resolution sample where the paired
+    photodiode event is detected. This is the conservative frame boundary used
+    before stimulus-specific event classification exists.
+    """
+
+    high_res_event: PhotodiodeEvent
+    imaging_res_event: PhotodiodeEvent
+    imaging_frame: int
+
+
+@dataclass(frozen=True)
+class PhotodiodeAlignment:
+    """Detected and paired photodiode events for one recording.
+
+    Inputs: converted high-resolution and imaging-resolution photodiode signals.
+    Outputs: event sets plus ordered high-res-to-frame pairings.
+
+    This is the first timing object response analysis should consume. It still
+    does not classify stimulus-specific flash patterns.
+    """
+
+    high_res: PhotodiodeEventSet
+    imaging_res: PhotodiodeEventSet
+    paired_events: tuple[AlignedPhotodiodeEvent, ...]
+
+
+def detect_photodiode_events(
+    signal: npt.ArrayLike,
+    *,
+    signal_name: PhotodiodeSignalName = "high_res_pd",
+    threshold: float | None = None,
+    threshold_fraction: float = DEFAULT_PHOTODIODE_THRESHOLD_FRACTION,
+    polarity: PhotodiodePolarity = "above",
+    minimum_width_samples: int = 1,
+    merge_gap_samples: int = 0,
+) -> PhotodiodeEventSet:
+    """Detect contiguous photodiode events in one signal.
+
+    Args:
+        signal: One-dimensional photodiode samples.
+        signal_name: Name of the converted photodiode signal being decoded.
+        threshold: Optional threshold. When omitted, twopy uses
+            ``min + threshold_fraction * range``.
+        threshold_fraction: Signal-range fraction used when ``threshold`` is
+            omitted. Defaults to the lab analysis convention, 0.3.
+        polarity: ``above`` detects samples greater than threshold; ``below``
+            detects samples less than threshold.
+        minimum_width_samples: Drop events shorter than this width.
+        merge_gap_samples: Merge neighboring events separated by this many
+            samples or fewer.
+
+    Returns:
+        Event set with the requested signal name.
+
+    Raises:
+        ValueError: If the signal is not one-dimensional or widths are invalid.
+
+    This function segments flashes. It does not classify stimulus-specific flash
+    patterns because that requires stimulus protocol rules.
+    """
+    events, resolved_threshold = detect_photodiode_event_segments(
+        signal=signal,
+        threshold=threshold,
+        threshold_fraction=threshold_fraction,
+        polarity=polarity,
+        minimum_width_samples=minimum_width_samples,
+        merge_gap_samples=merge_gap_samples,
+    )
+    return PhotodiodeEventSet(
+        signal_name=signal_name,
+        events=events,
+        threshold=resolved_threshold,
+        polarity=polarity,
+    )
+
+
+def detect_recording_photodiode_events(
+    recording: RecordingData,
+    *,
+    high_res_threshold: float | None = None,
+    imaging_res_threshold: float | None = None,
+    threshold_fraction: float = DEFAULT_PHOTODIODE_THRESHOLD_FRACTION,
+    polarity: PhotodiodePolarity = "above",
+    minimum_width_samples: int = 1,
+    merge_gap_samples: int = 0,
+) -> PhotodiodeAlignment:
+    """Detect and pair photodiode events for one converted recording.
+
+    Args:
+        recording: Loaded converted recording.
+        high_res_threshold: Optional threshold for ``high_res_pd``.
+        imaging_res_threshold: Optional threshold for ``imaging_res_pd``.
+        threshold_fraction: Signal-range fraction used for either signal when
+            its explicit threshold is omitted.
+        polarity: Which side of threshold marks a photodiode flash.
+        minimum_width_samples: Drop events shorter than this width in each
+            signal.
+        merge_gap_samples: Merge neighboring events separated by this many
+            samples or fewer in each signal.
+
+    Returns:
+        ``PhotodiodeAlignment`` with high-resolution events paired to imaging
+        frames by event order.
+
+    Pairing by order uses the photodiode evidence in both signals. It avoids
+    assuming the two computers share a frame rate or clock.
+    """
+    high_res = detect_photodiode_events(
+        recording.high_res_pd,
+        signal_name="high_res_pd",
+        threshold=high_res_threshold,
+        threshold_fraction=threshold_fraction,
+        polarity=polarity,
+        minimum_width_samples=minimum_width_samples,
+        merge_gap_samples=merge_gap_samples,
+    )
+    imaging_res = detect_photodiode_events(
+        recording.imaging_res_pd,
+        signal_name="imaging_res_pd",
+        threshold=imaging_res_threshold,
+        threshold_fraction=threshold_fraction,
+        polarity=polarity,
+        minimum_width_samples=minimum_width_samples,
+        merge_gap_samples=merge_gap_samples,
+    )
+    return PhotodiodeAlignment(
+        high_res=high_res,
+        imaging_res=imaging_res,
+        paired_events=pair_photodiode_events_to_imaging_frames(
+            high_res.events,
+            imaging_res.events,
+        ),
+    )
+
+
+def pair_photodiode_events_to_imaging_frames(
+    high_res_events: tuple[PhotodiodeEvent, ...],
+    imaging_res_events: tuple[PhotodiodeEvent, ...],
+) -> tuple[AlignedPhotodiodeEvent, ...]:
+    """Pair high-resolution photodiode events to imaging-frame events.
+
+    Args:
+        high_res_events: Events detected from ``high_res_pd``.
+        imaging_res_events: Events detected from ``imaging_res_pd``.
+
+    Returns:
+        Ordered event pairs with assigned imaging-frame indices.
+
+    Raises:
+        ValueError: If event counts differ.
+
+    Matching counts are required for this first implementation because silently
+    dropping or inventing event pairings would corrupt trial alignment.
+    """
+    if len(high_res_events) != len(imaging_res_events):
+        msg = (
+            "Cannot pair photodiode events with different counts: "
+            f"high_res={len(high_res_events)}, imaging_res={len(imaging_res_events)}"
+        )
+        raise ValueError(msg)
+
+    return tuple(
+        AlignedPhotodiodeEvent(
+            high_res_event=high_res_event,
+            imaging_res_event=imaging_res_event,
+            imaging_frame=imaging_res_event.start_sample,
+        )
+        for high_res_event, imaging_res_event in zip(
+            high_res_events,
+            imaging_res_events,
+            strict=True,
+        )
+    )