"""Imaging and ROI classes for in-memory numpy arrays.
Classes
-------
NumpyImaging
An Imaging specified by timeseries .npy file, sampling frequency, and channel names.
NumpyRois
A ROIs specified by image masks and traces .npy files.
"""
import numpy as np
import sparse
from numpy.typing import ArrayLike
from .baseimaging import BaseImaging, BaseImagingEpoch
from .baserois import BaseRois
[docs]
class NumpyImaging(BaseImaging):
"""An single- or multi-epoch Imaging specified by a numpy array or list of arrays"""
def __init__(
self,
imaging_series: ArrayLike | list[ArrayLike],
sampling_frequency: float,
time_vectors: ArrayLike | list[ArrayLike] | None = None,
seed=None,
):
"""Create a NumpyImagingExtractor from a numpy array or list of numpy arrays.
If a list of numpy arrays is provided, each array is treated as a separate epoch.
Individual epochs can have one or more planes. In the former case, the shape of each
array should be (num_frames, height, width). In the latter case, the shape should be
(num_frames, height, width, num_planes).
Parameters
----------
imaging_series: ArrayLike | list[ArrayLike]
Numpy array or list of numpy arrays representing the video.
sampling_frequency: float
Sampling frequency of the video in Hz.
time_vectors: ArrayLike | list[ArrayLike] | None, default: None
Optional time vector(s) for the video.
"""
if isinstance(imaging_series, np.ndarray):
videos = [imaging_series]
elif isinstance(imaging_series, list) and all(isinstance(ts, np.ndarray) for ts in imaging_series):
videos = imaging_series
else:
raise ValueError("'timeseries' must be a numpy array or a list of numpy arrays")
num_epochs = len(videos)
self._sampling_frequency = float(sampling_frequency)
# Check that all shapes and number of planes are consistent across epochs
shapes = []
for i, video in enumerate(videos):
if len(video.shape) not in [3, 4]:
raise ValueError(
"'timeseries' must be a 3D or 4D numpy array (num_frames, height, width, [num_planes])"
)
if len(video.shape) == 3:
videos[i] = video[:, :, :, np.newaxis] # Add a planes dimension
shapes.append(video.shape[1:])
if not all(shape == shapes[0] for shape in shapes):
raise ValueError("All epochs must have the same image shape (height, width, planes)")
# Check consistency of time vectors
if time_vectors is not None:
if num_epochs == 1 and isinstance(time_vectors, np.ndarray):
time_vectors = [time_vectors]
assert len(time_vectors) == num_epochs, "Number of time vectors must match number of epochs"
else:
time_vectors = [None] * num_epochs
BaseImaging.__init__(self, shape=shapes[0], sampling_frequency=sampling_frequency, dtype=videos[0].dtype)
for video, time_vector in zip(videos, time_vectors):
assert len(video.shape) == 4, "Video must be a 4D numpy array (num_frames, height, width, num_planes)"
self.add_epoch(
NumpyImagingEpoch(
video=video,
sampling_frequency=self._sampling_frequency,
time_vector=time_vector,
)
)
self._kwargs = {
"imaging_series": imaging_series,
"sampling_frequency": self._sampling_frequency,
"time_vectors": time_vectors,
"seed": seed,
}
[docs]
class NumpyImagingEpoch(BaseImagingEpoch):
"""A single epoch of an Imaging specified by a numpy array"""
def __init__(
self,
video: np.ndarray,
sampling_frequency: float,
time_vector: ArrayLike | None = None,
):
super().__init__(sampling_frequency=sampling_frequency, time_vector=time_vector)
self._video = video
[docs]
def get_series(
self,
start_frame: int | None = None,
end_frame: int | None = None,
plane_indices: slice | np.ndarray | None = None,
) -> np.ndarray:
"""Get the raw series, optionally for a subset of samples.
Parameters
----------
start_frame : int | None, default: None
start frame index, or zero if None
end_frame : int | None, default: None
end frame, or number of frames if None
plane_indices : slice | np.ndarray | None, default: None
List of plane indices to include, or all planes if None
Returns
-------
series: np.ndarray
The raw series for the specified frame range.
"""
start = start_frame if start_frame is not None else 0
end = end_frame if end_frame is not None else self._video.shape[0]
return self._video[start:end, :, :, plane_indices] if plane_indices is not None else self._video[start:end]
[docs]
def get_num_samples(self) -> int:
"""Returns the number of samples in this signal epoch
Returns
-------
int
Number of samples in the signal epoch
"""
return self._video.shape[0]
[docs]
class NumpyRois(BaseRois):
"""A ROIs object specified by numpy or sparse pydata arrays for masks and traces."""
def __init__(
self,
roi_image_masks: ArrayLike,
sampling_frequency: float,
roi_ids: ArrayLike | None = None,
):
"""Create a NumpyRois object from numpy or sparse pydata arrays.
Parameters
----------
roi_image_masks : ArrayLike
Numpy or sparse (e.g. `sparse.GCXS`) array representing the image masks for each ROI.
Accepted dimensions are: (num_rois x height x width) for single-plane and
(num_rois x height x width x num_planes) for multi-plane.
sampling_frequency : float
Sampling frequency of the ROIs in Hz.
roi_ids : ArrayLike | None, default: None
Optional array of ROI IDs. If None, IDs will be assigned as integers from 0 to num_rois-1.
"""
num_rois = roi_image_masks.shape[0]
# `.shape[1:]` avoids `roi_image_masks[0].shape`, which triggers a multi-second numba
# JIT compile on sparse arrays and crashes outright on an empty (0-ROI) array.
mask_shape = roi_image_masks.shape[1:]
if len(mask_shape) not in [2, 3]:
raise ValueError("Each ROI mask must be a 2D (height x width) or 3D (height x width x planes) array")
if roi_ids is None:
roi_ids = np.arange(num_rois)
BaseRois.__init__(
self,
sampling_frequency=sampling_frequency,
shape=mask_shape,
roi_ids=roi_ids,
)
self._roi_image_masks = roi_image_masks
self._kwargs = {
"roi_image_masks": roi_image_masks,
"sampling_frequency": sampling_frequency,
"roi_ids": roi_ids,
}
if isinstance(roi_image_masks, sparse.SparseArray):
# sparse arrays aren't handled by spikeinterface's JSON encoder; fall back to pickle.
self._serializability["json"] = False
[docs]
def get_roi_image_masks(self, roi_ids: list[int | str] | None = None) -> np.ndarray | sparse.SparseArray:
"""Get the image masks for specific ROIs.
Parameters
----------
roi_ids : list[int | str] | None
The IDs of the ROIs.
Returns
-------
np.ndarray | sparse.SparseArray
The image masks for the specified ROIs.
"""
if roi_ids is None:
return self._roi_image_masks
else:
roi_indices = self.ids_to_indices(roi_ids)
return self._roi_image_masks[roi_indices]