photon_mosaic.core.roianalyzer#

RoiAnalyzer: core class for pairing BaseRois and BaseImaging for analysis.

Adapted from SpikeInterface’s SortingAnalyzer to work with photon-mosaic’s BaseRois and BaseImaging instead of BaseSorting and BaseRecording.

Functions

create_roi_analyzer(rois, imaging[, format, ...])

Create a RoiAnalyzer by pairing a BaseRois and a BaseImaging.

get_available_analyzer_extensions()

Get all built-in extension names.

get_default_analyzer_extension_params(...)

Get the default params for an extension.

get_extension_class(extension_name[, ...])

Get extension class by name, auto-importing if needed.

load_roi_analyzer(folder[, load_extensions, ...])

Load a RoiAnalyzer from disk.

register_result_extension(extension_class)

Register an AnalyzerExtension subclass so it can be discovered by name.

Classes

AnalyzerExtension(roi_analyzer)

Base class for RoiAnalyzer extensions.

RoiAnalyzer(rois[, imaging, ...])

Pair BaseRois and BaseImaging for extensible post-processing analysis.

photon_mosaic.core.roianalyzer.create_roi_analyzer(rois, imaging, format='memory', folder=None, overwrite=False, backend_options=None)[source]#

Create a RoiAnalyzer by pairing a BaseRois and a BaseImaging.

The RoiAnalyzer manages a collection of AnalyzerExtension instances for post-processing steps such as trace extraction, dF/F, deconvolution, etc.

Parameters:
  • rois (BaseRois) – The ROIs object.

  • imaging (BaseImaging) – The imaging object.

  • format (str) – The storage backend. If “binary_folder” or “zarr”, folder must be provided.

  • folder (str | Path | None, default: None) – The folder where the analyzer is persisted (required for non-memory formats).

  • overwrite (bool) – If True, overwrite the folder if it already exists.

  • backend_options (dict | None) –

    Backend-specific options. May contain:

    • storage_options: dict | None (fsspec storage options)

    • saving_options: dict | None (e.g. compression for zarr)

Returns:

The created RoiAnalyzer object.

Return type:

RoiAnalyzer

photon_mosaic.core.roianalyzer.load_roi_analyzer(folder, load_extensions=True, format='auto', backend_options=None)[source]#

Load a RoiAnalyzer from disk.

Parameters:
  • folder (str or Path) – The folder where the analyzer is stored.

  • load_extensions (bool) – Whether to load all saved extensions.

  • format (str) – The format of the stored analyzer. “auto” will guess from the path.

  • backend_options (dict | None) – Backend-specific options (e.g. storage_options for remote zarr).

Returns:

The loaded RoiAnalyzer.

Return type:

RoiAnalyzer

class photon_mosaic.core.roianalyzer.RoiAnalyzer(rois, imaging=None, imaging_attributes=None, format=None, backend_options=None)[source]#

Pair BaseRois and BaseImaging for extensible post-processing analysis.

Maintains a collection of computed AnalyzerExtension instances. Supports three storage backends: "memory", "binary_folder", and "zarr".

Do not instantiate directly — use create_roi_analyzer() or RoiAnalyzer.create().

Attributes:
imaging
num_planes
roi_ids
sampling_frequency
shape

Methods

compute(input[, save, extension_params, verbose])

Compute one or several extensions.

compute_one_extension(extension_name[, ...])

Compute a single extension.

compute_several_extensions(extensions[, ...])

Compute several extensions respecting dependency order.

copy()

Create an in-memory copy.

create(rois, imaging[, format, folder, ...])

Create a new RoiAnalyzer.

delete_extension(extension_name)

Delete an extension from memory and from disk.

get_computable_extensions()

List all registered extension names.

get_default_extension_params(extension_name)

Get default params for an extension.

get_extension(extension_name)

Get an extension, auto-loading from disk if needed.

get_loaded_extension_names()

Return names of currently loaded extensions.

get_roi_property(key[, ids])

Get a property from the internal ROIs copy.

get_rois_provenance()

Get the original rois object if possible, otherwise None.

get_saved_extension_names()

Get extension names saved on disk (without loading data).

has_extension(extension_name)

Check if an extension exists (in memory or on disk).

load(folder[, imaging, load_extensions, ...])

Load from folder or zarr.

load_all_saved_extension()

Load all saved extensions into memory.

load_extension(extension_name)

Load an extension from disk into memory.

remove_rois(remove_roi_ids[, format, folder])

Create a new RoiAnalyzer with some ROIs removed.

save_as([format, folder, backend_options])

Save the analyzer to a different backend.

select_rois(roi_ids[, format, folder])

Create a new RoiAnalyzer with a subset of ROIs.

set_roi_property(key, values[, ids, ...])

Set a property on the internal ROIs copy, optionally persisting to disk.

set_temporary_imaging(imaging[, check_dtype])

Set a temporary imaging (e.g. a cached/loaded copy) without persisting it.

create_binary_folder

create_memory

create_zarr

get_dtype

get_num_epochs

get_num_rois

get_num_samples

get_total_duration

get_total_samples

has_imaging

has_temporary_imaging

is_read_only

load_from_binary_folder

load_from_zarr

classmethod create(rois, imaging, format='memory', folder=None, backend_options=None)[source]#

Create a new RoiAnalyzer.

Parameters:
  • rois (BaseRois) – The ROIs object.

  • imaging (BaseImaging) – The imaging object.

  • format (Literal['memory', 'binary_folder', 'zarr']) – Storage backend.

  • folder (str | Path | None) – Required for non-memory formats.

  • backend_options (dict | None) – Backend-specific options.

Return type:

RoiAnalyzer

classmethod load(folder, imaging=None, load_extensions=True, format='auto', backend_options=None)[source]#

Load from folder or zarr.

The imaging can be provided if its location has changed.

classmethod create_memory(rois, imaging, imaging_attributes)[source]#
classmethod create_binary_folder(folder, rois, imaging, imaging_attributes, backend_options)[source]#
classmethod load_from_binary_folder(folder, imaging=None, backend_options=None)[source]#
classmethod create_zarr(folder, rois, imaging, imaging_attributes, backend_options)[source]#
classmethod load_from_zarr(folder, imaging=None, backend_options=None)[source]#
set_temporary_imaging(imaging, check_dtype=True)[source]#

Set a temporary imaging (e.g. a cached/loaded copy) without persisting it.

Parameters:
  • imaging (BaseImaging) – The imaging object.

  • check_dtype (bool) – Whether to validate dtype match.

set_roi_property(key, values, ids=None, missing_value=None, save=True)[source]#

Set a property on the internal ROIs copy, optionally persisting to disk.

Parameters:
  • key (str) – Property name.

  • values (list | ndarray | tuple) – Property values.

  • ids (list | ndarray | tuple | None) – Subset of ROI ids to set. If None, set for all.

  • missing_value (Any) – Fill value for ids not in ids.

  • save (bool) – Whether to persist (binary_folder / zarr only).

Return type:

None

get_roi_property(key, ids=None)[source]#

Get a property from the internal ROIs copy.

Return type:

ndarray

save_as(format='memory', folder=None, backend_options=None)[source]#

Save the analyzer to a different backend.

Parameters:
  • format ("memory" | "binary_folder" | "zarr") – Target backend.

  • folder (str | Path | None) – Required for non-memory formats.

  • backend_options (dict | None) – Backend-specific options.

Return type:

RoiAnalyzer

select_rois(roi_ids, format='memory', folder=None)[source]#

Create a new RoiAnalyzer with a subset of ROIs.

Extensions are filtered to the selected ROI ids.

Parameters:
  • roi_ids (array-like) – ROI ids to keep.

  • format (str) – Target backend.

  • folder (str | Path | None) – Required for non-memory formats.

Return type:

RoiAnalyzer

remove_rois(remove_roi_ids, format='memory', folder=None)[source]#

Create a new RoiAnalyzer with some ROIs removed.

Parameters:
  • remove_roi_ids (array-like) – ROI ids to remove.

  • format (str) – Target backend.

  • folder (str | Path | None) – Required for non-memory formats.

Return type:

RoiAnalyzer

copy()[source]#

Create an in-memory copy.

Return type:

RoiAnalyzer

property imaging: BaseImaging#
property roi_ids: ndarray#
property sampling_frequency: float#
property shape: tuple#
property num_planes: int#
has_imaging()[source]#
Return type:

bool

has_temporary_imaging()[source]#
Return type:

bool

get_num_rois()[source]#
Return type:

int

get_num_epochs()[source]#
Return type:

int

get_num_samples(epoch_index=None)[source]#
Return type:

int

get_total_samples()[source]#
Return type:

int

get_total_duration()[source]#
Return type:

float

get_dtype()[source]#
is_read_only()[source]#
Return type:

bool

get_rois_provenance()[source]#

Get the original rois object if possible, otherwise None.

compute(input, save=True, extension_params=None, verbose=False, **kwargs)[source]#

Compute one or several extensions.

Parameters:
  • input (str | dict | list) – Extension name (str), dict of {name: params}, or list of names.

  • save (bool, default: True) – Whether to persist computed extensions.

  • extension_params (dict | None) – Per-extension params when input is a list.

  • verbose (bool) – Print progress.

  • **kwargs – Passed to the extension’s set_params (if str) or as job_kwargs.

Returns:

The extension instance if input is a string, None otherwise.

Return type:

AnalyzerExtension | None

compute_one_extension(extension_name, save=True, verbose=False, **kwargs)[source]#

Compute a single extension.

Automatically deletes dependent extensions to keep data coherent.

Return type:

AnalyzerExtension

compute_several_extensions(extensions, save=True, verbose=False, **job_kwargs)[source]#

Compute several extensions respecting dependency order.

Parameters:
  • extensions (dict) – Mapping of extension_name -> params dict.

  • save (bool) – Whether to persist.

  • verbose (bool) – Print progress.

  • **job_kwargs – Parallelization kwargs.

get_saved_extension_names()[source]#

Get extension names saved on disk (without loading data).

Return type:

list[str]

get_extension(extension_name)[source]#

Get an extension, auto-loading from disk if needed. Returns None if not computed.

Return type:

AnalyzerExtension | None

load_extension(extension_name)[source]#

Load an extension from disk into memory.

Return type:

AnalyzerExtension | None

load_all_saved_extension()[source]#

Load all saved extensions into memory.

delete_extension(extension_name)[source]#

Delete an extension from memory and from disk.

Return type:

None

get_loaded_extension_names()[source]#

Return names of currently loaded extensions.

Return type:

list[str]

has_extension(extension_name)[source]#

Check if an extension exists (in memory or on disk).

Return type:

bool

get_computable_extensions()[source]#

List all registered extension names.

Return type:

list[str]

get_default_extension_params(extension_name)[source]#

Get default params for an extension.

Return type:

dict

photon_mosaic.core.roianalyzer.register_result_extension(extension_class)[source]#

Register an AnalyzerExtension subclass so it can be discovered by name.

photon_mosaic.core.roianalyzer.get_extension_class(extension_name, auto_import=True)[source]#

Get extension class by name, auto-importing if needed.

photon_mosaic.core.roianalyzer.get_available_analyzer_extensions()[source]#

Get all built-in extension names.

Return type:

list[str]

photon_mosaic.core.roianalyzer.get_default_analyzer_extension_params(extension_name)[source]#

Get the default params for an extension.

Return type:

dict

class photon_mosaic.core.roianalyzer.AnalyzerExtension(roi_analyzer)[source]#

Base class for RoiAnalyzer extensions.

Subclasses must set extension_name and implement:

  • _set_params(**params) — validate / clean params

  • _run(**kwargs) — populate self.data

  • _select_extension_data(roi_ids) — filter data to a subset

  • _get_data() — return the computed result

Optionally (for pipeline extensions):

  • _get_pipeline_nodes() — if use_nodepipeline = True

Attributes:
extension_name
folder
format
nodepipeline_variables
roi_analyzer

Methods

copy(new_roi_analyzer[, roi_ids])

Copy this extension to a new RoiAnalyzer, optionally filtering to roi_ids.

delete()

Delete extension from disk and clear in-memory data.

reset()

Reset extension: clear data and recreate empty folder.

set_params([save])

Set parameters and optionally persist.

function_factory

get_any_dependencies

get_data

get_default_params

get_optional_dependencies

get_pipeline_nodes

get_required_dependencies

load

load_data

load_params

load_run_info

run

save

set_data

extension_name: str | None = None#
depend_on: list[str] = []#
need_imaging = False#
use_nodepipeline = False#
nodepipeline_variables: list[str] | None = None#
need_job_kwargs = False#
need_backward_compatibility_on_load = False#
property roi_analyzer#
property format#
property folder#
classmethod get_required_dependencies(**params)[source]#
classmethod get_optional_dependencies(**params)[source]#
classmethod get_any_dependencies(**params)[source]#
classmethod get_default_params()[source]#
classmethod load(roi_analyzer)[source]#
load_run_info()[source]#
load_params()[source]#
load_data()[source]#
run(save=True, **kwargs)[source]#
save()[source]#
copy(new_roi_analyzer, roi_ids=None)[source]#

Copy this extension to a new RoiAnalyzer, optionally filtering to roi_ids.

delete()[source]#

Delete extension from disk and clear in-memory data.

reset()[source]#

Reset extension: clear data and recreate empty folder.

set_params(save=True, **params)[source]#

Set parameters and optionally persist.

get_data(*args, **kwargs)[source]#
set_data(name, value)[source]#
get_pipeline_nodes()[source]#
classmethod function_factory()[source]#