Optical Physiology#

Imaging#

Base Imaging#

Author: Ben Dichter.

class BaseImagingExtractorInterface(verbose: bool = False, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries', metadata_key: str | None = None, **source_data)[source]#

Bases: BaseExtractorInterface

Parent class for all ImagingExtractorInterfaces.

keywords: tuple[str] = ('ophys', 'optical electrophysiology', 'fluorescence', 'microscopy', 'two photon', 'one photon', 'voltage imaging', 'calcium imaging')#
get_metadata_schema() → dict[source]#

Retrieve the metadata schema for the optical physiology (Ophys) data.

Returns:

The metadata schema dictionary containing definitions for Device, ImagingPlane, and either OnePhotonSeries or TwoPhotonSeries based on the photon_series_type.

Return type:

dict

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Retrieve the metadata for the imaging data.

Parameters:

use_new_metadata_format (bool, default: False) – When False, returns the old list-based metadata format (backward compatible). When True, returns only NWBFile-level metadata (session_description, identifier, etc.) without ophys keys. Ophys defaults are filled by add_imaging_to_nwbfile() internally.

Returns:

Dictionary containing metadata. When use_new_metadata_format is False, includes device information, imaging plane details, and photon series configuration. When True, includes only NWBFile basics.

Return type:

DeepDict

get_original_timestamps() → ndarray[source]#

Retrieve the original unaltered timestamps for the data in this interface.

This function should retrieve the data on-demand by re-initializing the IO.

Returns:

timestamps – The timestamps for the data stream.

Return type:

numpy.ndarray

get_timestamps() → ndarray[source]#

Retrieve the timestamps for the data in this interface.

Returns:

timestamps – The timestamps for the data stream.

Return type:

numpy.ndarray

set_aligned_timestamps(aligned_timestamps: ndarray)[source]#

Replace all timestamps for this interface with those aligned to the common session start time.

Must be in units seconds relative to the common ‘session_start_time’.

Parameters:

aligned_timestamps (numpy.ndarray) – The synchronized timestamps for data in this interface.

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None, *args, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries', photon_series_index: int = 0, parent_container: Literal['acquisition', 'processing/ophys'] = 'acquisition', stub_test: bool = False, always_write_timestamps: bool = False, iterator_type: str | None = 'v2', iterator_options: dict | None = None, stub_samples: int = 100)[source]#

Add imaging data to the NWB file

Parameters:

  • nwbfile (NWBFile) – The NWB file where the imaging data will be added.

  • metadata (dict, optional) – Metadata for the NWBFile, by default None.

  • photon_series_type ({“TwoPhotonSeries”, “OnePhotonSeries”}, optional) – The type of photon series to be added, by default “TwoPhotonSeries”.

  • photon_series_index (int, optional) – The index of the photon series in the provided imaging data, by default 0.

  • parent_container ({“acquisition”, “processing/ophys”}, optional) – Specifies the parent container to which the photon series should be added, either as part of “acquisition” or under the “processing/ophys” module, by default “acquisition”.

  • stub_test (bool, optional) – If True, only writes a small subset of frames for testing purposes, by default False.

  • always_write_timestamps (bool, optional) – Whether to always write timestamps, by default False.

  • iterator_type ({“v2”, None}, default: “v2”) – The type of iterator for chunked data writing. ‘v2’: Uses iterative write with control over chunking and progress bars. None: Loads all data into memory before writing (not recommended for large datasets).

  • iterator_options (dict, optional) – Options for controlling the iterative write process (buffer size, progress bars). See the pynwb tutorial on iterative write for more information on chunked data writing.

    Note: To configure chunk size and compression, use the backend configuration system via get_default_backend_configuration() and configure_backend() after calling this method. See the backend configuration documentation for details.

  • stub_samples (int, default: 100) – The number of samples (frames) to use for testing.

Bruker Tiff Imaging#

class BrukerTiffMultiPlaneConverter(folder_path: Annotated[pathlib._local.Path, PathType(path_type='dir')], plane_separation_type: Literal['disjoint', 'contiguous'], verbose: bool = False)[source]#

Bases: BaseDataInterface

Converter class for Bruker imaging data with multiple channels and multiple planes.

Initializes the data interfaces for Bruker volumetric imaging data stream.

Parameters:

  • folder_path (DirectoryPath) – The path to the folder that contains the Bruker TIF image files (.ome.tif) and configuration files (.xml, .env).

  • plane_separation_type ({‘contiguous’, ‘disjoint’}) – Defines how to write volumetric imaging data. Use ‘contiguous’ to create the volumetric two photon series, and ‘disjoint’ to create separate imaging plane and two photon series for each plane.

  • verbose (bool, default: False) – Controls verbosity.

display_name: str | None = 'Bruker TIFF Imaging (multiple channels, multiple planes)'#
keywords: tuple[str] = ('ophys', 'optical electrophysiology', 'fluorescence', 'microscopy', 'two photon', 'one photon', 'voltage imaging', 'calcium imaging')#
associated_suffixes: tuple[str] = ('.ome', '.tif', '.xml', '.env')#
info: str | None = 'Interface for handling all channels and all planes of Bruker imaging data.'#
classmethod get_source_schema()[source]#

Infer the JSON schema for the source_data from the method signature (annotation typing).

Returns:

The JSON schema for the source_data.

Return type:

dict

get_metadata() → DeepDict[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

add_to_nwbfile(nwbfile: NWBFile, metadata, stub_test: bool = False, stub_samples: int = 100)[source]#

Add data from multiple data interfaces to the specified NWBFile.

Parameters:

  • nwbfile (NWBFile) – The NWBFile object to which the data will be added.

  • metadata (dict) – Metadata dictionary containing information to describe the data being added to the NWB file.

  • stub_test (bool, optional) – If True, only a subset of the data (up to stub_samples) will be added for testing purposes. Default is False.

  • stub_samples (int, default: 100) – The number of samples (frames) to use for testing.

class BrukerTiffSinglePlaneConverter(folder_path: Annotated[pathlib._local.Path, PathType(path_type='dir')], verbose: bool = False)[source]#

Bases: BaseDataInterface

Primary data interface class for converting Bruker imaging data with multiple channels and a single plane.

Initializes the data interfaces for Bruker imaging data stream.

Parameters:

  • folder_path (DirectoryPath) – The path to the folder that contains the Bruker TIF image files (.ome.tif) and configuration files (.xml, .env).

  • verbose (bool, default: False) – Controls verbosity.

display_name: str | None = 'Bruker TIFF Imaging (multiple channels, single plane)'#
keywords: tuple[str] = ('ophys', 'optical electrophysiology', 'fluorescence', 'microscopy', 'two photon', 'one photon', 'voltage imaging', 'calcium imaging')#
associated_suffixes: tuple[str] = ('.ome', '.tif', '.xml', '.env')#
info: str | None = 'Interface for handling multiple channels of a single plane of Bruker imaging data.'#
classmethod get_source_schema()[source]#

Infer the JSON schema for the source_data from the method signature (annotation typing).

Returns:

The JSON schema for the source_data.

Return type:

dict

get_metadata() → DeepDict[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

add_to_nwbfile(nwbfile: NWBFile, metadata, stub_test: bool = False, stub_samples: int = 100)[source]#

Add data from all instantiated data interfaces to the provided NWBFile.

Parameters:

  • nwbfile (NWBFile) – The NWBFile object to which the data will be added.

  • metadata (dict) – Metadata dictionary containing information about the data to be added.

  • stub_test (bool, optional) – If True, only a subset of the data (defined by stub_samples) will be added for testing purposes, by default False.

  • stub_samples (int, default: 100) – The number of samples (frames) to use for testing.

Femtonics Imaging#

Femtonics imaging interface for NeuroConv.

class FemtonicsImagingInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *args, session_name: str | None = None, munit_name: str | None = None, channel_name: str | None = None, verbose: bool = False, metadata_key: str | None = None)[source]#

Bases: BaseImagingExtractorInterface

Data interface for Femtonics imaging data (.mesc files).

This interface handles Femtonics two-photon microscopy data stored in MESc (Measurement Session Container) format, which is an HDF5-based file format containing imaging data, experiment metadata, scan parameters, and hardware configuration.

Initialize the FemtonicsImagingInterface.

Parameters:

  • file_path (FilePath) – Path to the .mesc file.

  • metadata_key (str, optional) – # TODO: improve docstring once #1653 (ophys metadata documentation) is merged Metadata key for this interface. When None, defaults to a key derived from session_name, munit_name, and channel_name.

  • session_name (str, optional) – Name of the MSession to use (e.g., “MSession_0”, “MSession_1”). If None, and there is only one session, then the first available session will be selected automatically. Otherwise this to be specified with the desired session. In Femtonics MESc files, an MSession (“Measurement Session”) represents a single experimental session, which may contain one or more MUnits (imaging acquisitions or experiments). MSessions are typically named as “MSession_0”, “MSession_1”, etc…

  • munit_name (str, optional) – Name of the MUnit within the specified session (e.g., “MUnit_0”, “MUnit_1”). If None, and there is only one session, then the first available session will be selected automatically. Otherwise this to be specified with the desired session.

    In Femtonics MESc files, an MUnit (“Measurement Unit”) represents a single imaging acquisition or experiment, including all associated imaging data and metadata. A single MSession can contain multiple MUnits, each corresponding to a separate imaging run/experiment performed during the session. MUnits are named as “MUnit_0”, “MUnit_1”, etc. within each session.

  • channel_name (str, optional) – Name of the channel to extract (e.g., ‘UG’, ‘UR’). If multiple channels are available and no channel is specified, an error will be raised. If only one channel is available, it will be used automatically.

  • verbose (bool, optional) – Whether to print verbose output. Default is False.

display_name: str | None = 'Femtonics Imaging'#
associated_suffixes: tuple[str] = ('.mesc',)#
info: str | None = 'Interface for Femtonics two-photon imaging data in MESc format.'#
classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Extract metadata specific to Femtonics imaging data.

Parameters:

use_new_metadata_format (bool, default: False) – When False, returns the old list-based metadata format (backward compatible). When True, returns dict-based metadata with Femtonics provenance.

Returns:

Dictionary containing extracted metadata including device information, optical channels, imaging plane details, and acquisition parameters.

Return type:

DeepDict

classmethod get_available_sessions(file_path: Annotated[Path, PathType(path_type=file)]) → list[str][source]#

Get list of available session keys in the file.

Parameters:

file_path (str or Path) – Path to the .mesc file.

Returns:

List of available session keys.

Return type:

list of str

classmethod get_available_munits(file_path: Annotated[Path, PathType(path_type=file)], session_name: str = None) → list[str][source]#

Get list of available unit keys in the specified session.

Parameters:

  • file_path (str or Path) – Path to the .mesc file.

  • session_name (str, optional) – Name of the MSession to use (e.g., “MSession_0”). If None and only one session exists, uses that session automatically. If multiple sessions exist, raises an error.

Returns:

List of available unit keys.

Return type:

list of str

classmethod get_available_channels(file_path: Annotated[Path, PathType(path_type=file)], session_name: str = None, munit_name: str = None) → list[str][source]#

Get available channels in the specified session/unit combination.

Parameters:

  • file_path (str or Path) – Path to the .mesc file.

  • session_name (str, optional) – Name of the MSession to use (e.g., “MSession_0”). If None and only one session exists, uses that session automatically. If multiple sessions exist, raises an error.

  • munit_name (str, optional) – Name of the MUnit within the session (e.g., “MUnit_0”). If None and only one unit exists in the session, uses that unit automatically. If multiple units exist, raises an error.

Returns:

List of available channel names.

Return type:

list of str

HDF5 Imaging#

class Hdf5ImagingInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *args, mov_field: str = 'mov', sampling_frequency: float | None = None, start_time: float | None = None, metadata: dict | None = None, channel_names: list | numpy.ndarray | None = None, verbose: bool = False, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries', metadata_key: str | None = None)[source]#

Bases: BaseImagingExtractorInterface

Interface for HDF5 imaging data.

Parameters:

  • file_path (FilePath) – Path to .h5 or .hdf5 file.

  • mov_field (str, default: ‘mov’)

  • sampling_frequency (float, optional)

  • start_time (float, optional)

  • metadata (dict, optional)

  • channel_names (list of str, optional)

  • verbose (bool, default: False)

  • metadata_key (str, optional) – # TODO: improve docstring once #1653 (ophys metadata documentation) is merged Metadata key for this interface. When None, defaults to “hdf5_imaging”.

display_name: str | None = 'HDF5 Imaging'#
associated_suffixes: tuple[str] = ('.h5', '.hdf5')#
info: str | None = 'Interface for HDF5 imaging data.'#
classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

Inscopix Imaging#

is_file_multiplane(file_path) → bool[source]#

Return whether an .isxd file is a multiplane recording.

Multiplane recordings are not yet supported by the interface and are rejected; the single-plane case (also the default when the plane count cannot be determined) loads normally.

class InscopixImagingInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], verbose: bool = False, metadata_key: str | None = None, **kwargs)[source]#

Bases: BaseImagingExtractorInterface

Data Interface for Inscopix Imaging Extractor.

Parameters:

  • file_path (FilePath) – Path to the .isxd Inscopix file.

  • verbose (bool, optional) – If True, outputs additional information during processing.

  • metadata_key (str, optional) – # TODO: improve docstring once #1653 (ophys metadata documentation) is merged Metadata key for this interface. When None, defaults to “inscopix_imaging”.

  • **kwargs (dict, optional) – Additional keyword arguments passed to the parent class.

Raises:

NotImplementedError – If the file is a multiplane recording, which roiextractors cannot yet separate into per-plane series.

display_name: str | None = 'Inscopix Imaging'#
associated_suffixes: tuple[str] = ('.isxd',)#
info: str | None = 'Interface for handling Inscopix imaging data.'#
classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Retrieve the metadata for the Inscopix imaging data.

Parameters:

use_new_metadata_format (bool, default: False) – When False, returns the old list-based metadata format (backward compatible). When True, returns dict-based metadata with Inscopix provenance.

Returns:

Dictionary containing metadata including device information, imaging plane details, photon series configuration, and Inscopix-specific acquisition parameters.

Return type:

DeepDict

add_to_nwbfile(nwbfile, metadata: dict | None = None, **kwargs)[source]#

Add the Inscopix data to the NWB file.

Parameters:

  • nwbfile (NWBFile) – NWB file to add the data to.

  • metadata (dict, optional) – Metadata dictionary. If None, will be generated dynamically with OnePhotonSeries.

  • **kwargs – Additional keyword arguments passed to the parent add_to_nwbfile method.

  • # TODO (add logic for determining whether the microscope is nVista 2P and change photon_series_type to TwoPhotonSeries accordingly.)

MicroManager Tiff Imaging#

class MicroManagerTiffImagingInterface(folder_path: Annotated[pathlib._local.Path, PathType(path_type='dir')], *args, verbose: bool = False, metadata_key: str | None = None)[source]#

Bases: BaseImagingExtractorInterface

Data Interface for MicroManagerTiffImagingExtractor.

Data Interface for MicroManagerTiffImagingExtractor.

Parameters:

  • folder_path (DirectoryPath) – The folder path that contains the OME-TIF image files (.ome.tif files) and the ‘DisplaySettings’ JSON file.

  • verbose (bool, default: False)

  • metadata_key (str, optional) – Metadata key for this interface. When None, defaults to “micromanager_imaging”.

display_name: str | None = 'Micro-Manager TIFF Imaging'#
associated_suffixes: tuple[str] = ('.ome', '.tif', '.json')#
info: str | None = 'Interface for Micro-Manager TIFF imaging data.'#
classmethod get_source_schema() → dict[source]#

Get the source schema for the Micro-Manager TIFF imaging interface.

Returns:

The schema dictionary containing input parameters and descriptions for initializing the Micro-Manager TIFF interface.

Return type:

dict

classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Get metadata for the Micro-Manager TIFF imaging data.

Parameters:

use_new_metadata_format (bool, default: False) – When False, returns the old list-based metadata format (backward compatible). When True, returns dict-based metadata with Micro-Manager provenance.

Returns:

Dictionary containing metadata including session start time, imaging plane details, and two-photon series configuration.

Return type:

dict

Miniscope Imaging#

class MiniscopeConverter(folder_path: Annotated[pathlib._local.Path, PathType(path_type='dir')], user_configuration_file_path: Annotated[pathlib._local.Path, PathType(path_type='file')] | None = None, verbose: bool = False)[source]#

Bases: ConverterPipe

Bundle Miniscope imaging and optional behavior recordings into a single NWB conversion.

Instantiate Miniscope imaging (and optional behavior) interfaces.

Parameters:

  • folder_path (DirectoryPath) – Root data directory containing the Miniscope acquisition data. This should be the base directory where the configured directory structure sits (e.g. “dataDirectory” in the User Config).

    • With config file: The top-level directory containing the hierarchy defined by ‘directoryStructure’

    • Without config file (legacy): The directory containing timestamp subfolders with Miniscope/ folders

    IMPORTANT: The ‘dataDirectory’ field in the User Config file is ignored. Always pass the actual data root directory as folder_path.

  • user_configuration_file_path (FilePath, optional) – Path to the Miniscope “User Config” JSON file (the Miniscope documentation and source code refer to this artifact as UserConfigFile.json). When provided, the converter uses the configuration to discover Miniscope device folders and session hierarchy, supporting multiple simultaneous Miniscopes and custom directory layouts. If omitted, the converter falls back to the legacy layout (see Notes).

  • verbose (bool, default: False) – Controls verbosity.

Notes

The Miniscope acquisition software saves a “User Config” JSON that includes:

  • dataDirectory and directoryStructure: ordered keys (e.g., researcher, experiment, animal, date, time) used to build the on-disk folder hierarchy.

  • devices[miniscopes]: mapping of Miniscope device names (e.g., "ACC_miniscope2") to their acquisition parameters.

Example 1 - Dual Miniscope with 5-level hierarchy:

{
    "dataDirectory": "./dual_miniscope_data",
    "directoryStructure": [
        "researcherName",
        "experimentName",
        "animalName",
        "date",
        "time"
    ],
    "researcherName": "researcher_name",
    "experimentName": "experiment_name",
    "animalName": "animal_name",
    "devices": {
        "miniscopes": {
            "ACC_miniscope2": {...},
            "HPC_miniscope1": {...}
        }
    }
}

This produces a folder tree such as:

dual_miniscope_data/
├── researcher_name/
│   └── experiment_name/
│       └── animal_name/
│           └── 2025_06_12/
│               ├── 15_15_04/
│               │   ├── ACC_miniscope2/
│               │   │   ├── 0.avi
│               │   │   ├── 1.avi
│               │   │   ├── 2.avi
│               │   │   ├── metaData.json
│               │   │   └── timeStamps.csv
│               │   ├── HPC_miniscope1/
│               │   │   ├── 0.avi
│               │   │   ├── 1.avi
│               │   │   ├── 2.avi
│               │   │   ├── metaData.json
│               │   │   └── timeStamps.csv
│               │   └── metaData.json
│               └── 15_26_31/
│                   ├── ACC_miniscope2/
│                   │   ├── 0.avi
│                   │   ├── 1.avi
│                   │   ├── metaData.json
│                   │   └── timeStamps.csv
│                   ├── HPC_miniscope1/
│                   │   ├── 0.avi
│                   │   ├── 1.avi
│                   │   ├── metaData.json
│                   │   └── timeStamps.csv
│                   └── metaData.json

Example 2 - Single Miniscope with 3-level hierarchy:

{
    "dataDirectory": "./miniscope_recordings",
    "directoryStructure": [
        "animalName",
        "date",
        "time"
    ],
    "animalName": "mouse_001",
    "devices": {
        "miniscopes": {
            "Miniscope": {...}
        }
    }
}

Which yields:

miniscope_recordings/
└── mouse_001/
    └── 2022_09_19/
        └── 09_18_41/
            ├── Miniscope/
            │   ├── 0.avi
            │   ├── 1.avi
            │   ├── 2.avi
            │   ├── metaData.json
            │   └── timeStamps.csv
            └── metaData.json

The converter walks the directory structure, creating one imaging interface per Miniscope device and preserving their individual timestamps. Behavior video is added only if BehavCam_ folders (with metadata) are present. For devices recorded multiple times, each timestamp folder is instantiated as a separate interface labeled SegmentXX (with zero padding based on the total number of segments) so repeated recordings remain distinct while sharing a common device definition.

Backwards compatibility: If user_configuration_file_path is not provided, the converter falls back to the original “Tye Lab” layout that expects timestamp subfolders with Miniscope/ and optional BehavCam_*/ directories (each holding their own metaData.json and timeStamps.csv files):

main_folder/
├── timestamp_one/
│   ├── Miniscope/
│   │   ├── 0.avi
│   │   ├── 1.avi
│   │   ├── metaData.json
│   │   └── timeStamps.csv
│   ├── BehavCam_*/
│   │   ├── 0.avi
│   │   ├── metaData.json
│   │   └── timeStamps.csv
│   └── metaData.json
└── timestamp_two/
    └── ...

Use the configuration file whenever possible to describe other layouts explicitly.

display_name: str | None = 'Miniscope Imaging and Video'#
keywords: tuple[str] = ('ophys', 'optical electrophysiology', 'fluorescence', 'microscopy', 'two photon', 'one photon', 'voltage imaging', 'calcium imaging', 'video', 'miniscope', 'IMU', 'orientation', 'quaternion', 'BNO055')#
associated_suffixes: tuple[str] = ('.avi', '.csv', '.json', '.avi', '.csv')#
info: str | None = 'Converter for handling both imaging and video recordings from Miniscope.'#
classmethod get_source_schema()[source]#

Compile input schemas from each of the data interface classes.

Returns:

The compiled source schema from all data interface classes.

Return type:

dict

get_metadata()[source]#

Auto-fill as much of the metadata as possible. Must comply with metadata schema.

Returns:

The metadata dictionary containing auto-filled metadata from all interfaces.

Return type:

DeepDict

get_conversion_options_schema() → dict[source]#

Allow standard stub options alongside per-interface schemas.

add_to_nwbfile(nwbfile: NWBFile, metadata, conversion_options: dict | None = None, stub_test: bool = False, stub_samples: int = 100)[source]#

Add Miniscope interfaces to the provided NWBFile.

run_conversion(nwbfile_path: str | None = None, nwbfile: NWBFile | None = None, metadata: dict | None = None, overwrite: bool = False, stub_test: bool = False, stub_samples: int = 100, **kwargs) → None[source]#

Run the NWB conversion process for the instantiated data interfaces.

Parameters:

  • nwbfile_path (str, optional) – Path where the NWBFile will be written. If None, the file is handled in-memory.

  • nwbfile (NWBFile, optional) – An in-memory NWBFile object to be written to the file. If None, a new NWBFile is created.

  • metadata (dict, optional) – Metadata dictionary with information to create the NWBFile. If None, metadata is auto-generated.

  • overwrite (bool, optional) – If True, overwrites the existing NWBFile at nwbfile_path. If False (default), data is appended.

  • stub_test (bool, optional) – If True, only a subset of the data (up to stub_samples) is written for testing purposes, by default False.

  • stub_samples (int, optional) – The number of samples (frames) to include in the subset if stub_test is True, by default 100.

  • **kwargs – Additional keyword arguments passed to the parent NWBConverter.run_conversion method.

Sbx Imaging#

class SbxImagingInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *args, sampling_frequency: float | None = None, verbose: bool = False, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries', metadata_key: str | None = None)[source]#

Bases: BaseImagingExtractorInterface

Data Interface for SbxImagingExtractor.

Parameters:

  • file_path (FilePath) – Path to .sbx file.

  • sampling_frequency (float, optional)

  • verbose (bool, default: False)

  • metadata_key (str, optional) – # TODO: improve docstring once #1653 (ophys metadata documentation) is merged Metadata key for this interface. When None, defaults to “sbx_imaging”.

display_name: str | None = 'Scanbox Imaging'#
associated_suffixes: tuple[str] = ('.sbx',)#
info: str | None = 'Interface for Scanbox imaging data.'#
classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Get metadata for the Scanbox imaging data.

Parameters:

use_new_metadata_format (bool, default: False) – When False, returns the old list-based metadata format (backward compatible). When True, returns dict-based metadata with Scanbox device provenance.

Returns:

Dictionary containing metadata including device information and imaging details specific to the Scanbox system.

Return type:

dict

ScanImage Imaging#

class ScanImageImagingInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')] | None = None, *args, channel_name: str | None = None, slice_sample: int | None = None, plane_index: int | None = None, file_paths: list[Annotated[pathlib._local.Path, PathType(path_type='file')]] | None = None, interleave_slice_samples: bool | None = None, verbose: bool = False, metadata_key: str | None = None)[source]#

Bases: BaseImagingExtractorInterface

Interface for reading TIFF files produced via ScanImage software.

This interface is designed to handle the structure of ScanImage TIFF files, which can contain multi-channel and both planar and volumetric data. It supports both single-file and multi-file datasets generated by ScanImage in various acquisition modes (grab, focus, loop).

ScanImage is a software package for controlling laser scanning microscopes, particularly for two-photon and multi-photon imaging. The interface extracts imaging data and metadata from ScanImage TIFF files and converts them to NWB format.

Key features:

  • Handles multi-channel data with channel selection

  • Supports volumetric (multi-plane) imaging data

  • Automatically detects and loads multi-file datasets based on ScanImage naming conventions

  • Extracts and provides access to ScanImage metadata

  • Efficiently retrieves frames using lazy loading

  • Handles flyback frames in volumetric data

Parameters:

  • file_path (FilePath, optional) – Path to the ScanImage TIFF file. If this is part of a multi-file series, this should be the first file. Either file_path or file_paths must be provided.

  • metadata_key (str, optional) – Metadata key for this interface. When None, defaults to a key derived from channel_name and plane_index (e.g., scan_image_imaging_channel_1_plane_0).

  • channel_name (str, optional) – Name of the channel to extract (e.g., “Channel 1”, “Channel 2”).

    • If None and only one channel is available, that channel will be used.

    • If None and multiple channels are available, an error will be raised.

    • Use get_available_channels(file_path) to see available channels before creating the interface.

  • slice_sample (int, optional) – Controls how to handle multiple frames per slice in volumetric data: ScanImage data can contain multiple frames for a single plane. Use this to select a specific frame from each slice. if None, this will throw an error. Select a slice sample or set interleave_slice_samples to True to interleave all the slice samples as separate volumes/samples. Note that this will scramble the acquisition order of the frames. This parameter has no effect when frames_per_slice = 1.

  • plane_index (int, optional) – Must be between 0 and num_planes-1. Used to extract a specific plane from volumetric data. When provided:

    • The resulting extractor will be planar

    • Each sample will contain only data for the specified plane

    • This parameter has no effect on planar (non-volumetric) data.

  • file_paths (list[Path | str], optional) – List of file paths to use. This is an escape value that can be used in case the automatic file detection doesn’t work correctly and can be used to override the automatic file detection. This is useful when:

    • Automatic detection doesn’t work correctly

    • You need to specify a custom subset of files

    • You need to control the exact order of files

    The file paths must be provided in the temporal order of the frames in the dataset.

  • interleave_slice_samples (bool, optional) – Controls whether to interleave all slice samples as separate time points when frames_per_slice > 1:

    • If True: Interleaves all slice samples as separate time points, increasing the effective

    number of samples by frames_per_slice. This treats each slice_sample as a distinct sample. - If False: Requires a specific slice_sample to be provided when frames_per_slice > 1. - This parameter has no effect when frames_per_slice = 1 or when slice_sample is provided. - Default is False.

  • verbose (bool, default: False) – If True, will print detailed information about the interface initialization process.

display_name: str | None = 'ScanImage Imaging'#
associated_suffixes: tuple[str] = ('.tif', '.tiff')#
info: str | None = 'Interface for ScanImage TIFF files.'#
classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Get metadata for the ScanImage imaging data.

Parameters:

use_new_metadata_format (bool, default: False) – When False, returns the old list-based metadata format (backward compatible). When True, returns dict-based metadata with ScanImage provenance.

Returns:

The metadata dictionary containing imaging metadata from the ScanImage files. This includes: - Session start time extracted from the ScanImage file - Device information for the microscope - Optical channel configuration - Imaging plane details including grid spacing and origin coordinates if available - Photon series metadata with scan line rate and other acquisition parameters

Return type:

DeepDict

static get_scanimage_version(file_path: Path | str) → int[source]#

Extract the ScanImage version from a BigTIFF file without validation.

This method reads the binary header of the TIFF file to determine the ScanImage version that produced it. It supports ScanImage versions 3, 4, and 5.

Parameters:

file_path (Path | str) – Path to the ScanImage TIFF file

Returns:

ScanImage version number (3, 4, or 5)

Return type:

int

static get_available_channels(file_path: Path | str) → list[str][source]#

Get the channel names available in a ScanImage TIFF file.

This static method extracts the channel names from a ScanImage TIFF file without needing to create an interface instance. This is useful for determining which channels are available before creating an interface.

Parameters:

file_path (Path | str) – Path to the ScanImage TIFF file.

Returns:

List of channel names available in the file (e.g., [“Channel 1”, “Channel 2”]).

Return type:

list[str]

static get_available_planes(file_path: Path | str) → list[str][source]#

Get the available plane names from a ScanImage TIFF file.

This static method determines the number of planes (Z-slices) in a volumetric ScanImage dataset without needing to create an interface instance. This is useful for determining which planes are available before creating an interface.

Parameters:

file_path (Path | str) – Path to the ScanImage TIFF file.

Returns:

List of plane names available in the file. For volumetric data, this will be a list of strings representing plane indices (e.g., [“0”, “1”, “2”]).

Return type:

list[str]

class ScanImageLegacyImagingInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *args, fallback_sampling_frequency: float | None = None, verbose: bool = False, metadata_key: str | None = None)[source]#

Bases: BaseImagingExtractorInterface

Interface for reading TIFF files produced via ScanImage v3.8.

DataInterface for reading Tiff files that are generated by ScanImage v3.8. This interface extracts the metadata from the exif of the tiff file.

Parameters:

  • file_path (FilePath) – Path to tiff file.

  • fallback_sampling_frequency (float, optional) – The sampling frequency can usually be extracted from the scanimage metadata in exif:ImageDescription:state.acq.frameRate. If not, use this.

  • metadata_key (str, optional) – Metadata key for this interface. When None, defaults to “scan_image_legacy_imaging”.

display_name: str | None = 'ScanImage Imaging'#
associated_suffixes: tuple[str] = ('.tif',)#
info: str | None = 'Interface for ScanImage v3.8 TIFF files.'#
classmethod get_source_schema() → dict[source]#

Infer the JSON schema for the source_data from the method signature (annotation typing).

Returns:

The JSON schema for the source_data.

Return type:

dict

classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Get metadata for the ScanImage imaging data.

Parameters:

use_new_metadata_format (bool, default: False) – When False, returns the old list-based metadata format (backward compatible). When True, returns dict-based metadata with ScanImage provenance keyed by metadata_key under Devices, Ophys.ImagingPlanes and Ophys.MicroscopySeries.

Returns:

Dictionary containing metadata including session start time and device information specific to the ScanImage system.

Return type:

DeepDict

get_scanimage_major_version(scanimage_metadata: dict) → str[source]#

Determine the version of ScanImage that produced the TIFF file.

Parameters:

scanimage_metadata (dict) – Dictionary of metadata extracted from a TIFF file produced via ScanImage.

Returns:

version – The version of ScanImage that produced the TIFF file.

Return type:

str

Raises:

ValueError – If the ScanImage version could not be determined from metadata.

Tiff Imaging#

class TiffImagingInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')] | None = None, file_paths: list[Annotated[pathlib._local.Path, PathType(path_type='file')]] | None = None, sampling_frequency: float = None, *args, dimension_order: str = 'ZCT', num_channels: int = 1, channel_name: str | None = None, num_planes: int = 1, verbose: bool = False, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries', metadata_key: str | None = None)[source]#

Bases: BaseImagingExtractorInterface

Interface for multi-page TIFF files.

Initialize reading of TIFF file(s).

Parameters:

  • file_path (FilePath, optional) – Use file_paths instead. Will be removed in April 2026 or later. Path to a single TIFF file. Either file_path or file_paths must be specified.

  • file_paths (list[FilePath], optional) – List of paths to TIFF files. Either file_path or file_paths must be specified.

  • sampling_frequency (float) – The sampling frequency of the imaging data in Hz.

  • dimension_order (str, default: “ZCT”) – Order of dimensions in the TIFF file. For example, “ZCT” means frames are organized as Z-planes, channels, then time.

  • num_channels (int, default: 1) – Number of color channels in the TIFF file. Channel names are automatically generated as string representations of channel indices: “0”, “1”, “2”, etc. For example, if num_channels=3, the available channels will be [“0”, “1”, “2”].

  • channel_name (str, optional) – Name of the channel to extract. Must be a string representation of a channel index (e.g., “0”, “1”, “2”, etc.) corresponding to one of the num_channels. If None and num_channels is 1, defaults to “0”. If None and num_channels > 1, an error will be raised.

  • num_planes (int, default: 1) – Number of z-planes per volume.

  • verbose (bool, default: False) – Whether to print verbose output.

  • photon_series_type ({‘OnePhotonSeries’, ‘TwoPhotonSeries’}, default: “TwoPhotonSeries”) – Type of photon series for NWB conversion.

  • metadata_key (str, optional) – # TODO: improve docstring once #1653 (ophys metadata documentation) is merged Metadata key for this interface. When None, defaults to “tiff_imaging”, or “tiff_imaging_channel_{channel_name}” if channel_name is provided.

Notes

TIFF Frame Terminology#

In this documentation, we use “frame” to refer to each acquired image stored in the TIFF file. This is equivalent to:

  • IFD (Image File Directory) in the TIFF specification - the data structure containing metadata and image data for one image

  • Page in common TIFF libraries like tifffile - a single image within a multi-page TIFF

Each frame represents one 2D image acquisition at a specific combination of depth (Z), channel (C), and timepoint (T). The dimension order determines the sequence in which frames are acquired and stored in the file.

Dimension Order Notes#

This class follows a subset of the OME-TIFF dimension order specification, focusing on the Z (depth), C (channel), and T dimensions. The XY spatial dimensions are assumed to be the first two dimensions of each frame and are not included in the dimension_order parameter.

While we use ‘T’ for compatibility with the OME-TIFF standard, we emphasize that its meaning varies significantly based on position:

  • When T is first (TCZ, TZC): Represents oversampling - multiple samples acquired at each depth or channel:

    • TCZ: T samples per channel at each depth position

    • TZC: T samples per depth position for each channel

  • When T is middle (ZTC, CTZ): Represents repetitions - repeated acquisitions of sub-structures before varying the outer dimension:

    • ZTC: T repetitions of each Z-stack before switching channels

    • CTZ: T repetitions of the full channel set at each depth

  • When T is last (ZCT, CZT): Represents acquisition cycles - complete acquisitions of the entire multi-channel, multi-plane dataset:

    • ZCT: T complete multi-channel volumes where the depth is varied first

    • CZT: T complete multi-channel volumes where the channel is varied first

For more information on OME-TIFF dimension order, see: https://ome-model.readthedocs.io/en/stable/ome-tiff/specification.html

Acquisition Patterns#

ZCT (Depth → Channel → Acquisition Cycles)

Acquire a complete Z-stack for the first channel, then switch to the next channel and acquire its full Z-stack. After all channels are acquired, this constitutes one acquisition cycle. Repeat for T acquisition cycles.

ZTC (Depth → Repetitions → Channel)

Acquire full Z-stacks repeated T times for a single channel, then switch to the next channel and acquired another T repetitions of the full Z-stack for that channel. Repeat the same process for all channels.

CZT (Channel → Depth → Acquisition Cycles)

At the first depth position, acquire all channels sequentially. Move to the next depth and acquire all channels again. After completing all depths, one acquisition cycle is complete. Repeat for T acquisition cycles.

CTZ (Channel → Repetitions → Depth)

At a fixed depth position, acquire all channels, then repeat this channel acquisition T times. Then move to the next depth position and repeat the pattern of T repetitions of all channels.

TCZ (Oversampling → Channel → Depth)

At a fixed depth position, acquire T samples for the first channel, then acquire T samples for the next channel. After oversampling all channels at this depth, move to the next depth position and repeat.

TZC (Oversampling → Depth → Channel)

For a fixed channel, acquire T samples at the first depth, then T samples at the second depth, continuing through all depths. Switch to the next channel and repeat the entire oversampling pattern across depths.

Special Cases#

When data has only a single channel (num_channels=1):

ZCT, ZTC, CZT → ZT: Volumetric time series (complete volumes acquired sequentially)

CTZ, TCZ, TZC → TZ: Plane-by-plane time series (T samples at each depth before moving to next)

When data is planar (num_planes=1):

ZCT, CZT, CTZ → CT: Channel-first acquisition patterns (one full channel sweep after another)

ZTC, TCZ, TZC → TC: Time-first acquisition patterns (full data for one channel and then the next)

When data is both single-channel AND planar:

All dimension orders → T: Simple planar time series (all orderings equivalent)

display_name: str | None = 'TIFF Imaging'#
associated_suffixes: tuple[str] = ('.tif', '.tiff')#
info: str | None = 'Interface for multi-page TIFF files.'#
classmethod get_source_schema() → dict[source]#

Get the source schema for the TIFF imaging interface.

Returns:

The JSON schema for the TIFF imaging interface source data, containing file path and other configuration parameters.

Return type:

dict

classmethod get_extractor_class()[source]#

Get the extractor class for the TIFF imaging interface.

Returns:

MultiTIFFMultiPageExtractor for handling TIFF files.

Return type:

class

Segmentation#

Base Segmentation#

class BaseSegmentationExtractorInterface(verbose: bool = False, metadata_key: str | None = None, **source_data)[source]#

Bases: BaseExtractorInterface

Parent class for all SegmentationExtractorInterfaces.

keywords: tuple[str] = ('segmentation', 'roi', 'cells')#
property roi_ids#

Get all ROI IDs of the segmentation data.

get_metadata_schema() → dict[source]#

Generate the metadata schema for Ophys data, updating required fields and properties.

This method builds upon the base schema and customizes it for Ophys-specific metadata, including required components such as devices, fluorescence data, imaging planes, and two-photon series. It also applies temporary schema adjustments to handle certain use cases until a centralized metadata schema definition is available.

Returns:

A dictionary representing the updated Ophys metadata schema.

Return type:

dict

Notes

  • Ensures that Device and ImageSegmentation are marked as required.

  • Updates various properties, including ensuring arrays for ImagingPlane and TwoPhotonSeries.

  • Adjusts the schema for Fluorescence, including required fields and pattern properties.

  • Adds schema definitions for DfOverF, segmentation images, and summary images.

  • Applies temporary fixes, such as setting additional properties for ImageSegmentation to True.

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

get_original_timestamps() → ndarray[source]#

Retrieve the original unaltered timestamps for the data in this interface.

This function should retrieve the data on-demand by re-initializing the IO.

Returns:

timestamps – The timestamps for the data stream.

Return type:

numpy.ndarray

get_timestamps() → ndarray[source]#

Retrieve the timestamps for the data in this interface.

Returns:

timestamps – The timestamps for the data stream.

Return type:

numpy.ndarray

set_aligned_timestamps(aligned_timestamps: ndarray)[source]#

Replace all timestamps for this interface with those aligned to the common session start time.

Must be in units seconds relative to the common ‘session_start_time’.

Parameters:

aligned_timestamps (numpy.ndarray) – The synchronized timestamps for data in this interface.

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None, *args, stub_test: bool = False, include_background_segmentation: bool = False, include_roi_centroids: bool = True, include_roi_acceptance: bool | None = None, mask_type: Literal['image', 'pixel', 'voxel'] = 'image', plane_segmentation_name: str | None = None, iterator_options: dict | None = None, stub_samples: int = 100, roi_ids_to_add: list[str | int] | None = None)[source]#

Add segmentation data to the NWB file.

Parameters:

  • nwbfile (NWBFile) – The NWBFile to add the plane segmentation to.

  • metadata (dict, optional) – The metadata for the interface

  • stub_test (bool, default: False)

  • include_background_segmentation (bool, default: False) – Whether to include the background plane segmentation and fluorescence traces in the NWB file. If False, neuropil traces are included in the main plane segmentation rather than the background plane segmentation.

  • include_roi_centroids (bool, default: True) – Whether to include the ROI centroids on the PlaneSegmentation table. If there are a very large number of ROIs (such as in whole-brain recordings), you may wish to disable this for faster write speeds.

  • include_roi_acceptance (bool, optional) – Deprecated and ignored. ROI acceptance is now written automatically as a column on the PlaneSegmentation table whenever the segmentation extractor exposes acceptance/rejection through its property system.

  • mask_type (str, default: ‘image’) – There are three types of ROI masks in NWB, ‘image’, ‘pixel’, and ‘voxel’.

    • ‘image’ masks have the same shape as the reference images the segmentation was applied to, and weight each pixel by its contribution to the ROI (typically boolean, with 0 meaning ‘not in the ROI’).

    • ‘pixel’ masks are instead indexed by ROI, with the data at each index being the shape of the image by the number of pixels in each ROI.

    • ‘voxel’ masks are instead indexed by ROI, with the data at each index being the shape of the volume by the number of voxels in each ROI.

    Specify your choice between these two as mask_type=’image’, ‘pixel’, ‘voxel’

  • plane_segmentation_name (str, optional) – The name of the plane segmentation to be added.

  • iterator_options (dict, optional) – Options for controlling the iterative write process (buffer size, progress bars) when writing image masks and traces.

    Note: To configure chunk size and compression, use the backend configuration system via get_default_backend_configuration() and configure_backend() after calling this method. See the backend configuration documentation for details.

  • stub_samples (int, default: 100) – The number of samples (frames) to use for testing.

  • roi_ids_to_add (list of str or int, optional) – The ROI IDs to include in the NWB file. If None (default), all ROIs are included. Use this to filter out rejected or unwanted ROIs and reduce file size. Neuropil traces (e.g., from Suite2p) share the same IDs as their corresponding cells and are automatically included when those cell IDs are selected. The IDs must be a subset of the IDs returned by self.roi_ids.

Caiman Segmentation#

class CaimanSegmentationInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *args, verbose: bool = False, metadata_key: str | None = None)[source]#

Bases: BaseSegmentationExtractorInterface

Data interface for CaimanSegmentationExtractor.

Parameters:

  • file_path (FilePath) – Path to .hdf5 file.

  • verbose (bool, default False) – Whether to print progress

  • metadata_key (str, optional) – Metadata key for this interface. When None, defaults to “caiman_segmentation”.

display_name: str | None = 'CaImAn Segmentation'#
associated_suffixes: tuple[str] = ('.hdf5',)#
info: str | None = 'Interface for CaImAn segmentation data.'#
classmethod get_source_schema() → dict[source]#

Get the source schema for the CaImAn segmentation interface.

Returns:

The schema dictionary containing input parameters and descriptions for initializing the CaImAn segmentation interface.

Return type:

dict

classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False)[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

Cnmfe Segmentation#

class CnmfeSegmentationInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *args, verbose: bool = False, metadata_key: str | None = None)[source]#

Bases: BaseSegmentationExtractorInterface

Data interface for constrained non-negative matrix factorization (CNMFE) segmentation extractor.

display_name: str | None = 'CNMFE Segmentation'#
associated_suffixes: tuple[str] = ('.mat',)#
info: str | None = 'Interface for constrained non-negative matrix factorization (CNMFE) segmentation.'#
classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False)[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

Extract Segmentation#

class ExtractSegmentationInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *args, sampling_frequency: float, output_struct_name: str | None = None, verbose: bool = False, metadata_key: str | None = None)[source]#

Bases: BaseSegmentationExtractorInterface

Data interface for ExtractSegmentationExtractor.

Parameters:

  • file_path (FilePath)

  • sampling_frequency (float)

  • output_struct_name (str, optional)

  • verbose (bool, default : True)

  • metadata_key (str, optional) – Metadata key for this interface. When None, defaults to “extract_segmentation”.

display_name: str | None = 'EXTRACT Segmentation'#
associated_suffixes: tuple[str] = ('.mat',)#
info: str | None = 'Interface for EXTRACT segmentation.'#
classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False)[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

Inscopix Segmentation#

class InscopixSegmentationInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *args, verbose: bool = False, metadata_key: str | None = None)[source]#

Bases: BaseSegmentationExtractorInterface

Conversion interface for Inscopix segmentation data.

Parameters:

  • file_path (FilePath) – Path to the .isxd Inscopix file.

  • verbose (bool, optional) – If True, outputs additional information during processing.

  • metadata_key (str, optional) – Metadata key for this interface. When None, defaults to “inscopix_segmentation”.

display_name: str | None = 'Inscopix Segmentation'#
associated_suffixes: tuple[str] = ('.isxd',)#
info: str | None = 'Interface for handling Inscopix segmentation.'#
classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Retrieve the metadata for the Inscopix segmentation data.

Parameters:

use_new_metadata_format (bool, default: False) – When False, returns the old list-based metadata format (backward compatible). When True, returns dict-based metadata with Inscopix provenance keyed by metadata_key under Devices and Ophys.PlaneSegmentations.

Returns:

  • DeepDict – Dictionary containing metadata including device information, imaging plane details, photon series configuration, and Inscopix-specific acquisition parameters.

  • TODO (Determine the excitation and emission wavelengths. For each Inscopix microscope they are fixed (e.g. NVista has an emission: 535 and excitation: 475).)

  • We currently do not know how to map the names returned by get_acquisition_info[‘MicroscopeType’]

  • to the actual microscope models, as we do not have example data for each type.

  • See related issue (https://github.com/inscopix/pyisx/issues/62)

Sima Segmentation#

class SimaSegmentationInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *args, sima_segmentation_label: str = 'auto_ROIs', metadata_key: str | None = None)[source]#

Bases: BaseSegmentationExtractorInterface

Data interface for SimaSegmentationExtractor.

Parameters:

  • file_path (FilePath)

  • sima_segmentation_label (str, default: “auto_ROIs”)

  • metadata_key (str, optional) – Metadata key for this interface. When None, defaults to “sima_segmentation”.

display_name: str | None = 'SIMA Segmentation'#
associated_suffixes: tuple[str] = ('.sima',)#
info: str | None = 'Interface for SIMA segmentation.'#
classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False)[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

Suite2p Segmentation#

class Suite2pSegmentationInterface(folder_path: Annotated[pathlib._local.Path, PathType(path_type='dir')], *args, channel_name: str | None = None, plane_name: str | None = None, plane_segmentation_name: str | None = None, verbose: bool = False, metadata_key: str | None = None)[source]#

Bases: BaseSegmentationExtractorInterface

Interface for Suite2p segmentation data.

Parameters:

  • folder_path (DirectoryPath) – Path to the folder containing Suite2p segmentation data. Should contain ‘plane#’ sub-folders.

  • channel_name (str, optional) – The name of the channel to load. To determine what channels are available, use Suite2pSegmentationInterface.get_available_channels(folder_path).

  • plane_name (str, optional) – The name of the plane to load. This interface only loads one plane at a time. If this value is omitted, the first plane found will be loaded. To determine what planes are available, use Suite2pSegmentationInterface.get_available_planes(folder_path).

  • plane_segmentation_name (str, optional) – The name of the plane segmentation to be added.

  • metadata_key (str, optional) – # TODO: improve docstring once #1653 (ophys metadata documentation) is merged Metadata key for this interface. When None, defaults to “suite2p_segmentation_{channel_name}_{plane_name}”.

display_name: str | None = 'Suite2p Segmentation'#
associated_suffixes: tuple[str] = ('.npy',)#
info: str | None = 'Interface for Suite2p segmentation.'#
classmethod get_source_schema() → dict[source]#

Get the source schema for the Suite2p segmentation interface.

Returns:

The schema dictionary containing input parameters and descriptions for initializing the Suite2p segmentation interface.

Return type:

dict

classmethod get_available_planes(folder_path: Annotated[Path, PathType(path_type=dir)]) → dict[source]#

Get the available planes in the Suite2p segmentation folder.

Parameters:

folder_path (DirectoryPath) – Path to the folder containing Suite2p segmentation data.

Returns:

Dictionary containing information about available planes in the dataset.

Return type:

dict

classmethod get_available_channels(folder_path: Annotated[Path, PathType(path_type=dir)]) → dict[source]#

Get the available channels in the Suite2p segmentation folder.

Parameters:

folder_path (DirectoryPath) – Path to the folder containing Suite2p segmentation data.

Returns:

Dictionary containing information about available channels in the dataset.

Return type:

dict

classmethod get_extractor_class()[source]#

Get the extractor class for this interface.

This classmethod must be implemented by each concrete interface to specify which extractor class to use.

Returns:

The extractor class or function to use for initialization.

Return type:

type or callable

get_metadata(*, use_new_metadata_format: bool = False) → DeepDict[source]#

Get metadata for the Suite2p segmentation data.

Parameters:

use_new_metadata_format (bool, default: False) – When False, returns the old list-based metadata format (backward compatible). When True, returns dict-based metadata with Suite2p provenance.

Returns:

Dictionary containing metadata including plane segmentation details, fluorescence data, and segmentation images.

Return type:

DeepDict

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None, *args, stub_test: bool = False, stub_samples: int = 100, include_roi_centroids: bool = True, include_roi_acceptance: bool | None = None, mask_type: str | None = 'image', plane_segmentation_name: str | None = None, iterator_options: dict | None = None)[source]#

Add segmentation data to the specified NWBFile.

Parameters:

  • nwbfile (NWBFile) – The NWBFile object to which the segmentation data will be added.

  • metadata (dict, optional) – Metadata containing information about the segmentation. If None, default metadata is used.

  • stub_test (bool, optional) – If True, only a subset of the data (defined by stub_samples) will be added for testing purposes, by default False.

  • stub_samples (int, optional) – The number of samples (frames) to include in the subset if stub_test is True, by default 100.

  • include_roi_centroids (bool, optional) – Whether to include the centroids of regions of interest (ROIs) in the data, by default True.

  • include_roi_acceptance (bool, optional) – Deprecated and ignored. ROI acceptance is now written automatically as a column on the PlaneSegmentation table whenever the segmentation extractor exposes acceptance/rejection through its property system.

  • mask_type (str, default: ‘image’) – There are three types of ROI masks in NWB, ‘image’, ‘pixel’, and ‘voxel’.

    • ‘image’ masks have the same shape as the reference images the segmentation was applied to, and weight each pixel

    by its contribution to the ROI (typically boolean, with 0 meaning ‘not in the ROI’). * ‘pixel’ masks are instead indexed by ROI, with the data at each index being the shape of the image by the number of pixels in each ROI. * ‘voxel’ masks are instead indexed by ROI, with the data at each index being the shape of the volume by the number of voxels in each ROI.

    Specify your choice between these two as mask_type=’image’, ‘pixel’, ‘voxel’, or None. plane_segmentation_name : str, optional The name of the plane segmentation object, by default None.

  • iterator_options (dict, optional) – Additional options for iterating over the data, by default None.

On this page
Edit on GitHub

This Page