Ophys#

Imaging#

Base Imaging#

Author: Ben Dichter.

class BaseImagingExtractorInterface(verbose: bool = False, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries', **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')#

ExtractorModuleName: Optional[str] = 'roiextractors'#

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() → DeepDict[source]#

Retrieve the metadata for the imaging data.

Returns: Dictionary containing metadata including device information, imaging plane details, and photon series configuration.
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: Optional[dict] = None, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries', photon_series_index: int = 0, parent_container: Literal['acquisition', 'processing/ophys'] = 'acquisition', stub_test: bool = False, stub_frames: int = 100, always_write_timestamps: bool = False)[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.
stub_frames (int, optional) – The number of frames to write when stub_test is True. Will use min(stub_frames, total_frames) to avoid exceeding available frames, by default 100.

Bruker Tiff Imaging#

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

Bases: NWBConverter

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: Union[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: Union[str, None] = 'Interface for handling all channels and all planes of Bruker imaging data.'#

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_conversion_options_schema() → dict[source]#

Get the schema for the conversion options.

Returns: The schema dictionary containing conversion options for the Bruker TIFF interface.
Return type: dict

add_to_nwbfile(nwbfile: NWBFile, metadata, stub_test: bool = False, stub_frames: 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_frames) will be added for testing purposes. Default is False.
stub_frames (int, optional) – The number of frames to include in the subset if stub_test is True. Default is 100.

run_conversion(nwbfile_path: Optional[Path] = None, nwbfile: Optional[NWBFile] = None, metadata: Optional[dict] = None, overwrite: bool = False, stub_test: bool = False, stub_frames: int = 100) → None[source]#

Run the conversion process for the instantiated data interfaces and add data to the NWB file.

Parameters

nwbfile_path (FilePath, optional) – Path where the NWB file will be written. If None, the file will be handled in-memory.
nwbfile (NWBFile, optional) – An in-memory NWBFile object. If None, a new NWBFile object will be created.
metadata (dict, optional) – Metadata dictionary for describing the NWB file. If None, it will be auto-generated using the get_metadata() method.
overwrite (bool, optional) – If True, overwrites the existing NWB file at nwbfile_path. If False, appends to the file (default is False).
stub_test (bool, optional) – If True, only a subset of the data (up to stub_frames) will be added for testing purposes, by default False.
stub_frames (int, optional) – The number of frames to include in the subset if stub_test is True, by default 100.

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

Bases: NWBConverter

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: Union[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: Union[str, None] = 'Interface for handling multiple channels of a single plane of Bruker imaging data.'#

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_conversion_options_schema() → dict[source]#

Get the schema for the conversion options.

Returns: The schema dictionary containing conversion options for the Bruker TIFF interface.
Return type: dict

add_to_nwbfile(nwbfile: NWBFile, metadata, stub_test: bool = False, stub_frames: 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_frames) will be added for testing purposes, by default False.
stub_frames (int, optional) – The number of frames to include in the subset if stub_test is True, by default 100.

Run the NWB conversion process for all instantiated data interfaces.

Parameters

nwbfile_path (FilePath, optional) – The file path where the NWB file will be written. If None, the file is handled in-memory.
nwbfile (NWBFile, optional) – An existing in-memory NWBFile object. If None, a new NWBFile object will be created.
metadata (dict, optional) – Metadata dictionary used to create or validate the NWBFile. If None, metadata is automatically generated.
overwrite (bool, optional) – If True, the NWBFile at nwbfile_path is overwritten if it exists. If False (default), data is appended.
stub_test (bool, optional) – If True, only a subset of the data (up to stub_frames) is used for testing purposes. By default False.
stub_frames (int, optional) – The number of frames to include in the subset if stub_test is True. By default 100.

HDF5 Imaging#

class Hdf5ImagingInterface(file_path: Annotated[pathlib.Path, PathType(path_type='file')], mov_field: str = 'mov', sampling_frequency: Optional[float] = None, start_time: Optional[float] = None, metadata: Optional[dict] = None, channel_names: Union[list, numpy.ndarray, NoneType] = None, verbose: bool = False, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries')[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)

display_name: Union[str, None] = 'HDF5 Imaging'#

associated_suffixes: tuple[str] = ('.h5', '.hdf5')#

info: Union[str, None] = 'Interface for HDF5 imaging data.'#

MicroManager Tiff Imaging#

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

Bases: BaseImagingExtractorInterface

Data Interface for MicroManagerTiffImagingExtractor.

Parameters

folder_path (FolderPathType) – The folder path that contains the OME-TIF image files (.ome.tif files) and the ‘DisplaySettings’ JSON file.
verbose (bool, default: False)

display_name: Union[str, None] = 'Micro-Manager TIFF Imaging'#

associated_suffixes: tuple[str] = ('.ome', '.tif', '.json')#

info: Union[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

get_metadata() → dict[source]#

Get metadata for the Micro-Manager TIFF imaging data.

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.Path, PathType(path_type='dir')], verbose: bool = False)[source]#

Bases: NWBConverter

Primary conversion class for handling Miniscope data streams.

Initializes the data interfaces for the Miniscope recording and behavioral data stream.

The main Miniscope folder is expected to contain both data streams organized as follows:

C6-J588_Disc5/ (main folder)
├── 15_03_28/ (subfolder corresponding to the recording time)
│   ├── Miniscope/ (subfolder containing the microscope video stream)
│   │   ├── 0.avi (microscope video)
│   │   ├── metaData.json (metadata for the microscope device)
│   │   └── timeStamps.csv (timing of this video stream)
│   ├── BehavCam_2/ (subfolder containing the behavioral video stream)
│   │   ├── 0.avi (bevavioral video)
│   │   ├── metaData.json (metadata for the behavioral camera)
│   │   └── timeStamps.csv (timing of this video stream)
│   └── metaData.json (metadata for the recording, such as the start time)
├── 15_06_28/
│   ├── Miniscope/
│   ├── BehavCam_2/
│   └── metaData.json
└── 15_12_28/

Parameters

folder_path (FolderPathType) – The path to the main Miniscope folder.
verbose (bool, default: False) – Controls verbosity.

display_name: Union[str, None] = 'Miniscope Imaging and Video'#

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

associated_suffixes: tuple[str] = ('.avi', '.csv', '.json', '.avi')#

info: Union[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_conversion_options_schema() → dict[source]#

Get the schema for the conversion options.

Returns: The schema dictionary containing conversion options for the Miniscope interface.
Return type: dict

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

Add Miniscope imaging and behavioral camera data to the specified NWBFile.

Parameters

nwbfile (NWBFile) – The NWBFile object to which the imaging and behavioral data will be added.
metadata (dict) – Metadata dictionary containing information about the imaging and behavioral recordings.
stub_test (bool, optional) – If True, only a subset of the data (defined by stub_frames) will be added for testing purposes, by default False.
stub_frames (int, optional) – The number of frames to include in the subset if stub_test is True, by default 100.

run_conversion(nwbfile_path: Optional[str] = None, nwbfile: Optional[NWBFile] = None, metadata: Optional[dict] = None, overwrite: bool = False, stub_test: bool = False, stub_frames: int = 100) → 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_frames) is written for testing purposes, by default False.
stub_frames (int, optional) – The number of frames to include in the subset if stub_test is True, by default 100.

Sbx Imaging#

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

Bases: BaseImagingExtractorInterface

Data Interface for SbxImagingExtractor.

Parameters

file_path (FilePath) – Path to .sbx file.
sampling_frequency (float, optional)
verbose (bool, default: False)

display_name: Union[str, None] = 'Scanbox Imaging'#

associated_suffixes: tuple[str] = ('.sbx',)#

info: Union[str, None] = 'Interface for Scanbox imaging data.'#

get_metadata() → dict[source]#

Get metadata for the Scanbox imaging data.

Returns: Dictionary containing metadata including device information and imaging details specific to the Scanbox system.
Return type: dict

ScanImage Imaging#

class ScanImageImagingInterface(verbose: bool = False, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries', **source_data)[source]#

Bases: BaseImagingExtractorInterface

Interface for reading TIFF files produced via ScanImage.

It extracts metadata from the provided TIFF file and determines the ScanImage version. For the legacy version 3.8, it creates an instance of ScanImageLegacyImagingInterface. For newer versions, it parses the metadata and determines the number of planes. If there is more than one plane and no specific plane is provided, it creates an instance of ScanImageMultiPlaneImagingInterface. If there is only one plane or a specific plane is provided, it creates an instance of ScanImageSinglePlaneImagingInterface.

display_name: Union[str, None] = 'ScanImage Imaging'#

associated_suffixes: tuple[str] = ('.tif',)#

info: Union[str, None] = 'Interface for ScanImage TIFF files.'#

ExtractorName: Optional[str] = 'ScanImageTiffImagingExtractor'#

classmethod get_source_schema() → dict[source]#

Get the source schema for the ScanImage imaging interface.

Returns: The schema dictionary containing input parameters and descriptions for initializing the ScanImage interface.
Return type: dict

class ScanImageLegacyImagingInterface(file_path: Annotated[pathlib.Path, PathType(path_type='file')], fallback_sampling_frequency: Optional[float] = None, verbose: bool = False)[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.

display_name: Union[str, None] = 'ScanImage Imaging'#

associated_suffixes: tuple[str] = ('.tif',)#

info: Union[str, None] = 'Interface for ScanImage v3.8 TIFF files.'#

ExtractorName: Optional[str] = 'ScanImageTiffImagingExtractor'#

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

get_metadata() → dict[source]#

Get metadata for the ScanImage imaging data.

Returns: Dictionary containing metadata including session start time and device information specific to the ScanImage system.
Return type: dict

class ScanImageMultiFileImagingInterface(verbose: bool = False, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries', **source_data)[source]#

Bases: BaseImagingExtractorInterface

Interface for reading multi-file (buffered) TIFF files produced via ScanImage.

It extracts metadata from the first TIFF file in the provided folder and determines the number of available planes. If there is more than one plane and no specific plane is provided, it creates an instance of ScanImageMultiPlaneMultiFileImagingInterface. If there is only one plane or a specific plane is provided, it creates an instance of ScanImageSinglePlaneMultiFileImagingInterface.

display_name: Union[str, None] = 'ScanImage Multi-File Imaging'#

associated_suffixes: tuple[str] = ('.tif',)#

info: Union[str, None] = 'Interface for ScanImage multi-file (buffered) TIFF files.'#

ExtractorName: Optional[str] = 'ScanImageTiffSinglePlaneMultiFileImagingExtractor'#

classmethod get_source_schema() → dict[source]#

Get the source schema for the ScanImage multi-file imaging interface.

Returns: The schema dictionary containing input parameters and descriptions for initializing the ScanImage multi-file interface.
Return type: dict

class ScanImageMultiPlaneImagingInterface(file_path: Annotated[pathlib.Path, PathType(path_type='file')], channel_name: Optional[str] = None, image_metadata: Optional[dict] = None, parsed_metadata: Optional[dict] = None, verbose: bool = False)[source]#

Bases: BaseImagingExtractorInterface

Interface for reading multi plane (volumetric) TIFF files produced via ScanImage.

DataInterface for reading multi-file (buffered) TIFF files that are generated by ScanImage.

Parameters

file_path (FilePath) – Path to the TIFF file.
channel_name (str) – Name of the channel for this extractor.

display_name: Union[str, None] = 'ScanImage Volumetric Imaging'#

associated_suffixes: tuple[str] = ('.tif',)#

info: Union[str, None] = 'Interface for ScanImage multi plane (volumetric) TIFF files.'#

ExtractorName: Optional[str] = 'ScanImageTiffMultiPlaneImagingExtractor'#

get_metadata() → dict[source]#

Get metadata for the ScanImage imaging data.

Returns: Dictionary containing metadata including session start time and device information specific to the ScanImage system.
Return type: dict

class ScanImageMultiPlaneMultiFileImagingInterface(folder_path: Annotated[pathlib.Path, PathType(path_type='dir')], file_pattern: str, channel_name: Optional[str] = None, extract_all_metadata: bool = False, image_metadata: Optional[dict] = None, parsed_metadata: Optional[dict] = None, verbose: bool = False)[source]#

Bases: BaseImagingExtractorInterface

Interface for reading volumetric multi-file (buffered) TIFF files produced via ScanImage.

DataInterface for reading multi-file (buffered) TIFF files that are generated by ScanImage.

Parameters

folder_path (DirectoryPath) – Path to the folder containing the TIFF files.
file_pattern (str) – Pattern for the TIFF files to read – see pathlib.Path.glob for details.
channel_name (str) – The name of the channel to load, to determine what channels are available use ScanImageTiffSinglePlaneImagingExtractor.get_available_channels(file_path=…).
extract_all_metadata (bool) – If True, extract metadata from every file in the folder. If False, only extract metadata from the first file in the folder. The default is False.

display_name: Union[str, None] = 'ScanImage Volumetric Multi-File Imaging'#

associated_suffixes: tuple[str] = ('.tif',)#

info: Union[str, None] = 'Interface for ScanImage multi-file (buffered) volumetric TIFF files.'#

ExtractorName: Optional[str] = 'ScanImageTiffMultiPlaneMultiFileImagingExtractor'#

get_metadata() → dict[source]#

Get metadata for the ScanImage imaging data.

Returns: Dictionary containing metadata including session start time, device information, and imaging plane configuration specific to the ScanImage system.
Return type: dict

class ScanImageSinglePlaneImagingInterface(file_path: Annotated[pathlib.Path, PathType(path_type='file')], channel_name: Optional[str] = None, plane_name: Optional[str] = None, image_metadata: Optional[dict] = None, parsed_metadata: Optional[dict] = None, verbose: bool = False)[source]#

Bases: BaseImagingExtractorInterface

Interface for reading TIFF files produced via ScanImage.

DataInterface for reading multi-file (buffered) TIFF files that are generated by ScanImage.

Parameters

file_path (FilePath) – Path to the TIFF file.
channel_name (str) – The name of the channel to load, to determine what channels are available use ScanImageTiffSinglePlaneImagingExtractor.get_available_channels(file_path=…).
plane_name (str) – The name of the plane to load, to determine what planes are available use ScanImageTiffSinglePlaneImagingExtractor.get_available_planes(file_path=…).

display_name: Union[str, None] = 'ScanImage Single Plane Imaging'#

associated_suffixes: tuple[str] = ('.tif',)#

info: Union[str, None] = 'Interface for ScanImage TIFF files.'#

ExtractorName: Optional[str] = 'ScanImageTiffSinglePlaneImagingExtractor'#

get_metadata() → dict[source]#

Get metadata for the ScanImage imaging data.

Returns: Dictionary containing metadata including session start time, device information, and imaging plane configuration specific to the ScanImage system.
Return type: dict

class ScanImageSinglePlaneMultiFileImagingInterface(folder_path: Annotated[pathlib.Path, PathType(path_type='dir')], file_pattern: str, channel_name: Optional[str] = None, plane_name: Optional[str] = None, image_metadata: Optional[dict] = None, parsed_metadata: Optional[dict] = None, extract_all_metadata: bool = False, verbose: bool = False)[source]#

Bases: BaseImagingExtractorInterface

Interface for reading multi-file (buffered) TIFF files produced via ScanImage.

DataInterface for reading multi-file (buffered) TIFF files that are generated by ScanImage.

Parameters

folder_path (DirectoryPath) – Path to the folder containing the TIFF files.
file_pattern (str) – Pattern for the TIFF files to read – see pathlib.Path.glob for details.
channel_name (str) – The name of the channel to load, to determine what channels are available use ScanImageTiffSinglePlaneImagingExtractor.get_available_channels(file_path=…).
plane_name (str) – The name of the plane to load, to determine what planes are available use ScanImageTiffSinglePlaneImagingExtractor.get_available_planes(file_path=…).
extract_all_metadata (bool) – If True, extract metadata from every file in the folder. If False, only extract metadata from the first file in the folder. The default is False.

display_name: Union[str, None] = 'ScanImage Single Plane Multi-File Imaging'#

associated_suffixes: tuple[str] = ('.tif',)#

info: Union[str, None] = 'Interface for ScanImage multi-file (buffered) TIFF files.'#

ExtractorName: Optional[str] = 'ScanImageTiffSinglePlaneMultiFileImagingExtractor'#

get_metadata() → dict[source]#

Get metadata for the ScanImage imaging data.

Returns: Dictionary containing metadata including session start time, device information, and imaging plane configuration specific to the ScanImage system.
Return type: dict

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.Path, PathType(path_type='file')], sampling_frequency: float, verbose: bool = False, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries')[source]#

Bases: BaseImagingExtractorInterface

Interface for multi-page TIFF files.

Initialize reading of TIFF file.

Parameters

file_path (FilePath)
sampling_frequency (float)
verbose (bool, default: False)
photon_series_type ({‘OnePhotonSeries’, ‘TwoPhotonSeries’}, default: “TwoPhotonSeries”)

display_name: Union[str, None] = 'TIFF Imaging'#

associated_suffixes: tuple[str] = ('.tif', '.tiff')#

info: Union[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

Segmentation#

Base Segmentation#

Authors: Heberto Mayorquin, Cody Baker and Ben Dichter.

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

Bases: BaseExtractorInterface

Parent class for all SegmentationExtractorInterfaces.

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

ExtractorModuleName: Optional[str] = 'roiextractors'#

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() → dict[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: Optional[dict] = None, stub_test: bool = False, stub_frames: int = 100, include_background_segmentation: bool = False, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Optional[str] = 'image', plane_segmentation_name: Optional[str] = None, iterator_options: Optional[dict] = None)[source]#

Parameters

nwbfile (NWBFile) – The NWBFile to add the plane segmentation to.
metadata (dict, optional) – The metadata for the interface
stub_test (bool, default: False)
stub_frames (int, default: 100)
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, default: True) – Whether to include if the detected ROI was ‘accepted’ or ‘rejected’. If there are a very large number of ROIs (such as in whole-brain recordings), you may wish to ddisable this for faster write speeds.
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. If None, the mask information is not written to the NWB file.
plane_segmentation_name (str, optional) – The name of the plane segmentation to be added.
iterator_options (dict, optional) – The options to use when iterating over the image masks of the segmentation extractor.

Caiman Segmentation#

class CaimanSegmentationInterface(file_path: Annotated[pathlib.Path, PathType(path_type='file')], verbose: bool = False)[source]#

Bases: BaseSegmentationExtractorInterface

Data interface for CaimanSegmentationExtractor.

Parameters

file_path (FilePath) – Path to .hdf5 file.
verbose (bool, default True) – Whether to print progress

display_name: Union[str, None] = 'CaImAn Segmentation'#

associated_suffixes: tuple[str] = ('.hdf5',)#

info: Union[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

Cnmfe Segmentation#

class CnmfeSegmentationInterface(file_path: Annotated[pathlib.Path, PathType(path_type='file')], verbose: bool = False)[source]#

Bases: BaseSegmentationExtractorInterface

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

display_name: Union[str, None] = 'CNMFE Segmentation'#

associated_suffixes: tuple[str] = ('.mat',)#

info: Union[str, None] = 'Interface for constrained non-negative matrix factorization (CNMFE) segmentation.'#

Extract Segmentation#

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

Bases: BaseSegmentationExtractorInterface

Data interface for ExtractSegmentationExtractor.

Parameters

file_path (FilePath)
sampling_frequency (float)
output_struct_name (str, optional)
verbose (bool, default : True)

display_name: Union[str, None] = 'EXTRACT Segmentation'#

associated_suffixes: tuple[str] = ('.mat',)#

info: Union[str, None] = 'Interface for EXTRACT segmentation.'#

Sima Segmentation#

class SimaSegmentationInterface(file_path: Annotated[pathlib.Path, PathType(path_type='file')], sima_segmentation_label: str = 'auto_ROIs')[source]#

Bases: BaseSegmentationExtractorInterface

Data interface for SimaSegmentationExtractor.

Parameters

file_path (FilePath)
sima_segmentation_label (str, default: “auto_ROIs”)

display_name: Union[str, None] = 'SIMA Segmentation'#

associated_suffixes: tuple[str] = ('.sima',)#

info: Union[str, None] = 'Interface for SIMA segmentation.'#

Suite2p Segmentation#

class Suite2pSegmentationInterface(folder_path: Annotated[pathlib.Path, PathType(path_type='dir')], channel_name: Optional[str] = None, plane_name: Optional[str] = None, plane_segmentation_name: Optional[str] = None, verbose: bool = False)[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.

display_name: Union[str, None] = 'Suite2p Segmentation'#

associated_suffixes: tuple[str] = ('.npy',)#

info: Union[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: Path) → 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: Path) → 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

get_metadata() → DeepDict[source]#

Get metadata for the Suite2p segmentation data.

Returns: Dictionary containing metadata including plane segmentation details, fluorescence data, and segmentation images.
Return type: DeepDict

add_to_nwbfile(nwbfile: NWBFile, metadata: Optional[dict] = None, stub_test: bool = False, stub_frames: int = 100, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Optional[str] = 'image', plane_segmentation_name: Optional[str] = None, iterator_options: Optional[dict] = 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_frames) will be added for testing purposes, by default False.
stub_frames (int, optional) – The number of 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) – Whether to include acceptance status of ROIs, by default True.
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.

Fiber Photometry#

TDT Fiber Photometry#

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

Bases: BaseTemporalAlignmentInterface

Data Interface for converting fiber photometry data from a TDT output folder.

The output folder from TDT consists of a variety of TDT-specific file types (e.g. Tbk, Tdx, tev, tin, tsq). This data is read by the tdt.read_block function, and then parsed into the ndx-fiber-photometry format.

Initialize the TDTFiberPhotometryInterface.

Parameters

folder_path (FilePath) – The path to the folder containing the TDT data.
verbose (bool, optional) – Whether to print status messages, default = True.

keywords: tuple[str] = ('fiber photometry',)#

display_name: Union[str, None] = 'TDTFiberPhotometry'#

info: Union[str, None] = 'Data Interface for converting fiber photometry data from TDT files.'#

associated_suffixes: tuple[str] = ('Tbk', 'Tdx', 'tev', 'tin', 'tsq')#

get_metadata() → DeepDict[source]#

Get metadata for the TDTFiberPhotometryInterface.

Returns: The metadata dictionary for this interface.
Return type: DeepDict

get_metadata_schema() → dict[source]#

Get the metadata schema for the TDTFiberPhotometryInterface.

Returns: The metadata schema for this interface.
Return type: dict

load(t1: float = 0.0, t2: float = 0.0, evtype: list[str] = ['all'])[source]#

Load the TDT data from the folder path.

Parameters

t1 (float, optional) – Retrieve data starting at t1 (in seconds), default = 0 for start of recording.
t2 (float, optional) – Retrieve data ending at t2 (in seconds), default = 0 for end of recording.
evtype (list[str], optional) – List of strings, specifies what type of data stores to retrieve from the tank. Can contain ‘all’ (default), ‘epocs’, ‘snips’, ‘streams’, or ‘scalars’. Ex. [‘epocs’, ‘snips’]

Returns

TDT data object

Return type

tdt.StructType

get_original_timestamps(t1: float = 0.0, t2: float = 0.0) → dict[str, numpy.ndarray][source]#

Get the original timestamps for the data.

Parameters

t1 (float, optional) – Retrieve data starting at t1 (in seconds), default = 0 for start of recording.
t2 (float, optional) – Retrieve data ending at t2 (in seconds), default = 0 for end of recording.

Returns

Dictionary of stream names to timestamps.

Return type

dict[str, np.ndarray]

get_timestamps(t1: float = 0.0, t2: float = 0.0) → dict[str, numpy.ndarray][source]#

Get the timestamps for the data.

Parameters

t1 (float, optional) – Retrieve data starting at t1 (in seconds), default = 0 for start of recording.
t2 (float, optional) – Retrieve data ending at t2 (in seconds), default = 0 for end of recording.

Returns

Dictionary of stream names to timestamps.

Return type

dict[str, np.ndarray]

set_aligned_timestamps(stream_name_to_aligned_timestamps: dict[str, numpy.ndarray]) → None[source]#

Set the aligned timestamps for the data.

Parameters: stream_name_to_aligned_timestamps (dict[str, np.ndarray]) – Dictionary of stream names to aligned timestamps.

set_aligned_starting_time(aligned_starting_time: float, t1: float = 0.0, t2: float = 0.0) → None[source]#

Set the aligned starting time and adjust the timestamps appropriately.

Parameters

aligned_starting_time (float) – The aligned starting time.
t1 (float, optional) – Retrieve data starting at t1 (in seconds), default = 0 for start of recording.
t2 (float, optional) – Retrieve data ending at t2 (in seconds), default = 0 for end of recording.

get_original_starting_time_and_rate(t1: float = 0.0, t2: float = 0.0) → dict[str, tuple[float, float]][source]#

Get the original starting time and rate for the data.

Parameters

t1 (float, optional) – Retrieve data starting at t1 (in seconds), default = 0 for start of recording.
t2 (float, optional) – Retrieve data ending at t2 (in seconds), default = 0 for end of recording.

Returns

Dictionary of stream names to starting time and rate.

Return type

dict[str, tuple[float, float]]

get_starting_time_and_rate(t1: float = 0.0, t2: float = 0.0) → tuple[float, float][source]#

Get the starting time and rate for the data.

Parameters

t1 (float, optional) – Retrieve data starting at t1 (in seconds), default = 0 for start of recording.
t2 (float, optional) – Retrieve data ending at t2 (in seconds), default = 0 for end of recording.

Returns

Dictionary of stream names to starting time and rate.

Return type

dict[str, tuple[float, float]]

set_aligned_starting_time_and_rate(stream_name_to_aligned_starting_time_and_rate: dict[str, tuple[float, float]]) → None[source]#

Set the aligned starting time and rate for the data.

Parameters: stream_name_to_aligned_starting_time_and_rate (dict[str, tuple[float, float]]) – Dictionary of stream names to aligned starting time and rate.

get_events() → dict[str, dict[str, numpy.ndarray]][source]#

Get a dictionary of events from the TDT files (e.g. camera TTL pulses).

The events dictionary maps from the names of each epoc in the TDT data to an event dictionary. Each event dictionary maps from “onset”, “offset”, and “data” to the corresponding arrays.

Returns: Dictionary of events.
Return type: dict[str, dict[str, np.ndarray]]

add_to_nwbfile(nwbfile: NWBFile, metadata: dict, *, stub_test: bool = False, t1: float = 0.0, t2: float = 0.0, timing_source: Literal['original', 'aligned_timestamps', 'aligned_starting_time_and_rate'] = 'original')[source]#

Add the data to an NWBFile.

Parameters

nwbfile (pynwb.NWBFile) – The in-memory object to add the data to.
metadata (dict) – Metadata dictionary with information used to create the NWBFile.
stub_test (bool, optional) – If True, only add a subset of the data (1s) to the NWBFile for testing purposes, default = False.
t1 (float, optional) – Retrieve data starting at t1 (in seconds), default = 0 for start of recording.
t2 (float, optional) – Retrieve data ending at t2 (in seconds), default = 0 for end of recording.
timing_source (Literal[“original”, “aligned_timestamps”, “aligned_starting_time_and_rate”], optional) – Source of timing information for the data, default = “original”.

Raises

AssertionError – If the timing_source is not one of “original”, “aligned_timestamps”, or “aligned_starting_time_and_rate”.