Source code for photon_mosaic.core.baserois

import numpy as np
import sparse
from numpy.typing import ArrayLike
from spikeinterface.core.base import BaseExtractor

from .baseimaging import BaseImaging


[docs] class BaseRois(BaseExtractor): """Base class for rois extractors.""" def __init__( self, sampling_frequency: float, shape: tuple | list | np.ndarray, roi_ids: ArrayLike, ): BaseExtractor.__init__(self, roi_ids) self._sampling_frequency = float(sampling_frequency) if len(shape) == 2: shape = (shape[0], shape[1], 1) self._shape = tuple(shape) self._num_planes = shape[2] self._roi_ids = np.array(roi_ids) self._imaging: BaseImaging | None = None # no concept of epochs for rois, since they are spatial only def __repr__(self): return self._repr_header() def _repr_header(self, display_name=True): """Generate text representation of the BaseRois object.""" if display_name and self.name != self.__class__.__name__: name = f"{self.name} ({self.__class__.__name__})" else: name = self.__class__.__name__ shape = self._shape # Format shape string based on whether data is volumetric or not shape_repr = f"{shape[0]} rows x {shape[1]} columns " return f"{name}:\n{self.get_num_rois()} ROIs - {shape_repr}" def _repr_html_(self, display_name=True): common_style = "margin-left: 10px;" border_style = "border:1px solid #ddd; padding:10px;" html_header = f"<div style='{border_style}'><strong>{self._repr_header(display_name)}</strong></div>" html_roi_ids = f"<details style='{common_style}'> <summary><strong>ROI IDs</strong></summary><ul>" html_roi_ids += f"{list(self.roi_ids)} </details>" html_extra = self._get_common_repr_html(common_style) html_repr = html_header + html_roi_ids + html_extra return html_repr @property def imaging(self): """Get the registered imaging. Returns ------- BaseImaging | None The registered imaging or None if not registered. """ return self._imaging @property def segmentation_info(self): if "__segmentation_info__" in self.get_annotation_keys(): return self.get_annotation("__segmentation_info__") else: return None
[docs] def set_segmentation_info(self, imaging_dict, params_dict, log_dict): segmentation_info = dict(imaging=imaging_dict, params=params_dict, log=log_dict) self.annotate(__segmentation_info__=segmentation_info)
[docs] def has_imaging(self) -> bool: """Check if an imaging is registered. Returns ------- bool True if an imaging is registered, False otherwise. """ return self._imaging is not None
@property def shape(self): """Get the shape of the ROIs (height, width, planes). Returns ------- tuple The shape of the ROIs as (height, width, planes). """ return self._shape @property def sampling_frequency(self): return self._sampling_frequency @property def roi_ids(self) -> np.ndarray: """Get the ROI IDs. Returns ------- np.ndarray The ROI IDs. """ return self._roi_ids
[docs] def get_num_planes(self) -> int: """Get the number of planes. Returns ------- int The number of planes. """ return self._num_planes
@property def num_planes(self) -> int: """Number of planes for ROI masks. This is a convenience alias for :meth:`get_num_planes`. """ return self.get_num_planes()
[docs] def get_num_rois(self) -> int: """Get the total number of ROIs. Returns ------- int The total number of ROIs. """ return len(self.roi_ids)
[docs] def get_roi_image_masks( self, roi_ids: list[int | str] | None = None ) -> np.ndarray | sparse.SparseArray: # pragma: no cover """Get the image mask for a specific ROI. The image mask can be binary or weighted and 2D (single plane) or 3D (multi-plane). Subclasses may return either a dense ``np.ndarray`` or a sparse `pydata/sparse <https://sparse.pydata.org/>`_ array (e.g. ``sparse.GCXS``). Each ROI typically occupies only a tiny fraction of the full imaging volume, so a sparse representation avoids the out-of-memory errors a dense array would cause once there are many ROIs over a large (e.g. volumetric) field of view -- see photon-mosaic#103. Callers that need actual pixel values (e.g. for plotting) should call ``.todense()`` explicitly rather than assume a dense array. Parameters ---------- roi_ids : list[int | str] | None The IDs of the ROIs. Returns ------- np.ndarray | sparse.SparseArray The image mask for the specified ROIs. """ raise NotImplementedError("This method should be implemented in subclasses.")
[docs] def get_roi_pixel_masks(self, roi_ids: list[int | str] | None = None) -> list[np.ndarray]: """Get the pixel coordinates for a specific ROI. Parameters ---------- roi_ids : list[int | str] | None The IDs of the ROIs. Returns ------- np.ndarray The pixel coordinates for the specified ROIs (y, x, [z,] weight). """ if roi_ids is None: roi_ids = self.roi_ids.tolist() # Get pixel masks from representations pixel_masks = [] image_masks = self.get_roi_image_masks(roi_ids) for img_mask in image_masks: if isinstance(img_mask, sparse.SparseArray): # .coords/.data give pixel coordinates and weights directly -- no need to # densify or scan for nonzero entries. coords has shape (ndim, nnz); unpacking # it gives one array per spatial dimension (y, x, [z]). coo = img_mask.tocoo() coords, weights = coo.coords, coo.data else: # Dense case (2D or 3D): np.nonzero returns one array per dimension. coords = np.nonzero(img_mask) weights = img_mask[coords] pixel_masks.append(np.column_stack([*coords, weights])) return pixel_masks
[docs] def select_rois(self, roi_ids: ArrayLike) -> "BaseRois": """Select a subset of ROIs. Parameters ---------- roi_ids : ArrayLike The IDs of the ROIs to select. Returns ------- SelectRois A new BaseRois object containing only the selected ROIs. """ from .selectrois import SelectRois return SelectRois(self, roi_ids)
[docs] def register_imaging(self, imaging: BaseImaging): """ Register an imaging to the ROIs. If the ROIs and imaging both contain time information, the imaging's time information will be used. Parameters ---------- imaging : BaseImaging Imaging with the same number of planes as the ROIs. Assigned to self._imaging. """ assert ( imaging.get_num_planes() == self.get_num_planes() ), "The imaging has a different number of planes than the ROIs!" assert np.isclose( self.sampling_frequency, imaging.sampling_frequency, atol=0.1 ), "The imaging has a different sampling frequency than the ROIs!" self._imaging = imaging
[docs] def save(self, format="binary", **save_kwargs): """ Save a `BaseRois` object to a specified format: * "binary" * "zarr" Parameters ---------- format : str, default: "binary" The format to save the ROIs in. Options are: - "binary": Saves the ROIs in binary format. - "zarr": Saves the ROIs in Zarr format. verbose : bool, default: False If True, prints additional information during the save process. **save_kwargs : dict Additional keyword arguments specific to the chosen format. All formats support job_kwargs for parallel processing (see `si.get_global_job_kwargs()` for default values). * "binary" format: - folder : str or Path The folder where the binary files will be saved. - overwrite : bool, default: False If True, existing files in the folder will be overwritten. * "zarr" format: - folder : str or Path The folder where the Zarr files will be saved. - overwrite: bool, default: False If True, the folder is removed if it already exists - storage_options: dict or None, default: None Storage options for zarr `store`. E.g., if "s3://" or "gcs://" they can provide authentication methods, etc. For cloud storage locations, this should not be None (in case of default values, use an empty dict) - compressor: numcodecs.Codec or None, default: None Compressor for the ROI mask datasets. If None, zarr's default is used - filters: list[numcodecs.Codec] or None, default: None Filters for the ROI mask datasets - chunks: tuple or None, default: None Chunk shape for the ROI mask datasets. If None, an automatic per-ROI chunking is applied Returns ------- BinaryFolderRois or ZarrRois The on-disk representation. """ if format == "binary": from .binaryrois import BinaryFolderRois folder = save_kwargs.pop("folder", None) if folder is None: raise ValueError("The 'folder' parameter must be specified for binary format.") return BinaryFolderRois.write_rois(self, folder, **save_kwargs) elif format == "zarr": from .zarrrois import ZarrRois folder = save_kwargs.pop("folder", None) if folder is None: raise ValueError("The 'folder' parameter must be specified for zarr format.") return ZarrRois.write_rois(self, folder, **save_kwargs) else: raise ValueError(f"format {format!r} not supported for BaseRois, use 'binary' or 'zarr'")