Source code for photon_mosaic.core.imaging_ops

"""Operations that derive one imaging object from another.

Every public callable here takes imaging object(s) and hands back a new lazy
proxy: selecting or subdividing epochs, cutting out a frame range, or joining
objects along the plane axis. Nothing copies pixels — the proxies pull from
their parents on read.
"""

from typing import Sequence

import numpy as np
from numpy.typing import DTypeLike

from .baseimaging import BaseImaging, BaseImagingEpoch


def _normalize_epoch_indices(epoch_indices: int | list[int], num_epochs: int) -> list[int]:
    """Normalize and validate epoch indices requested by the user."""
    if isinstance(epoch_indices, int):
        normalized_epoch_indices = [epoch_indices]
    elif isinstance(epoch_indices, list):
        normalized_epoch_indices = epoch_indices
    else:
        raise TypeError("epoch_indices must be an int or a list of ints")

    if len(normalized_epoch_indices) == 0:
        raise ValueError("epoch_indices must contain at least one index")

    for epoch_index in normalized_epoch_indices:
        # isinstance(True, int) returns True, so we need the second check here
        if not isinstance(epoch_index, int) or isinstance(epoch_index, bool):
            raise TypeError("All epoch indices must be ints")
        if not 0 <= epoch_index < num_epochs:
            raise IndexError(f"Epoch index {epoch_index} out of range for imaging with {num_epochs} epochs")

    return normalized_epoch_indices


[docs] class SelectEpochImaging(BaseImaging): """Proxy imaging object exposing only selected epochs from a parent imaging.""" def __init__(self, imaging: BaseImaging, epoch_indices: int | list[int]): normalized_epoch_indices = _normalize_epoch_indices(epoch_indices, imaging.get_num_epochs()) BaseImaging.__init__( self, sampling_frequency=imaging.sampling_frequency, shape=imaging.shape, dtype=imaging.get_dtype(), plane_ids=imaging.plane_ids.copy(), ) imaging.copy_metadata(self) self._selected_epoch_indices = {} for i, epoch_index in enumerate(normalized_epoch_indices): imaging_epoch = imaging.epochs[epoch_index] self.add_epoch(imaging_epoch) self._selected_epoch_indices[i] = epoch_index self._parent = imaging self._kwargs = { "imaging": imaging, "epoch_indices": normalized_epoch_indices, }
[docs] def get_series( self, start_frame: int | None = None, end_frame: int | None = None, plane_ids: list | np.ndarray | None = None, epoch_index: int | None = None, ) -> np.ndarray: # parent may want to do further operations to the series before returning # so we explicitly delegate to them rather than relying on BaseImaging. # We also remap selected epoch indices relative to the parent if epoch_index is None: selected_epoch_index = self._selected_epoch_indices[0] else: selected_epoch_index = self._selected_epoch_indices[epoch_index] return self._parent.get_series( start_frame=start_frame, end_frame=end_frame, plane_ids=plane_ids, epoch_index=selected_epoch_index, )
[docs] def split_epochs(imaging: BaseImaging, epoch_indices: int | list[int]) -> SelectEpochImaging: """Return a proxy imaging object with only the requested epochs.""" return SelectEpochImaging(imaging=imaging, epoch_indices=epoch_indices)
[docs] def split_imaging_by_epochs(imaging: BaseImaging) -> list[SelectEpochImaging]: """Return a list of proxy imaging objects, each containing a single epoch.""" return [SelectEpochImaging(imaging=imaging, epoch_indices=i) for i in range(imaging.get_num_epochs())]
class _FrameRangeEpoch(BaseImagingEpoch): """Lazy view over a contiguous frame range of a parent epoch.""" def __init__(self, parent_epoch: BaseImagingEpoch, start_frame: int, end_frame: int): t_start = parent_epoch._t_start if getattr(parent_epoch, "_t_start", None) is not None else 0.0 sampling_frequency = parent_epoch._sampling_frequency BaseImagingEpoch.__init__( # type: ignore[call-arg] self, sampling_frequency=sampling_frequency, t_start=t_start + start_frame / sampling_frequency, ) self._parent_epoch = parent_epoch self._start = int(start_frame) self._end = int(end_frame) def get_num_samples(self) -> int: return self._end - self._start def get_series(self, start_frame, end_frame, plane_indices=None): return self._parent_epoch.get_series( self._start + start_frame, self._start + end_frame, plane_indices, )
[docs] class SplitEpochAtFramesImaging(BaseImaging): """Imaging proxy that subdivides one epoch of a parent into several sub-epochs. The frame boundaries are interpreted in the same way as ``np.split``: the boundaries split the parent epoch into ``len(boundaries) + 1`` contiguous pieces, each exposed as its own epoch on the returned object. Pixels are pulled lazily from the parent — no data is copied. """ def __init__(self, imaging: BaseImaging, epoch_index: int, frame_boundaries: Sequence[int]): num_epochs = imaging.get_num_epochs() if not isinstance(epoch_index, int) or isinstance(epoch_index, bool): raise TypeError("epoch_index must be an int") if not 0 <= epoch_index < num_epochs: raise IndexError(f"Epoch index {epoch_index} out of range for imaging with {num_epochs} epochs") parent_epoch = imaging.epochs[epoch_index] n_samples = parent_epoch.get_num_samples() boundaries = list(map(int, frame_boundaries)) if any(b <= 0 or b >= n_samples for b in boundaries): raise ValueError(f"frame_boundaries must be strictly between 0 and {n_samples}; got {boundaries}") if any(boundaries[i] >= boundaries[i + 1] for i in range(len(boundaries) - 1)): raise ValueError(f"frame_boundaries must be strictly increasing; got {boundaries}") BaseImaging.__init__( self, sampling_frequency=imaging.sampling_frequency, shape=imaging.shape, dtype=imaging.get_dtype(), plane_ids=imaging.plane_ids.copy(), ) imaging.copy_metadata(self) edges = [0, *boundaries, n_samples] for lo, hi in zip(edges[:-1], edges[1:]): self.add_epoch(_FrameRangeEpoch(parent_epoch, lo, hi)) self._parent = imaging self._kwargs = { "imaging": imaging, "epoch_index": epoch_index, "frame_boundaries": np.asarray(boundaries, dtype=int).tolist(), }
[docs] def split_epoch_at_frames( imaging: BaseImaging, epoch_index: int, frame_boundaries: Sequence[int], ) -> SplitEpochAtFramesImaging: """Split one epoch of ``imaging`` into contiguous sub-epochs at the given frame boundaries. Convenience wrapper for :class:`SplitEpochAtFramesImaging`. Useful when an extractor exposes recorded files as a single concatenated epoch (e.g. suite2p's per-plane ``data.bin`` plus ``ops['frames_per_file']``) and you want each underlying file as its own epoch. """ return SplitEpochAtFramesImaging(imaging=imaging, epoch_index=epoch_index, frame_boundaries=frame_boundaries)
[docs] class FrameSliceImaging(BaseImaging): """Imaging proxy exposing one contiguous frame range of a parent epoch. The imaging counterpart of SpikeInterface's ``FrameSliceRecording``: the way to cut a short stub out of a long video, whether for a test fixture, a quick look, or to hand something small to code that would choke on the whole recording. Pixels are pulled lazily from the parent. The result has exactly one epoch. ``t_start`` stays on the parent's timeline rather than being re-referenced to zero, so the stub keeps its place in the original recording. Parameters ---------- parent_imaging : BaseImaging The imaging object to slice. start_frame : int | None, default: None First included frame, or 0 if None. end_frame : int | None, default: None End frame, excluded as in ordinary python slicing; the parent epoch's frame count if None. epoch_index : int | None, default: None Which epoch of the parent to slice. If None and the parent has a single epoch it defaults to that one; a multi-epoch parent must name its epoch, as it must for :meth:`BaseImaging.get_series`. SpikeInterface refuses a multi-segment parent outright; naming the epoch keeps that capability without letting an unnamed one be picked silently (see issue #129). """ def __init__( self, parent_imaging: BaseImaging, start_frame: int | None = None, end_frame: int | None = None, epoch_index: int | None = None, ): num_epochs = parent_imaging.get_num_epochs() if epoch_index is None: if num_epochs > 1: raise ValueError("epoch_index must be provided for multi-epoch imaging data.") epoch_index = 0 if not isinstance(epoch_index, int) or isinstance(epoch_index, bool): raise TypeError("epoch_index must be an int") if not 0 <= epoch_index < num_epochs: raise IndexError(f"Epoch index {epoch_index} out of range for imaging with {num_epochs} epochs") parent_epoch = parent_imaging.epochs[epoch_index] parent_size = parent_epoch.get_num_samples() start_frame = 0 if start_frame is None else int(start_frame) end_frame = parent_size if end_frame is None else int(end_frame) if not 0 <= start_frame < parent_size: raise ValueError(f"start_frame must be within [0, {parent_size}); got {start_frame}") if not 0 < end_frame <= parent_size: raise ValueError(f"end_frame must be within (0, {parent_size}]; got {end_frame}") if end_frame <= start_frame: raise ValueError(f"start_frame must be smaller than end_frame; got {start_frame} and {end_frame}") BaseImaging.__init__( self, sampling_frequency=parent_imaging.sampling_frequency, shape=parent_imaging.shape, dtype=parent_imaging.get_dtype(), plane_ids=parent_imaging.plane_ids.copy(), ) parent_imaging.copy_metadata(self) self.add_epoch(_FrameRangeEpoch(parent_epoch, start_frame, end_frame)) self._parent = parent_imaging self._kwargs = { "parent_imaging": parent_imaging, "start_frame": start_frame, "end_frame": end_frame, "epoch_index": epoch_index, }
[docs] def frame_slice( parent_imaging: BaseImaging, start_frame: int | None = None, end_frame: int | None = None, epoch_index: int | None = None, ) -> FrameSliceImaging: """Return a single-epoch proxy over ``[start_frame, end_frame)`` of one parent epoch. Convenience wrapper for :class:`FrameSliceImaging`. """ return FrameSliceImaging( parent_imaging=parent_imaging, start_frame=start_frame, end_frame=end_frame, epoch_index=epoch_index, )
class _ConcatenatedEpoch(BaseImagingEpoch): """Lazy epoch joining several parent epochs end to end along time.""" def __init__(self, parent_epochs: Sequence[BaseImagingEpoch], shape: tuple, dtype: DTypeLike): first = parent_epochs[0] BaseImagingEpoch.__init__( # type: ignore[call-arg] self, sampling_frequency=first._sampling_frequency, t_start=getattr(first, "_t_start", None), ) self._parent_epochs = list(parent_epochs) self._sizes = [e.get_num_samples() for e in self._parent_epochs] self._offsets = np.cumsum([0, *self._sizes]).tolist() self._shape = shape self._dtype = dtype def get_num_samples(self) -> int: return self._offsets[-1] def get_series(self, start_frame, end_frame, plane_indices=None): assert start_frame < end_frame, f"start_frame {start_frame} must be < end_frame {end_frame}" # _offsets is sorted, so bisect to the parent epochs overlapping the request. first = np.searchsorted(self._offsets, start_frame, side="right") - 1 last = np.searchsorted(self._offsets, end_frame, side="left") if last - first == 1: # request inside one epoch: no copy offset = self._offsets[first] return self._parent_epochs[first].get_series(start_frame - offset, end_frame - offset, plane_indices) # One probe frame gives the spatial shape and dtype shared by all epochs. out = np.empty((end_frame - start_frame, *self._shape), dtype=self._dtype) pos = 0 for i in range(first, last): # Requested frames clipped to parent epoch i, in that epoch's own numbering. lo = max(start_frame - self._offsets[i], 0) hi = min(end_frame - self._offsets[i], self._sizes[i]) out[pos : pos + hi - lo] = self._parent_epochs[i].get_series(lo, hi, plane_indices) pos += hi - lo return out
[docs] class ConcatenateImaging(BaseImaging): """Imaging proxy joining all epochs of one or several input imaging objects into one epoch along time. Epoch data is accessed lazily in input order; ``t_start`` is the first epoch's from the first input. """ def __init__(self, imagings: list[BaseImaging] | BaseImaging): if isinstance(imagings, BaseImaging): imagings = [imagings] elif not isinstance(imagings, list): raise TypeError("imagings must be a BaseImaging or a list of BaseImaging objects") if not imagings: raise ValueError("concatenate_epochs requires at least one imaging object") for input_index, imaging in enumerate(imagings): if not isinstance(imaging, BaseImaging): raise TypeError(f"Input {input_index} is not a BaseImaging (got {type(imaging).__name__})") imagings = imagings.copy() # shallow copy, in case modified after call reference = imagings[0] for input_index, imaging in enumerate(imagings[1:], start=1): if tuple(imaging.shape) != tuple(reference.shape): raise ValueError( f"Input {input_index} shape {imaging.shape} disagrees with input 0 ({reference.shape})" ) if imaging.sampling_frequency != reference.sampling_frequency: raise ValueError( f"Input {input_index} sampling frequency {imaging.sampling_frequency} disagrees with input 0 " f"({reference.sampling_frequency})" ) if np.dtype(imaging.get_dtype()) != np.dtype(reference.get_dtype()): raise ValueError( f"Input {input_index} dtype {imaging.get_dtype()} disagrees with input 0 ({reference.get_dtype()})" ) shape = reference.shape dtype = reference.get_dtype() BaseImaging.__init__( self, sampling_frequency=reference.sampling_frequency, shape=shape, dtype=dtype, plane_ids=reference.plane_ids.copy(), ) reference.copy_metadata(self) parent_epochs = [epoch for imaging in imagings for epoch in imaging.epochs] self.add_epoch(_ConcatenatedEpoch(parent_epochs, shape=shape, dtype=dtype)) self._kwargs = {"imagings": imagings}
[docs] def concatenate_epochs(imagings: list[BaseImaging] | BaseImaging) -> ConcatenateImaging: """Return a single-epoch proxy joining all input epochs in order.""" return ConcatenateImaging(imagings=imagings)
[docs] class AppendImaging(BaseImaging): """Imaging proxy whose epochs are those of each input, in list order. Inputs must share shape, sampling frequency and dtype. Nothing is copied. """ def __init__(self, imagings: list[BaseImaging]): if not isinstance(imagings, list): raise TypeError("imagings must be a list of BaseImaging objects") if len(imagings) < 2: raise ValueError("append_imaging requires at least two imaging objects") for input_index, imaging in enumerate(imagings): if not isinstance(imaging, BaseImaging): raise TypeError(f"Input {input_index} is not a BaseImaging (got {type(imaging).__name__})") imagings = imagings.copy() # shallow copy, in case modified after call reference = imagings[0] for input_index, imaging in enumerate(imagings[1:], start=1): if tuple(imaging.shape) != tuple(reference.shape): raise ValueError( f"Input {input_index} shape {imaging.shape} disagrees with input 0 ({reference.shape})" ) if imaging.sampling_frequency != reference.sampling_frequency: raise ValueError( f"Input {input_index} sampling frequency {imaging.sampling_frequency} disagrees with input 0 " f"({reference.sampling_frequency})" ) if np.dtype(imaging.get_dtype()) != np.dtype(reference.get_dtype()): raise ValueError( f"Input {input_index} dtype {imaging.get_dtype()} disagrees with input 0 ({reference.get_dtype()})" ) BaseImaging.__init__( self, sampling_frequency=reference.sampling_frequency, shape=reference.shape, dtype=reference.get_dtype(), plane_ids=reference.plane_ids.copy(), ) reference.copy_metadata(self) for imaging in imagings: for epoch in imaging.epochs: self.add_epoch(epoch) self._kwargs = {"imagings": imagings}
[docs] def append_imaging(imagings: list[BaseImaging]) -> AppendImaging: """Return a proxy with the epochs of each imaging object in list order.""" return AppendImaging(imagings=imagings)
class _StackedPlanesEpoch(BaseImagingEpoch): """Lazy epoch whose planes are gathered from several parent epochs. Each parent epoch contributes a contiguous block of planes; on read the blocks are joined along the plane axis into ``(num_samples, H, W, sum_of_planes)``. Only the parents holding requested planes are read. """ def __init__( self, parent_epochs: Sequence[BaseImagingEpoch], height: int, width: int, planes_per_parent: Sequence[int], dtype: np.dtype, ): first = parent_epochs[0] BaseImagingEpoch.__init__( # type: ignore[call-arg] self, sampling_frequency=first._sampling_frequency, t_start=getattr(first, "t_start", None), ) self._parent_epochs = list(parent_epochs) self._height = int(height) self._width = int(width) self._dtype = np.dtype(dtype) self._planes_per_parent = [int(n) for n in planes_per_parent] self._num_planes = int(sum(self._planes_per_parent)) # Global index of each parent's first plane, so a requested global plane # index resolves to (parent, local index) without reading anything. self._parent_offsets = np.cumsum([0, *self._planes_per_parent[:-1]]).tolist() def get_num_samples(self) -> int: return self._parent_epochs[0].get_num_samples() def get_series( self, start_frame: int, end_frame: int, plane_indices: slice | np.ndarray | None = None, ) -> np.ndarray: requested = self._resolve_plane_indices(plane_indices) if not requested: return np.empty((end_frame - start_frame, self._height, self._width, 0), dtype=self._dtype) # Group the requested planes by the parent holding them, so each parent # is read at most once and parents holding none are not read at all. local_by_parent: dict[int, list[int]] = {} for global_index in requested: parent = int(np.searchsorted(self._parent_offsets, global_index, side="right") - 1) local_by_parent.setdefault(parent, []).append(global_index - self._parent_offsets[parent]) by_parent = sorted(local_by_parent.items()) parts = [ self._parent_epochs[parent].get_series(start_frame, end_frame, self._parent_selection(parent, local)) for parent, local in by_parent ] stacked = np.concatenate(parts, axis=-1) if len(parts) > 1 else parts[0] # ``stacked`` is in parent order; restore the order the caller asked for. gathered = [self._parent_offsets[parent] + local for parent, locals_ in by_parent for local in locals_] if gathered == requested: return stacked position = {global_index: i for i, global_index in enumerate(gathered)} return stacked[..., [position[global_index] for global_index in requested]] def _parent_selection(self, parent: int, local: list[int]) -> slice | np.ndarray: """Pick how to ask ``parent`` for ``local``. A parent asked for all of its planes in order gets a slice, so it can hand back a view instead of an advanced-indexing copy — the whole-volume read is the common case and should stay as cheap as it was. """ if local == list(range(self._planes_per_parent[parent])): return slice(None) return np.asarray(local, dtype=int) def _resolve_plane_indices(self, plane_indices: slice | np.ndarray | None) -> list[int]: """Normalise ``plane_indices`` to an explicit list of global plane indices. Negative indices count from the last plane, as they do on the sibling epochs that index a numpy array directly. """ if plane_indices is None: return list(range(self._num_planes)) if isinstance(plane_indices, slice): return list(range(*plane_indices.indices(self._num_planes))) candidates = np.atleast_1d(plane_indices) if candidates.dtype == bool: # A boolean mask selects planes, it does not name them by index. candidates = np.flatnonzero(candidates) indices = [] for raw in candidates: index = int(raw) if index < 0: index += self._num_planes if not 0 <= index < self._num_planes: raise IndexError(f"Plane index {int(raw)} out of range for {self._num_planes} planes") indices.append(index) return indices
[docs] class StackPlanesImaging(BaseImaging): """Imaging proxy that stacks several imaging objects along the plane axis. All inputs must share the same epoch structure (number of epochs and the per-epoch frame counts), the same ``(height, width)``, sampling frequency and dtype. The resulting object has ``sum(num_planes)`` planes and pulls pixels lazily from the inputs — no data is copied. Parameters ---------- imagings : sequence of BaseImaging Two or more imaging objects covering the same field of view at the same timestamps, each providing one or more planes. """ def __init__(self, imagings: Sequence[BaseImaging]): imagings = list(imagings) if len(imagings) < 2: raise ValueError("stack_planes requires at least two imaging objects") for i, im in enumerate(imagings): if not isinstance(im, BaseImaging): raise TypeError(f"Input {i} is not a BaseImaging (got {type(im).__name__})") ref = imagings[0] num_epochs = ref.get_num_epochs() height, width = int(ref.shape[0]), int(ref.shape[1]) fs = ref.sampling_frequency dtype = ref.get_dtype() ref_samples = [ref.epochs[e].get_num_samples() for e in range(num_epochs)] for i, im in enumerate(imagings[1:], start=1): if im.get_num_epochs() != num_epochs: raise ValueError(f"Input {i} has {im.get_num_epochs()} epochs but input 0 has {num_epochs}") if (int(im.shape[0]), int(im.shape[1])) != (height, width): raise ValueError( f"Input {i} has frame shape ({im.shape[0]}, {im.shape[1]}) " f"but input 0 has ({height}, {width})" ) if im.sampling_frequency != fs: raise ValueError(f"Input {i} sampling frequency {im.sampling_frequency} disagrees with input 0 ({fs})") if np.dtype(im.get_dtype()) != np.dtype(dtype): raise ValueError(f"Input {i} dtype {im.get_dtype()} disagrees with input 0 ({dtype})") samples = [im.epochs[e].get_num_samples() for e in range(num_epochs)] if samples != ref_samples: raise ValueError(f"Input {i} per-epoch frame counts {samples} disagree with input 0 ({ref_samples})") planes_per_parent = [int(im.num_planes) for im in imagings] total_planes = sum(planes_per_parent) BaseImaging.__init__(self, sampling_frequency=fs, shape=(height, width, total_planes), dtype=dtype) for epoch_index in range(num_epochs): parent_epochs = [im.epochs[epoch_index] for im in imagings] self.add_epoch(_StackedPlanesEpoch(parent_epochs, height, width, planes_per_parent, dtype)) self._parents = imagings self._kwargs = {"imagings": imagings} self.name = f"Stacked planes ({total_planes} planes from {len(imagings)} objects)"
[docs] def stack_planes(*imagings: BaseImaging) -> StackPlanesImaging: """Stack imaging objects along the plane axis into one multi-plane volume. Accepts the objects either as separate arguments (``stack_planes(a, b)``) or as a single sequence (``stack_planes([a, b])``). Parameters ---------- *imagings : BaseImaging Two or more imaging objects of the same FOV / timestamps; see :class:`StackPlanesImaging`. Returns ------- StackPlanesImaging A lazy multi-plane view over the inputs. """ if len(imagings) == 1 and isinstance(imagings[0], (list, tuple)): items: Sequence[BaseImaging] = imagings[0] else: items = imagings return StackPlanesImaging(items)