ROI extractors#

Interface with roiextractors#

get_full_ophys_metadata()[source]#

Returns a fully specified ophys metadata example with realistic values.

Users can call this to get a complete example of what the metadata structure looks like, edit only the fields they need, and discard the rest. Each call returns an independent copy so callers can modify it freely without affecting other calls.

# TODO: expand with segmentation metadata once we get to that PR

add_imaging_to_nwbfile(imaging: ImagingExtractor, nwbfile: NWBFile, metadata: dict | None = None, *args, 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, metadata_key: str | None = None) → NWBFile[source]#

Add imaging data from an ImagingExtractor object to an NWBFile.

Supports both old list-based metadata (via photon_series_index) and new dict-based metadata (via metadata_key).

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. Used with the old list-based metadata format.

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

  • metadata_key (str, optional) – The key in metadata["Ophys"]["MicroscopySeries"] identifying the series. When provided, uses the new dict-based metadata format and photon_series_index is ignored.

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, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries', *, iterator_type: str | None = 'v2', iterator_options: dict | None = None, backend: Literal['hdf5', 'zarr'] | None = None, backend_configuration: HDF5BackendConfiguration | ZarrBackendConfiguration | None = None, append_on_disk_nwbfile: bool = False) → NWBFile | None[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, optional) – Path for where to write the NWBFile. If not provided, only adds data to the in-memory nwbfile without writing to disk. Deprecated: Using this function without nwbfile_path is deprecated. Use add_imaging_to_nwbfile instead.

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

    write_imaging_to_nwbfile(imaging=my_imaging_extractor, nwbfile=my_nwbfile)

    will result in the appropriate changes to the my_nwbfile object.

  • 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: False) – If ‘nwbfile_path’ is specified, informs user after a successful write operation.

  • photon_series_type ({“TwoPhotonSeries”, “OnePhotonSeries”}, default: “TwoPhotonSeries”) – The type of photon series to add.

  • 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. See the pynwb tutorial on iterative write for more information on chunked data writing.

  • backend ({“hdf5”, “zarr”}, optional) – The type of backend to use when writing the file. If a backend_configuration is not specified, the default type will be “hdf5”. If a backend_configuration is specified, then the type will be auto-detected.

  • backend_configuration (HDF5BackendConfiguration or ZarrBackendConfiguration, optional) – The configuration model to use when configuring the datasets for this backend.

  • append_on_disk_nwbfile (bool, default: False) – Whether to append to an existing NWBFile on disk. If True, the nwbfile parameter must be None.

Returns:

The NWBFile object when writing a new file or using an in-memory nwbfile. Returns None when appending to an existing file on disk (append_on_disk_nwbfile=True). Deprecated: Returning NWBFile in append mode is deprecated and will return None on or after June 2026.

Return type:

NWBFile or None

add_segmentation_to_nwbfile(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: dict | None = None, *args, 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, backend: Literal['hdf5', 'zarr'] | None = None, backend_configuration: HDF5BackendConfiguration | ZarrBackendConfiguration | None = None, append_on_disk_nwbfile: bool = False) → NWBFile | None[source]#

Primary method for writing a SegmentationExtractor object to an NWBFile.

Parameters:

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

  • nwbfile_path (FilePath, optional) – Path for where to write the NWBFile. If not provided, only adds data to the in-memory nwbfile without writing to disk. Deprecated: Using this function without nwbfile_path is deprecated. Use add_segmentation_to_nwbfile instead.

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

  • 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: False) – 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 ({“image”, “pixel”, “voxel”}, 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.

  • backend ({“hdf5”, “zarr”}, optional) – The type of backend to use when writing the file. If a backend_configuration is not specified, the default type will be “hdf5”. If a backend_configuration is specified, then the type will be auto-detected.

  • backend_configuration (HDF5BackendConfiguration or ZarrBackendConfiguration, optional) – The configuration model to use when configuring the datasets for this backend.

  • append_on_disk_nwbfile (bool, default: False) – Whether to append to an existing NWBFile on disk. If True, the nwbfile parameter must be None.

Returns:

The NWBFile object when writing a new file or using an in-memory nwbfile. Returns None when appending to an existing file on disk (append_on_disk_nwbfile=True). Deprecated: Returning NWBFile in append mode is deprecated and will return None on or after June 2026.

Return type:

NWBFile or None

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.

property shape#

Return (num_frames, width, height) or (num_frames, width, height, num_planes) for volumetric.

property ndim#

Return the number of dimensions (3 for 2D imaging, 4 for volumetric).