Source code for photon_mosaic.preprocessing.suite2p_registration

import logging
import math
import time
from typing import Any, Sequence

import numpy as np
from numpy.typing import NDArray
from pydantic import ConfigDict, Field

from photon_mosaic.core import (
    BaseImaging,
    Motion,
    register_motion_class,
    register_registration_class,
    split_epoch_at_frames,
)
from photon_mosaic.core.selectplanes import select_planes

from .registration import RegisterImaging, RegisterImagingEpoch, RegistrationSettings


[docs] class Suite2pRegistrationSettings(RegistrationSettings): """Settings for Suite2P motion correction. Adds the Suite2P specific parameters on top of the shared :class:`photon_mosaic.preprocessing.registration.RegistrationSettings` (``debug``, ``tmp_dir``, ``batch_size``, ``device``). Values can be provided via constructor, environment variables, or .env file. """ data_type: str = Field(default="h5", description="Processing h5 (default) or TIFF timeseries") do_registration: bool = Field( default=True, description="whether to register data (2 forces re-registration)", ) align_by_chan: int = Field( default=1, description="when multi-channel, you can align by non-functional channel (1-based)", ) maxregshift: float = Field( default=0.1, description="max allowed registration shift, as a fraction of " "frame max(width and height). This will be ignored if force_refImg is set to True", ) force_refImg: bool = Field(default=True, description="Force the use of an external reference image") block_size: list = Field(default_factory=lambda: [128, 128], description="Block size for non-rigid registration.") snr_thresh: float = Field( default=1.2, description="if any nonrigid block is below this threshold, it gets smoothed " "until above this threshold. 1.0 results in no smoothing", ) outlier_detrend_window: float = Field( default=3.0, description="For outlier rejection in the xoff/yoff outputs of suite2p, the offsets are first de-trended " "with a median filter of this duration [seconds]. " "This value is ~30 or 90 samples in size for 11 and 31 Hz sampling rates respectively.", ) outlier_maxregshift: float = Field( default=0.05, description="Units [fraction FOV dim]. After median-filter detrending, outliers more than this value are " "clipped to this value in x and y offset, independently. " "This is similar to Suite2P's internal maxregshift, but allows for low-frequency drift. " "Default value of 0.05 is typically clipping outliers to " "512 * 0.05 = 25 pixels above or below the median trend.", ) clip_negative: bool = Field( default=False, description="Whether or not to clip negative pixel values in output. Because the pixel values " "in the raw movies are set by the current coming off a photomultiplier tube, there can " "be pixels with negative values (current has a sign), possibly due to noise in the rig. " "Some segmentation algorithms cannot handle negative values in the movie, so we have this " "option to artificially set those pixels to zero.", ) max_reference_iterations: int = Field( default=8, description="Maximum number of iterations for creating a reference image", ) auto_remove_empty_frames: bool = Field( default=True, description="Automatically detect empty noise frames at the start and end of the movie. " "Overrides values set in " "trim_frames_start and trim_frames_end. Some movies arrive with otherwise quality data but contain a set of " "frames that are empty and contain pure noise. When processed, these frames tend to receive " "large random shifts that throw off motion border calculation. Turning on this setting automatically " "detects these frames before processing and removes them from reference image creation, automated smoothing " "parameter searches, and finally the motion border calculation. The frames are still written however any " "shift estimated is removed and their shift is set to 0 to avoid large motion borders.", ) trim_frames_start: int = Field( default=0, description="Number of frames to remove from the start of the movie if known. " "Removes frames from motion border calculation " "and resets the frame shifts found. Frames are still written to motion correction. Raises an error if " "auto_remove_empty_frames is set and trim_frames_start > 0", ) trim_frames_end: int = Field( default=0, description="Number of frames to remove from the end of the movie if known. " "Removes frames from motion border calculation " "and resets the frame shifts found. Frames are still written to motion correction. Raises an error if " "auto_remove_empty_frames is set and trim_frames_start > 0", ) do_optimize_motion_params: bool = Field( default=False, description="Do a search for best parameters of smooth_sigma and smooth_sigma_time. " "Adds significant runtime cost to " "motion correction and should only be run once per experiment with the resulting parameters being stored " "for later use.", ) smooth_sigma_time: int = Field( default=0, description="gaussian smoothing in time. Must be 0: suite2p 1.x crashes for values > 0 " "(https://github.com/MouseLand/suite2p/issues/1271).", ) smooth_sigma: float = Field( default=1.15, description="~1 good for 2P recordings, recommend 3-5 for 1P recordings. " "If do_optimize_motion_params is set, this will be overridden", ) use_ave_image_as_reference: bool = Field( default=False, description="Only available if `do_optimize_motion_params` is set. " "After the a best set of smoothing parameters is found, " "use the resulting average image as the reference for the full registration. This can be used as two step " "registration by setting by setting smooth_sigma_min=smooth_sigma_max and " "smooth_sigma_time_min=smooth_sigma_time_max and steps=1.", ) # Additional parameters that were hardcoded in the original code movie_lower_quantile: float = Field( default=0.1, description="Lower quantile threshold for avg projection histogram adjustment of movie", ) movie_upper_quantile: float = Field( default=0.999, description="Upper quantile threshold for avg projection histogram adjustment of movie", ) preview_frame_bin_seconds: float = Field( default=2.0, description="Before creating the webm, the movies will be averaged into bins of this many seconds", ) preview_playback_factor: float = Field( default=10.0, description="The preview movie will playback at this factor times real-time", ) n_batches: int = Field( default=20, description="Number of batches to load from the movie for smoothing parameter testing. " "Batches are evenly spaced throughout the movie.", ) smooth_sigma_min: float = Field( default=0.65, description="Minimum value of the parameter search for smooth_sigma", ) smooth_sigma_max: float = Field( default=2.15, description="Maximum value of the parameter search for smooth_sigma", ) smooth_sigma_steps: int = Field( default=4, description="Number of steps to grid between smooth_sigma and smooth_sigma_max", ) smooth_sigma_time_min: float = Field( default=0, description="Minimum value of the parameter search for smooth_sigma_time", ) smooth_sigma_time_max: float = Field( default=6, description="Maximum value of the parameter search for smooth_sigma_time", ) smooth_sigma_time_steps: int = Field( default=7, description="Number of steps to grid between smooth_sigma and smooth_sigma_time_max. " "Large values will add significant time to motion correction", ) model_config = ConfigDict(env_prefix="SUITE2P_REGISTRATION_", case_sensitive=False, env_file=".env")
def _compute_reference_wrapper( f_align_in: NDArray, settings: dict, refImg: NDArray | None = None, device=None, ) -> tuple[NDArray, int]: """Compute the reference image for a single plane using Suite2p's algorithm. Parameters ---------- f_align_in : NDArray Frames shaped ``(n_frames, Ly, Lx)``. settings : dict Suite2p settings dict (merged with suite2p defaults). refImg : NDArray | None, optional Pre-computed reference image. If provided, skips computation. device : torch.device | None, optional Torch device to use. Defaults to CPU. Returns ------- refImg : NDArray Reference image shaped ``(Ly, Lx)``. bidiphase : int Bidirectional phase offset in pixels. """ import suite2p.registration.bidiphase as bidi import torch from suite2p.registration.register import compute_reference if device is None: device = torch.device("cpu") n_frames = f_align_in.shape[0] compute_bidi = settings.get("do_bidiphase", False) and settings.get("bidiphase", 0) == 0 if refImg is None or compute_bidi: ix_frames = np.linspace(0, n_frames, 1 + min(settings.get("nimg_init", 200), n_frames), dtype=int)[:-1] frames = f_align_in[ix_frames].copy() if compute_bidi: bidiphase = bidi.compute(frames) logging.info("Estimated bidiphase offset from data: %d pixels" % bidiphase) else: bidiphase = settings.get("bidiphase", 0) if bidiphase != 0 and refImg is None: frames = bidi.shift(frames, bidiphase) if refImg is None: t0 = time.time() refImg = compute_reference(frames, settings=settings, device=device) logging.info("Reference frame computed in %0.2f sec." % (time.time() - t0)) return refImg, bidiphase
[docs] class Suite2PMotion(Motion): """Motion artifacts produced by Suite2P registration. Adds Suite2P-specific fields (``ops``, block coordinates, non-rigid offsets) on top of the algorithm-agnostic :class:`Motion` container. """ method_name = "suite2p" settings_class = Suite2pRegistrationSettings def __init__( self, imaging: BaseImaging, displacements: Sequence[NDArray[np.floating[Any]]], ops: dict[str, Any], reference: Any = None, nonrigid_offsets: Sequence[Sequence[tuple[NDArray[np.floating[Any]], NDArray[np.floating[Any]]]] | None] | Sequence[Sequence[tuple[NDArray[np.floating[Any]], NDArray[np.floating[Any]]] | None]] | None = None, blocks: Sequence[Any] | None = None, yranges: Sequence[Sequence[tuple[int, int]]] | None = None, xranges: Sequence[Sequence[tuple[int, int]]] | None = None, corrected_badframes: Sequence[NDArray[np.bool_]] | None = None, metadata: dict[str, Any] | None = None, ) -> None: """Store Suite2P registration outputs. Parameters ---------- imaging, displacements, reference, yranges, xranges, metadata See :class:`photon_mosaic.core.motion.Motion`. corrected_badframes : Sequence | None, optional Per-epoch bad-frame mask (see :class:`photon_mosaic.core.motion.Motion`). For Suite2P this is the union of any caller-supplied ``badframes`` with frames whose registration shift exceeded ``maxregshift``, then combined across planes (a frame flagged on any plane is flagged for the whole volume). ops : dict[str, Any] Suite2P options used during registration. nonrigid_offsets : Sequence | None, optional Per-epoch, per-plane non-rigid offsets. Structure: ``[epoch][plane] -> (yoff1, xoff1)`` each ``(n_frames, n_blocks)``. blocks : Sequence | None, optional Suite2P block definitions when non-rigid registration is enabled. """ super().__init__( imaging=imaging, displacements=displacements, reference=reference, yranges=yranges, xranges=xranges, corrected_badframes=corrected_badframes, metadata=metadata, ) self.ops = ops self.nonrigid_offsets = nonrigid_offsets self.blocks = blocks def _to_dict_kwargs(self) -> dict[str, Any]: """Add the Suite2P-specific fields to :meth:`Motion._to_dict_kwargs`.""" kwargs = super()._to_dict_kwargs() blocks = None if self.blocks is None else [_compact_blocks(b) for b in self.blocks] kwargs.update(ops=self.ops, nonrigid_offsets=self.nonrigid_offsets, blocks=blocks) return kwargs @classmethod def _from_dict_kwargs(cls, kwargs: dict[str, Any]) -> dict[str, Any]: """Rebuild the upsampling matrix dropped by :meth:`_to_dict_kwargs`.""" kwargs = super()._from_dict_kwargs(kwargs) if kwargs.get("blocks") is not None: kwargs["blocks"] = [_expand_blocks(b) for b in kwargs["blocks"]] return kwargs @classmethod def _compute( cls, imaging: BaseImaging, *, settings: Suite2pRegistrationSettings | None = None, badframes: NDArray | None = None, **params: Any, ) -> "Suite2PMotion": """Pre-compute Suite2P displacements for all planes and epochs. Computes the reference image and per-frame rigid (and optionally nonrigid) shifts without applying them to the data. Shifts are stored in the returned ``Motion`` object and applied lazily by ``RegisterSuite2PImagingEpoch``. Called through :meth:`photon_mosaic.core.Motion.compute` (or its ``compute_motion`` alias), which resolves ``settings`` before calling this. Parameters ---------- imaging : BaseImaging Imaging object containing one or more epochs/planes to be registered. settings : Suite2pRegistrationSettings | None, optional Registration settings; ``None`` uses the defaults. badframes : NDArray | None, optional Boolean array of shape ``(n_frames,)`` marking frames to exclude from reference image computation. **params : Any Extra Suite2P options applied on top of ``settings``. Returns ------- Suite2PMotion Motion container with per-epoch displacements and Suite2P-specific fields (``ops``, ``blocks``, ``nonrigid_offsets``). """ import torch from suite2p.registration.register import compute_crop, default_settings, register_frames # Merge suite2p defaults -> our settings -> caller overrides ops = default_settings()["registration"] if settings is None: settings = cls.settings_class() ops.pop("maxregshiftNR", None) # suite2p's name for max_nonrigid_shift; ours is used throughout ops.update(settings.model_dump()) if "maxregshiftNR" in params: raise ValueError("'maxregshiftNR' is now 'max_nonrigid_shift'.") ops.update(params) if ops["smooth_sigma_time"] > 0: raise ValueError("smooth_sigma_time > 0 crashes suite2p 1.x registration.") bounds = ops["bounds"] if bounds is not None and ops["nonrigid"]: raise ValueError( "'bounds' (an estimation crop) is supported by the suite2p backend for rigid registration only: " "its non-rigid block geometry is defined on the frame the shifts are applied to." ) rows, cols = (slice(None), slice(None)) if bounds is None else (slice(*bounds[0]), slice(*bounds[1])) device = torch.device(ops.get("device", "cpu")) n_planes = imaging.num_planes n_epochs = imaging.get_num_epochs() # Reference images and bidiphase offsets computed once per plane from epoch 0 refImgs: list[NDArray | None] = [None] * n_planes bidiphases: list[int] = [0] * n_planes # Block definitions are the same for all epochs (geometry doesn't change) all_blocks: list[Any] | None = None all_displacements: list[NDArray] = [] all_nonrigid_offsets: list[list | None] = [] all_yranges: list[list[tuple[int, int]]] = [] all_xranges: list[list[tuple[int, int]]] = [] all_corrected_badframes: list[NDArray] = [] for epoch_idx in range(n_epochs): n_frames = imaging.get_num_samples(segment_index=epoch_idx) Ly, Lx = imaging.shape[0], imaging.shape[1] badframes0 = np.zeros(n_frames, dtype=bool) if badframes is None else badframes.copy() epoch_yoff: list[NDArray] = [] epoch_xoff: list[NDArray] = [] epoch_corrXY: list[NDArray] = [] epoch_nr: list[tuple[NDArray, NDArray] | None] = [] epoch_blocks: list[Any] = [] # sub-epochs of batch_size frames: each is read whole, so one batch is in memory at a time batch_size = ops["batch_size"] batched = split_epoch_at_frames(imaging, epoch_idx, range(batch_size, n_frames, batch_size)) for p, plane_id in enumerate(imaging.plane_ids): # Reference once, from the first epoch: read only the nimg_init evenly spaced frames suite2p # samples (the wrapper then uses all of them) if epoch_idx == 0: picks = np.linspace(0, n_frames, 1 + min(ops.get("nimg_init", 200), n_frames), dtype=int)[:-1] plane = select_planes(imaging, [plane_id]) sample = np.concatenate([plane.get_series(i, i + 1, epoch_index=0) for i in picks]) sample = sample[:, rows, cols, 0].astype(np.float32) refImgs[p], bidiphases[p] = _compute_reference_wrapper(sample, ops, refImg=None, device=device) # Compute shifts without applying them, one sub-epoch (= one suite2p batch) per call. # Only the offsets are kept per batch: the other returns include a mean image per call. # Select the plane after splitting: selection is applied by get_series, not by the epochs. plane_batches = select_planes(batched, [plane_id]) batch_offsets = [] for b in range(plane_batches.get_num_epochs()): _, _, _, offsets, blocks, _, _, _ = register_frames( plane_batches.get_series(epoch_index=b)[:, rows, cols, 0].astype(np.float32), refImg=refImgs[p], f_align_out=None, batch_size=batch_size, bidiphase=bidiphases[p], norm_frames=ops.get("norm_frames", True), smooth_sigma=ops["smooth_sigma"], spatial_taper=ops.get("spatial_taper", 3.45), block_size=ops["block_size"], nonrigid=ops["nonrigid"], maxregshift=ops["maxregshift"], smooth_sigma_time=ops["smooth_sigma_time"], snr_thresh=ops["snr_thresh"], maxregshiftNR=ops["max_nonrigid_shift"], device=device, apply_shifts=False, ) batch_offsets.append(offsets) # suite2p's eight offset arrays, concatenated across batches as register_frames does internally yoff, xoff, corrXY, yoff1, xoff1, corrXY1, zest, cmax_all = [ None if parts[0] is None else np.concatenate(parts, axis=0) for parts in zip(*batch_offsets) ] epoch_yoff.append(yoff) epoch_xoff.append(xoff) epoch_corrXY.append(corrXY) epoch_nr.append((yoff1, xoff1) if yoff1 is not None else None) if epoch_idx == 0 and blocks is not None: epoch_blocks.append(blocks) if epoch_idx == 0 and epoch_blocks: all_blocks = epoch_blocks # Stack planes → always (n_frames, n_planes, 2) disps = np.stack([np.stack(epoch_yoff, axis=1), np.stack(epoch_xoff, axis=1)], axis=-1) all_displacements.append(disps) has_nonrigid = any(o is not None for o in epoch_nr) all_nonrigid_offsets.append(epoch_nr if has_nonrigid else None) # Compute valid FOV region and refined bad-frame mask for each plane epoch_yranges: list[tuple[int, int]] = [] epoch_xranges: list[tuple[int, int]] = [] epoch_cbf: list[NDArray] = [] for p in range(n_planes): bf, yrange, xrange = compute_crop( xoff=epoch_xoff[p], yoff=epoch_yoff[p], corrXY=epoch_corrXY[p], th_badframes=ops.get("th_badframes", 1.0), badframes=badframes0.copy(), maxregshift=ops["maxregshift"], Ly=Ly, Lx=Lx, ) epoch_yranges.append(tuple(yrange)) epoch_xranges.append(tuple(xrange)) epoch_cbf.append(bf) all_yranges.append(epoch_yranges) all_xranges.append(epoch_xranges) # Bad frames are a property of the time axis (a corrupted volume frame # is bad on all planes) — collapse Suite2P's per-plane masks into one. all_corrected_badframes.append(np.logical_or.reduce(epoch_cbf)) nonrigid_offsets = all_nonrigid_offsets if any(o is not None for o in all_nonrigid_offsets) else None return cls( imaging=imaging, displacements=all_displacements, ops=ops, reference=refImgs, nonrigid_offsets=nonrigid_offsets, blocks=all_blocks, yranges=all_yranges, xranges=all_xranges, corrected_badframes=all_corrected_badframes, )
# suite2p's make_blocks returns (yblock, xblock, nblocks, block_size, NRsm, Kmat, nup). Kmat is a # ((2*lpad+1)**2, nup**2) float32 tensor -- ~0.7 MB, ~11 MB as json, per plane -- but it is fully # determined by lpad and subpixel, so serialize those two ints instead and recompute it on load. _KMAT_INDEX = 5 def _compact_blocks(blocks: Any) -> Any: """Replace the ``Kmat`` of one plane's ``blocks`` by the ``mat_upsample`` arguments that produce it.""" if not isinstance(blocks, tuple) or len(blocks) != 7: return blocks # rigid registration stores no blocks for the plane kmat, nup = blocks[_KMAT_INDEX], blocks[6] lpad = (math.isqrt(kmat.shape[0]) - 1) // 2 subpixel = (nup - 1) // (2 * lpad) return blocks[:_KMAT_INDEX] + ({"lpad": lpad, "subpixel": subpixel},) + blocks[_KMAT_INDEX + 1 :] def _expand_blocks(blocks: Any) -> Any: """Inverse of :func:`_compact_blocks`.""" if not isinstance(blocks, tuple) or len(blocks) != 7 or not isinstance(blocks[_KMAT_INDEX], dict): return blocks from suite2p.registration.utils import mat_upsample # noqa: PLC0415 kmat, _ = mat_upsample(**blocks[_KMAT_INDEX]) return blocks[:_KMAT_INDEX] + (kmat,) + blocks[_KMAT_INDEX + 1 :]
[docs] class RegisterSuite2PImaging(RegisterImaging): """Apply pre-computed Suite2P motion correction on-the-fly. Thin alias of :class:`photon_mosaic.preprocessing.registration.RegisterImaging`, kept for discoverability and backwards compatibility; the generic class already dispatches on ``method``. """
[docs] class RegisterSuite2PImagingEpoch(RegisterImagingEpoch): """Epoch-level preprocessor that applies stored Suite2P displacements. Frame bounds, plane selection and output allocation come from :class:`~photon_mosaic.preprocessing.registration.RegisterImagingEpoch`; this class only shifts one plane's frames with Suite2P's ``shift_frames``. """ motion: Suite2PMotion def _correct_plane( self, plane_video: NDArray[np.floating[Any]], plane_index: int, start_frame: int, end_frame: int, ) -> NDArray[np.floating[Any]]: """Shift one plane's frames by the stored rigid (and non-rigid) offsets.""" import torch from suite2p.registration import register p = plane_index disps = self.motion.displacements[self.epoch_index] yoff = disps[start_frame:end_frame, p, 0].astype(int) xoff = disps[start_frame:end_frame, p, 1].astype(int) yoff1 = xoff1 = blocks = None if self.motion.nonrigid_offsets is not None: epoch_offsets = self.motion.nonrigid_offsets[self.epoch_index] if epoch_offsets is not None and p < len(epoch_offsets): plane_offsets = epoch_offsets[p] if plane_offsets is not None: yoff1_full, xoff1_full = plane_offsets yoff1 = yoff1_full[start_frame:end_frame] xoff1 = xoff1_full[start_frame:end_frame] if self.motion.blocks is not None: blocks = self.motion.blocks[p] # Apply motion correction shifts — always CPU for on-the-fly application device = torch.device("cpu") plane_video_torch = torch.from_numpy(plane_video).to(device) yoff_torch = torch.from_numpy(yoff.astype(np.int64)).to(device) xoff_torch = torch.from_numpy(xoff.astype(np.int64)).to(device) yoff1_torch = None xoff1_torch = None if yoff1 is not None: yoff1_torch = torch.from_numpy(yoff1).to(device) xoff1_torch = torch.from_numpy(xoff1).to(device) return register.shift_frames( plane_video_torch, yoff_torch, xoff_torch, yoff1_torch, xoff1_torch, blocks=blocks, device=device, )
register_motion_class(Suite2PMotion) register_registration_class("suite2p", RegisterSuite2PImagingEpoch)