Source code for photon_mosaic.segmentation.suite2p_segmentation

import importlib.metadata
import logging
import time
from typing import Annotated, Any, Sequence

import numpy as np
from numpy.typing import NDArray
from pydantic import Field, field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict

from photon_mosaic.core import BaseImaging
from photon_mosaic.extractors.suite2prois import Suite2pRois

from .basesegmentation import BaseSegmentation, register_segmentation_class


[docs] class Suite2pSegmentationSettings(BaseSettings): """Settings for Suite2P ROI detection.""" diameter: list[Annotated[float, Field(ge=1)]] = Field( default=[12.0, 12.0], description=( "Expected cell diameter in pixels [y, x], each at least 1. Cellpose rescales the image by " "30 / diameter, so [30, 30] runs Cellpose-SAM at its native scale, as when no diameter is " "given; use the same value for y and x. Sourcery uses it to set its smoothing and neuropil scales." ), ) tau: float = Field( default=1.0, description="Timescale of the indicator (seconds). GCaMP6s ~1.5, GCaMP6f ~0.7.", ) fs: float = Field( default=30.0, description="Sampling frequency of the imaging data in Hz.", ) preclassify: float = Field( default=0.0, description="Apply classifier before refinement with probability threshold. 0 disables.", ) device: str = Field( default="cpu", description="Torch device for detection: 'cpu', 'cuda', or 'mps'.", ) algorithm: str = Field( default="sparsery", description=( "ROI detection algorithm. Options: 'sparsery' (suite2p sparse mode), " "'sourcery' (suite2p dense mode), 'cellpose' (CellPose)." ), ) denoise: bool = Field( default=False, description="Apply denoising to binned movie before cell detection.", ) threshold_scaling: float = Field( default=1.0, description="Scale the automatically determined detection threshold.", ) max_overlap: float = Field( default=0.75, description="ROIs with more overlap than this are removed during triage.", ) soma_crop: bool = Field( default=True, description="Crop dendrites for cell classification stats like compactness.", ) allow_overlap: bool = Field( default=False, description="If False, overlapping pixels are discarded; if True, added to both ROIs.", ) nbins: int = Field( default=5000, description="Number of bins for the activity histogram.", ) highpass_time: int = Field( default=100, description="Window size (frames) for temporal high-pass filter before detection.", ) model_config = SettingsConfigDict( env_file=".env", env_prefix="SUITE2P_SEGMENTATION_", case_sensitive=False, extra="ignore" )
[docs] @field_validator("algorithm") @classmethod def lowercase_algorithm(cls, v: str) -> str: return v.lower()
[docs] def merged_with_suite2p_defaults(self) -> dict[str, Any]: """Return suite2p's installed detection defaults overlaid with our overrides. Used to source per-algorithm sub-dicts (``sparsery_settings``, ``sourcery_settings``, ``cellpose_settings``) without hard-coding them and to forward ``denoise``/``highpass_time`` etc. to the inner calls. """ from suite2p import default_settings # noqa: PLC0415 base: dict[str, Any] = dict(default_settings()["detection"]) base.update( { "algorithm": self.algorithm, "denoise": self.denoise, "threshold_scaling": self.threshold_scaling, "max_overlap": self.max_overlap, "soma_crop": self.soma_crop, "allow_overlap": self.allow_overlap, "nbins": self.nbins, "highpass_time": self.highpass_time, } ) return base
def _read_plane_range( imaging: BaseImaging, epoch_offsets: NDArray[np.int64], start: int, stop: int, ) -> NDArray: """Read frames ``[start, stop)`` of one plane, stitched across epochs. Pulls only the epoch chunks that overlap the requested global frame range via :func:`BaseImagingEpoch.get_series`. Returns whatever dtype the underlying epochs produce (no upcast). """ chunks: list[NDArray] = [] for i in range(imaging.get_num_epochs()): ep_lo = int(epoch_offsets[i]) ep_hi = int(epoch_offsets[i + 1]) if ep_hi <= start or ep_lo >= stop: continue local_start = max(0, start - ep_lo) local_end = min(ep_hi - ep_lo, stop - ep_lo) frames = imaging.get_series(start_frame=local_start, end_frame=local_end, epoch_index=i) chunks.append(frames[:, :, :, 0]) if len(chunks) == 1: return chunks[0] return np.concatenate(chunks, axis=0) def _stream_bin_movie( imaging: BaseImaging, *, bin_size: int, yrange: Sequence[int], xrange: Sequence[int], badframes: NDArray[np.bool_] | None, nbins: int, ) -> NDArray[np.float32]: """Stream-bin one plane across all epochs of ``imaging``. Mirrors :func:`suite2p.detection.detect.bin_movie` but pulls each batch via :func:`BaseImagingEpoch.get_series` instead of holding the full movie in memory. The only large array kept is the binned ``mov``. """ n_epochs = imaging.get_num_epochs() sizes = [int(imaging.get_num_frames(epoch_index=i)) for i in range(n_epochs)] epoch_offsets = np.cumsum([0, *sizes]).astype(np.int64) n_frames = int(epoch_offsets[-1]) good_frames = ~badframes if badframes is not None else np.ones(n_frames, dtype=bool) n_good = int(good_frames.sum()) if n_good == 0: raise ValueError("no good frames available for binning") batch_size = min(n_good, 500) Lyc = int(yrange[1] - yrange[0]) Lxc = int(xrange[1] - xrange[0]) num_binned_frames = min(nbins, n_frames // bin_size) mov = np.zeros((num_binned_frames, Lyc, Lxc), np.float32) curr = 0 tstarts = np.arange(0, n_frames, batch_size) bins_per_batch = max(1, batch_size // bin_size) n_batches = min(nbins // bins_per_batch, len(tstarts)) if n_batches < 1: n_batches = min(1, len(tstarts)) tstarts = tstarts[np.linspace(0, len(tstarts) - 1, n_batches, dtype=int)] for raw_tstart in tstarts: tstart = int(raw_tstart) tend = min(tstart + batch_size, n_frames) data = _read_plane_range(imaging, epoch_offsets, tstart, tend) good = good_frames[tstart:tend] if good.mean() > 0.5: data = data[good] data = data[:, slice(*yrange), slice(*xrange)] if data.shape[0] > bin_size: n_d = data.shape[0] data = data[: (n_d // bin_size) * bin_size] data = data.reshape(-1, bin_size, Lyc, Lxc).astype(np.float32).mean(axis=1) else: data = data.mean(axis=0).astype(np.float32)[np.newaxis, :, :] if mov.shape[0] > curr: nb = data.shape[0] mov[curr : curr + nb] = data curr += nb return mov[:curr] def _detect_rois_from_mov( mov: NDArray[np.float32], *, cfg: Suite2pSegmentationSettings, Ly: int, Lx: int, yrange: Sequence[int], xrange: Sequence[int], ) -> list[dict[str, Any]]: """Run the configured suite2p detection algorithm on a binned movie. Replaces :func:`suite2p.detection.detect.detection_wrapper` with a direct dispatch onto the algorithm-specific entry points (``sparsedetect.sparsery``, ``sourcery.sourcery``, or ``anatomical.select_rois``) so each backend's settings are wired explicitly. Returns the post-:func:`roi_stats` stat list with pixel coordinates already shifted back to the full image. """ import torch # noqa: PLC0415 from suite2p.detection import anatomical, sourcery, sparsedetect, utils # noqa: PLC0415 from suite2p.detection.stats import roi_stats # noqa: PLC0415 s = cfg.merged_with_suite2p_defaults() device = torch.device(cfg.device) diameter = np.array(cfg.diameter, dtype=float) if s.get("denoise", False): from suite2p.detection.denoise import pca_denoise # noqa: PLC0415 mov = pca_denoise(mov, block_size=s["block_size"], n_comps_frac=0.5) meanImg = mov.mean(axis=0) mov = utils.temporal_high_pass_filter(mov=mov, width=s["highpass_time"]) max_proj = mov.max(axis=0) use_cellpose = cfg.algorithm == "cellpose" and anatomical.CELLPOSE_INSTALLED if cfg.algorithm == "cellpose" and not anatomical.CELLPOSE_INSTALLED: logging.warning( "cellpose requested but not installed (%s); falling back to sparsery", anatomical.cellpose_error, ) if use_cellpose: _, raw_stat = anatomical.select_rois( meanImg, max_proj, settings=s["cellpose_settings"], diameter=diameter, device=device, ) else: algo = "sparsery" if cfg.algorithm == "cellpose" else cfg.algorithm sdmov = utils.standard_deviation_over_time(mov, batch_size=1000) if algo == "sparsery": _, raw_stat = sparsedetect.sparsery( mov=mov, sdmov=sdmov, threshold_scaling=cfg.threshold_scaling, **s["sparsery_settings"], ) elif algo == "sourcery": _, raw_stat = sourcery.sourcery( mov=mov, sdmov=sdmov, diameter=diameter, threshold_scaling=cfg.threshold_scaling, **s["sourcery_settings"], ) else: raise ValueError(f"unknown algorithm {cfg.algorithm!r}") stat = list(raw_stat) if not stat: return [] # shift ROI pixel coordinates from cropped frame back to full image ymin, xmin = int(yrange[0]), int(xrange[0]) for st in stat: st["ypix"] += ymin st["xpix"] += xmin if "med" in st: st["med"][0] += ymin st["med"][1] += xmin # roi_stats indexes its first arg with a boolean mask, so it must be a # numpy object array — not a plain list. stat_array = np.array(stat, dtype=object) return list( roi_stats( stat_array, Ly, Lx, diameter=diameter, max_overlap=cfg.max_overlap, do_soma_crop=cfg.soma_crop, median=use_cellpose, ) )
[docs] @register_segmentation_class class Suite2pSegmentation(BaseSegmentation): """Suite2p ROI detection, streamed from the imaging object. Frames are pulled lazily via :func:`BaseImagingEpoch.get_series` and stream-binned in place, so the full raw movie is never materialised. Returns a :class:`Suite2pRois` holding every plane's suite2p ``stat``. """ method_name = "suite2p" settings_class = Suite2pSegmentationSettings
[docs] @classmethod def is_installed(cls) -> bool: try: import suite2p # noqa: F401, PLC0415 except ImportError: return False return True
[docs] @classmethod def get_method_version(cls) -> str: return importlib.metadata.version("suite2p")
[docs] @classmethod def run( cls, imaging: BaseImaging, yrange: Sequence[int], xrange: Sequence[int], badframes: NDArray[np.bool_] | None, settings: Suite2pSegmentationSettings, ) -> Suite2pRois: from suite2p.classification import builtin_classfile, classify # noqa: PLC0415 H, W, n_planes = imaging.shape n_epochs = imaging.get_num_epochs() n_frames = int(imaging.get_total_frames()) bin_size = int(max(1, n_frames // settings.nbins, np.round(settings.tau * settings.fs))) logging.info("Suite2p detection — %d epochs", n_epochs) t0 = time.time() mov = _stream_bin_movie( imaging, bin_size=bin_size, yrange=yrange, xrange=xrange, badframes=badframes, nbins=settings.nbins, ) stat = _detect_rois_from_mov( mov, cfg=settings, Ly=H, Lx=W, yrange=yrange, xrange=xrange, ) logging.info(" found %d ROIs in %.1fs", len(stat), time.time() - t0) rois = Suite2pRois.from_stat( stats=stat, shape=(H, W, n_planes), sampling_frequency=imaging.sampling_frequency, ) if stat: # classify reads stat[0] iscell = classify(stat=np.array(stat, dtype=object), classfile=builtin_classfile) # same properties Suite2pRois sets when loading iscell.npy from a suite2p folder rois.set_property("iscell", iscell[:, 0] == 1) rois.set_property("iscell_probability", iscell[:, 1]) return rois