ROI extractors#

Interface with roiextractors#

get_nwb_imaging_metadata(imgextractor: ImagingExtractor, photon_series_type: Literal['OnePhotonSeries', 'TwoPhotonSeries'] = 'TwoPhotonSeries') → dict[source]#

Convert metadata from the ImagingExtractor into nwb specific metadata.

Parameters:

  • imgextractor (ImagingExtractor) – The imaging extractor to get metadata from.

  • photon_series_type ({‘OnePhotonSeries’, ‘TwoPhotonSeries’}, optional) – The type of photon series to create metadata for.

Returns:

Dictionary containing metadata for devices, imaging planes, and photon series specific to the imaging data.

Return type:

dict

add_devices_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None) → NWBFile[source]#

Add optical physiology devices from metadata.

Notes

The metadata concerning the optical physiology should be stored in metadata['Ophys']['Device'].

Deprecation: Passing pynwb.device.Device objects directly inside metadata['Ophys']['Device'] is deprecated and will be removed on or after March 2026. Please pass device definitions as dictionaries instead (e.g., {"name": "Microscope"}).

add_imaging_plane_to_nwbfile(nwbfile: NWBFile, metadata: dict, imaging_plane_name: str | None = None) → NWBFile[source]#

Deprecated since version 0.8.2: This function is deprecated and will be removed on or after March 2026. It is kept as-is for backward compatibility. Use high-level interface methods instead.

add_image_segmentation_to_nwbfile(nwbfile: NWBFile, metadata: dict) → NWBFile[source]#

Deprecated since version 0.8.2: This function is deprecated and will be removed on or after March 2026. It is kept as-is for backward compatibility. Use high-level interface methods instead.

add_photon_series_to_nwbfile(imaging: ImagingExtractor, nwbfile: NWBFile, metadata: dict | None = None, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries', photon_series_index: int = 0, parent_container: Literal['acquisition', 'processing/ophys'] = 'acquisition', iterator_type: str | None = 'v2', iterator_options: dict | None = None, always_write_timestamps: bool = False) → NWBFile[source]#

Deprecated since version 0.8.2: This function is deprecated and will be removed on or after March 2026. It is kept as-is for backward compatibility. Use high-level interface methods instead.

add_imaging_to_nwbfile(imaging: ImagingExtractor, nwbfile: NWBFile, metadata: dict | None = None, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries', photon_series_index: int = 0, iterator_type: str | None = 'v2', iterator_options: dict | None = None, parent_container: Literal['acquisition', 'processing/ophys'] = 'acquisition', always_write_timestamps: bool = False) → NWBFile[source]#

Add imaging data from an ImagingExtractor object to an NWBFile.

Parameters:

  • imaging (ImagingExtractor) – The extractor object containing the imaging data.

  • 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.

  • iterator_type (str, optional) – The type of iterator to use for adding the data. Commonly used to manage large datasets, by default “v2”.

  • iterator_options (dict, optional) – Additional options for controlling the iteration process, by default None.

  • 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”.

  • always_write_timestamps (bool, default: False) – Set to True to always write timestamps. By default (False), the function checks if the timestamps are uniformly sampled, and if so, stores the data using a regular sampling rate instead of explicit timestamps. If set to True, timestamps will be written explicitly, regardless of whether the sampling rate is uniform.

Returns:

The NWB file with the imaging data added

Return type:

NWBFile

write_imaging_to_nwbfile(imaging: ImagingExtractor, nwbfile_path: Annotated[Path, PathType(path_type=file)] | None = None, nwbfile: NWBFile | None = None, metadata: dict | None = None, overwrite: bool = False, verbose: bool = False, iterator_type: str = 'v2', iterator_options: dict | None = None, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries')[source]#

Primary method for writing an ImagingExtractor object to an NWBFile.

Parameters:

  • imaging (ImagingExtractor) – The imaging extractor object to be written to nwb

  • nwbfile_path (FilePath) – Path for where to write or load (if overwrite=False) the NWBFile. If specified, the context will always write to this location.

  • nwbfile (NWBFile, optional) – If passed, this function will fill the relevant fields within the NWBFile object. E.g., calling:

    write_recording(recording=my_recording_extractor, nwbfile=my_nwbfile)

    will result in the appropriate changes to the my_nwbfile object. If neither ‘nwbfile_path’ nor ‘nwbfile’ are specified, an NWBFile object will be automatically generated and returned by the function.

  • metadata (dict, optional) – Metadata dictionary with information used to create the NWBFile when one does not exist or overwrite=True.

  • overwrite (bool, optional) – Whether to overwrite the NWBFile if one exists at the nwbfile_path. The default is False (append mode).

  • verbose (bool, optional) – If ‘nwbfile_path’ is specified, informs user after a successful write operation. The default is True.

  • 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). Note: ‘v1’ is deprecated and will be removed on or after March 2026.

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

get_nwb_segmentation_metadata(sgmextractor: SegmentationExtractor) → dict[source]#

Convert metadata from the segmentation into nwb specific metadata.

Parameters:

segmentation_extractor (SegmentationExtractor) – The segmentation extractor to get metadata from.

Returns:

Dictionary containing metadata for devices, imaging planes, image segmentation, and fluorescence data specific to the segmentation.

Return type:

dict

add_plane_segmentation_to_nwbfile(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: dict | None, plane_segmentation_name: str | None = None, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Literal['image', 'pixel', 'voxel'] = 'image', iterator_options: dict | None = None) → NWBFile[source]#

Deprecated since version 0.8.2: This function is deprecated and will be removed on or after March 2026. It is kept as-is for backward compatibility. Use high-level interface methods instead.

add_background_plane_segmentation_to_nwbfile(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: dict | None, background_plane_segmentation_name: str | None = None, mask_type: Literal['image', 'pixel', 'voxel'] = 'image', iterator_options: dict | None = None) → NWBFile[source]#

Deprecated since version 0.8.2: This function is deprecated and will be removed on or after March 2026. It is kept as-is for backward compatibility. Use high-level interface methods instead.

add_fluorescence_traces_to_nwbfile(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: dict | None, plane_segmentation_name: str | None = None, include_background_segmentation: bool = False, iterator_options: dict | None = None) → NWBFile[source]#

Deprecated since version 0.8.2: This function is deprecated and will be removed on or after March 2026. It is kept as-is for backward compatibility. Use high-level interface methods instead.

add_background_fluorescence_traces_to_nwbfile(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: dict | None, background_plane_segmentation_name: str | None = None, iterator_options: dict | None = None, compression_options: dict | None = None) → NWBFile[source]#

Deprecated since version 0.8.2: This function is deprecated and will be removed on or after March 2026. It is kept as-is for backward compatibility. Use high-level interface methods instead.

add_summary_images_to_nwbfile(nwbfile: NWBFile, segmentation_extractor: SegmentationExtractor, metadata: dict | None = None, plane_segmentation_name: str | None = None) → NWBFile[source]#

Deprecated since version 0.8.2: This function is deprecated and will be removed on or after March 2026. It is kept as-is for backward compatibility. Use high-level interface methods instead.

add_segmentation_to_nwbfile(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: dict | None = None, plane_segmentation_name: str | None = None, background_plane_segmentation_name: str | None = None, include_background_segmentation: bool = False, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Literal['image', 'pixel', 'voxel'] = 'image', iterator_options: dict | None = None) → NWBFile[source]#

Add segmentation data from a SegmentationExtractor object to an NWBFile.

Parameters:

  • segmentation_extractor (SegmentationExtractor) – The extractor object containing segmentation data.

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

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

  • plane_segmentation_name (str, optional) – The name of the PlaneSegmentation object to be added, by default None.

  • background_plane_segmentation_name (str, optional) – The name of the background PlaneSegmentation, if any, by default None.

  • include_background_segmentation (bool, optional) – If True, includes background plane segmentation, by default False.

  • include_roi_centroids (bool, optional) – If True, includes the centroids of the regions of interest (ROIs), by default True.

  • include_roi_acceptance (bool, optional) – If True, includes the acceptance status of ROIs, by default True.

  • mask_type (str) – Type of mask to use for segmentation; can be either “image” or “pixel”, by default “image”.

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

Returns:

The NWBFile with the added segmentation data.

Return type:

NWBFile

write_segmentation_to_nwbfile(segmentation_extractor: SegmentationExtractor, nwbfile_path: Annotated[Path, PathType(path_type=file)] | None = None, nwbfile: NWBFile | None = None, metadata: dict | None = None, overwrite: bool = False, verbose: bool = False, include_background_segmentation: bool = False, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Literal['image', 'pixel', 'voxel'] = 'image', iterator_options: dict | None = None) → NWBFile[source]#

Primary method for writing an SegmentationExtractor object to an NWBFile.

Parameters:

  • segmentation_extractor (SegmentationExtractor) – The segmentation extractor object to be written to nwb

  • nwbfile_path (FilePath) – Path for where to write or load (if overwrite=False) the NWBFile. If specified, the context will always write to this location.

  • nwbfile (NWBFile, optional) – If passed, this function will fill the relevant fields within the NWBFile object. E.g., calling:

    write_segmentation_to_nwbfile(segmentation_extractor=my_segmentation_extractor, nwbfile=my_nwbfile)

    will result in the appropriate changes to the my_nwbfile object. If neither ‘nwbfile_path’ nor ‘nwbfile’ are specified, an NWBFile object will be automatically generated and returned by the function.

  • metadata (dict, optional) – Metadata dictionary with information used to create the NWBFile when one does not exist or overwrite=True.

  • overwrite (bool, default: False) – Whether to overwrite the NWBFile if one exists at the nwbfile_path.

  • verbose (bool, default: True) – If ‘nwbfile_path’ is specified, informs user after a successful write operation.

  • 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 disable 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’

  • iterator_options (dict, optional) – A dictionary with options for the internal iterators that process the data.

Imaging extractor iterator#

General purpose iterator for all ImagingExtractor data.

class ImagingExtractorDataChunkIterator(imaging_extractor: roiextractors.imagingextractor.ImagingExtractor, buffer_gb: float | None = None, buffer_shape: tuple | None = None, chunk_mb: float | None = None, chunk_shape: tuple | None = None, display_progress: bool = False, progress_bar_class: tqdm.std.tqdm | None = None, progress_bar_options: dict | None = None)[source]#

Bases: GenericDataChunkIterator

DataChunkIterator for ImagingExtractor objects primarily used when writing imaging data to an NWB file.

Initialize an Iterable object which returns DataChunks with data and their selections on each iteration.

Parameters:

  • imaging_extractor (ImagingExtractor) – The ImagingExtractor object which handles the data access.

  • buffer_gb (float, optional) – The upper bound on size in gigabytes (GB) of each selection from the iteration. The buffer_shape will be set implicitly by this argument. Cannot be set if buffer_shape is also specified. The default is 1GB.

  • buffer_shape (tuple, optional) – Manual specification of buffer shape to return on each iteration. Must be a multiple of chunk_shape along each axis. Cannot be set if buffer_gb is also specified. The default is None.

  • chunk_mb (float, optional) – The upper bound on size in megabytes (MB) of the internal chunk for the HDF5 dataset. The chunk_shape will be set implicitly by this argument. Cannot be set if chunk_shape is also specified. The default is 10MB, as recommended by the HDF5 group. For more details, search the hdf5 documentation for “Improving IO Performance Compressed Datasets”.

  • chunk_shape (tuple, optional) – Manual specification of the internal chunk shape for the HDF5 dataset. Cannot be set if chunk_mb is also specified. The default is None.

  • display_progress (bool, default=False) – Display a progress bar with iteration rate and estimated completion time.

  • progress_bar_class (dict, optional) – The progress bar class to use. Defaults to tqdm.tqdm if the TQDM package is installed.

  • progress_bar_options (dict, optional) – Dictionary of keyword arguments to be passed directly to tqdm. See tqdm/tqdm for options.