from __future__ import annotations
import importlib
import json
import shutil
from pathlib import Path
from typing import Any, Literal, Sequence
import numpy as np
from numpy.typing import NDArray
from pydantic_settings import BaseSettings
from photon_mosaic.core import BaseImaging
from photon_mosaic.core.baserois import BaseRois
# Editor autocomplete/typo-checking for the built-in methods. Not exhaustive:
# any string registered via ``register_segmentation_class`` (including
# third-party ones) is still accepted at runtime.
KnownSegmentationMethod = Literal["suite2p"]
# Method name -> module that defines (and registers) the backend's
# BaseSegmentation subclass. Only module *paths* live here, so this module
# imports no backend: the module is imported lazily the first time the method
# is requested.
_builtin_segmentation_modules: dict[str, str] = {
"suite2p": "photon_mosaic.segmentation.suite2p_segmentation",
}
# Method name -> BaseSegmentation subclass, filled in by ``register_segmentation_class``.
_registered_segmentation_classes: dict[str, type["BaseSegmentation"]] = {}
[docs]
def register_segmentation_class(segmentation_class: type["BaseSegmentation"]) -> type["BaseSegmentation"]:
"""Register a :class:`BaseSegmentation` subclass under its ``method_name``.
Backend modules call this at import time so that
``run_segmentation(..., method=...)`` can find them. Third-party backends
can call it too, which is what makes the set of methods extensible.
Parameters
----------
segmentation_class : type[BaseSegmentation]
Subclass defining ``method_name`` (and usually ``settings_class``).
Returns
-------
type[BaseSegmentation]
The class, unchanged, so this can be used as a decorator.
"""
name = segmentation_class.method_name
if not name:
raise ValueError(f"{segmentation_class.__name__} must define a non-empty 'method_name' to be registered.")
_registered_segmentation_classes[name] = segmentation_class
return segmentation_class
[docs]
def get_segmentation_class(method: str) -> type["BaseSegmentation"]:
"""Return the :class:`BaseSegmentation` subclass implementing ``method``.
Built-in backends are imported lazily on first use, so an optional
dependency is only required when its method is actually requested.
"""
if method in _registered_segmentation_classes:
return _registered_segmentation_classes[method]
module_path = _builtin_segmentation_modules.get(method)
if module_path is None:
known = sorted(set(_registered_segmentation_classes) | set(_builtin_segmentation_modules))
raise ValueError(f"Unknown segmentation method '{method}'. Available methods: {known}.")
try:
importlib.import_module(module_path)
except ImportError as exc:
raise ImportError(
f"Segmentation method '{method}' requires optional dependencies that are not installed "
f"(failed to import '{module_path}': {exc})."
) from exc
if method not in _registered_segmentation_classes:
raise ImportError(
f"Module '{module_path}' was imported but did not register a segmentation class for method '{method}'."
)
return _registered_segmentation_classes[method]
[docs]
def get_available_segmentation_methods() -> list[str]:
"""Return the names of all built-in and registered segmentation methods."""
return sorted(set(_registered_segmentation_classes) | set(_builtin_segmentation_modules))
[docs]
class BaseSegmentation:
"""Base class for ROI segmentation backends.
Modelled on SpikeInterface's ``BaseSorter``: subclasses are never
instantiated, they only provide classmethods that
:func:`photon_mosaic.segmentation.run_segmentation` calls in order:
1. :meth:`initialize_folder` / :meth:`set_params_to_folder` (provided here)
2. :meth:`run` -- detect ROIs on one contiguous span of epochs and return
them as a :class:`BaseRois`
Subclasses declare ``method_name`` (the string users pass as ``method``)
and ``settings_class`` (their pydantic settings model), and register
themselves with :func:`register_segmentation_class`.
"""
method_name: str | None = None
settings_class: type[BaseSettings] | None = None
support_multi_plane = False
[docs]
@classmethod
def is_installed(cls) -> bool:
"""Return whether the backend's dependencies are importable."""
raise NotImplementedError
[docs]
@classmethod
def get_method_version(cls) -> str:
"""Return the version of the underlying segmentation library."""
raise NotImplementedError
[docs]
@classmethod
def default_params(cls) -> dict[str, Any]:
"""Return the default value of every setting of ``settings_class``."""
if cls.settings_class is None:
return {}
return cls.settings_class().model_dump()
[docs]
@classmethod
def params_description(cls) -> dict[str, str | None]:
"""Return the description of every setting of ``settings_class``."""
if cls.settings_class is None:
return {}
return {name: field.description for name, field in cls.settings_class.model_fields.items()}
[docs]
@classmethod
def initialize_folder(cls, folder: str | Path, remove_existing_folder: bool = False) -> Path:
"""Create the output ``folder``, refusing to overwrite unless asked."""
folder = Path(folder)
if folder.exists():
if not remove_existing_folder:
raise FileExistsError(f"Folder {folder} already exists; pass remove_existing_folder=True to overwrite.")
shutil.rmtree(folder)
folder.mkdir(parents=True)
return folder
[docs]
@classmethod
def set_params_to_folder(cls, folder: str | Path, settings: Any, run_kwargs: dict[str, Any]) -> None:
"""Write the validated settings and the run arguments to ``segmentation_params.json``."""
params = {
"method": cls.method_name,
"settings": settings.model_dump(mode="json") if settings is not None else None,
"run_kwargs": run_kwargs,
}
with open(Path(folder) / "segmentation_params.json", "w") as f:
json.dump(params, f, indent=4)
[docs]
@classmethod
def run(
cls,
imaging: BaseImaging,
yrange: Sequence[int],
xrange: Sequence[int],
badframes: NDArray[np.bool_] | None,
settings: Any,
) -> BaseRois:
"""Detect ROIs on the concatenation of all epochs of ``imaging`` and return them.
Parameters
----------
imaging : BaseImaging
Motion-corrected imaging object.
yrange, xrange : sequence of int
Valid pixel range ``[lo, hi]``.
badframes : NDArray[bool] | None
Frames to exclude, shaped ``(total_frames_in_epochs,)``.
settings : BaseSettings
Validated ``settings_class`` instance.
Returns
-------
rois : BaseRois
Detected ROIs for the concatenated epochs.
"""
raise NotImplementedError
def _resolve_ranges(
value: Sequence[int] | Sequence[Sequence[int]] | None,
n_epochs: int,
*,
default: Sequence[int],
label: str,
) -> list[list[int]]:
"""Expand a y/x range argument into one ``[lo, hi]`` per epoch.
Accepts ``None`` (use ``default`` for every epoch), a flat ``[lo, hi]``
pair (broadcast to every epoch), or a ``(n_epochs, 2)`` sequence with one
range per epoch.
"""
if value is None:
return [list(default) for _ in range(n_epochs)]
arr = np.asarray(value)
if arr.ndim == 1:
if arr.shape[0] != 2:
raise ValueError(f"{label} must have length 2, got shape {arr.shape}")
return [arr.tolist() for _ in range(n_epochs)]
if arr.ndim == 2:
if arr.shape != (n_epochs, 2):
raise ValueError(f"{label} must have shape ({n_epochs}, 2), got {arr.shape}")
return [list(row) for row in arr.tolist()]
raise ValueError(f"{label} must be 1D or 2D, got ndim={arr.ndim}")
def _resolve_badframes(
value: NDArray[np.bool_] | Sequence[NDArray[np.bool_] | None] | None,
n_epochs: int,
frame_counts: Sequence[int],
) -> list[NDArray[np.bool_] | None]:
"""Normalize a badframes argument into one boolean array (or None) per epoch.
Accepts ``None``, a single flat ``(total_frames,)`` boolean array (split
along ``frame_counts``), or a per-epoch sequence of per-epoch arrays.
"""
if value is None:
return [None] * n_epochs
if isinstance(value, np.ndarray):
total = int(sum(frame_counts))
if value.shape[0] != total:
raise ValueError(f"badframes length {value.shape[0]} does not match total frame count {total}")
out: list[NDArray[np.bool_] | None] = []
offset = 0
for n in frame_counts:
out.append(np.asarray(value[offset : offset + n], dtype=bool))
offset += n
return out
if len(value) != n_epochs:
raise ValueError(f"badframes list length {len(value)} does not match number of epochs {n_epochs}")
out = []
for i, (b, n) in enumerate(zip(value, frame_counts)):
if b is None:
out.append(None)
continue
b_arr = np.asarray(b, dtype=bool)
if b_arr.shape[0] != n:
raise ValueError(f"badframes[{i}] length {b_arr.shape[0]} does not match epoch frame count {n}")
out.append(b_arr)
return out