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: Optional[dict] = None) → NWBFile[source]#: Add optical physiology devices from metadata. The metadata concerning the optical physiology should be stored in metadata[“Ophys][“Device”] This function handles both a text specification of the device to be built and an actual pynwb.Device object.

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

Adds the imaging plane specified by the metadata to the nwb file. The imaging plane that is added is the one located in metadata[“Ophys”][“ImagingPlane”][imaging_plane_index]

Parameters

nwbfile (NWBFile) – An previously defined -in memory- NWBFile.
metadata (dict) – The metadata in the nwb conversion tools format.
imaging_plane_name (str) – The name of the imaging plane to be added.

Returns

The nwbfile passed as an input with the imaging plane added.

Return type

NWBFile

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

Adds the image segmentation specified by the metadata to the nwb file.

Parameters

nwbfile (NWBFile) – The nwbfile to add the image segmentation to.
metadata (dict) – The metadata to create the image segmentation from.

Returns

The NWBFile passed as an input with the image segmentation added.

Return type

NWBFile

add_photon_series_to_nwbfile(imaging: ImagingExtractor, 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', iterator_type: Optional[str] = 'v2', iterator_options: Optional[dict] = None, always_write_timestamps: bool = False) → NWBFile[source]#

Auxiliary static method for nwbextractor.

Adds photon series from ImagingExtractor to NWB file object. The photon series can be added to the NWB file either as a TwoPhotonSeries or OnePhotonSeries object.

Parameters

imaging (ImagingExtractor) – The imaging extractor to get the data from.
nwbfile (NWBFile) – The nwbfile to add the photon series to.
metadata (dict) – The metadata for the photon series.
photon_series_type ({‘OnePhotonSeries’, ‘TwoPhotonSeries’}, optional) – The type of photon series to add, default is TwoPhotonSeries.
photon_series_index (int, default: 0) – The metadata for the photon series is a list of the different photon series to add. Specify which element of the list with this parameter.
parent_container ({‘acquisition’, ‘processing/ophys’}, optional) – The container where the photon series is added, default is nwbfile.acquisition. When ‘processing/ophys’ is chosen, the photon series is added to nwbfile.processing['ophys'].
iterator_type (str, default: ‘v2’) – The type of iterator to use when adding the photon series to the NWB file.
iterator_options (dict, optional)
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 NWBFile passed as an input with the photon series added.

Return type

NWBFile

add_imaging_to_nwbfile(imaging: ImagingExtractor, nwbfile: NWBFile, metadata: Optional[dict] = None, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries', photon_series_index: int = 0, iterator_type: Optional[str] = 'v2', iterator_options: Optional[dict] = 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: Optional[Path] = None, nwbfile: Optional[NWBFile] = None, metadata: Optional[dict] = None, overwrite: bool = False, verbose: bool = False, iterator_type: str = 'v2', iterator_options: Optional[dict] = 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”, “v1”, None}, default: ‘v2’) – The type of DataChunkIterator to use. ‘v1’ is the original DataChunkIterator of the hdmf data_utils. ‘v2’ is the locally developed SpikeInterfaceRecordingDataChunkIterator, which offers full control over chunking. None: write the TimeSeries with no memory chunking.
iterator_options (dict, optional) – Dictionary of options for the iterator. For ‘v1’ this is the same as the options for the DataChunkIterator. For ‘v2’, see https://hdmf.readthedocs.io/en/stable/hdmf.data_utils.html#hdmf.data_utils.GenericDataChunkIterator for the full list of options.

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: Optional[dict], plane_segmentation_name: Optional[str] = None, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Optional[str] = 'image', iterator_options: Optional[dict] = None) → NWBFile[source]#

Adds the plane segmentation specified by the metadata to the image segmentation.

If the plane segmentation already exists in the image segmentation, it is not added again.

Parameters

segmentation_extractor (SegmentationExtractor) – The segmentation extractor to get the results from.
nwbfile (NWBFile) – The NWBFile to add the plane segmentation to.
metadata (dict, optional) – The metadata for the plane segmentation.
plane_segmentation_name (str, optional) – The name of the plane segmentation to be added.
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’, or None. If None, the mask information is not written to the NWB file.
iterator_options (dict, optional) – The options to use when iterating over the image masks of the segmentation extractor.

Returns

The nwbfile passed as an input with the plane segmentation added.

Return type

NWBFile

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

Add background plane segmentation data from a SegmentationExtractor object to an NWBFile.

Parameters

segmentation_extractor (SegmentationExtractor) – The extractor object containing background segmentation data.
nwbfile (NWBFile) – The NWB file to which the background plane segmentation will be added.
metadata (dict, optional) – Metadata for the NWBFile, by default None.
background_plane_segmentation_name (str, optional) – The name of the background PlaneSegmentation object to be added, by default None.
mask_type (str, optional) – Type of mask to use for segmentation; options are “image”, “pixel”, or “voxel”, by default “image”.
iterator_options (dict, optional) – Options for iterating over the segmentation data, by default None.
compression_options (dict, optional) – Deprecated: options for compression; will be removed after 2024-10-01, by default None.

Returns

The NWBFile with the added background plane segmentation data.

Return type

NWBFile

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

Adds the fluorescence traces specified by the metadata to the nwb file. The fluorescence traces that are added are the one located in metadata[“Ophys”][“Fluorescence”]. The df/F traces that are added are the one located in metadata[“Ophys”][“DfOverF”].

Parameters

segmentation_extractor (SegmentationExtractor) – The segmentation extractor to get the traces from.
nwbfile (NWBFile) – The nwbfile to add the fluorescence traces to.
metadata (dict) – The metadata for the fluorescence traces.
plane_segmentation_name (str, optional) – The name of the plane segmentation that identifies which plane to add the fluorescence traces to.
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.
iterator_options (dict, optional)

Returns

The nwbfile passed as an input with the fluorescence traces added.

Return type

NWBFile

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

Parameters

segmentation_extractor (SegmentationExtractor) – The segmentation extractor to get the traces from.
nwbfile (NWBFile) – The nwbfile to add the fluorescence traces to.
metadata (dict) – The metadata for the fluorescence traces.
plane_segmentation_name (str, optional) – The name of the plane segmentation that identifies which plane to add the fluorescence traces to.
iterator_options (dict, optional)

Returns

The nwbfile passed as an input with the fluorescence traces added.

Return type

NWBFile

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

Adds summary images (i.e. mean and correlation) to the nwbfile using an image container object pynwb.Image

Parameters

nwbfile (NWBFile) – An previously defined -in memory- NWBFile.
segmentation_extractor (SegmentationExtractor) – A segmentation extractor object from roiextractors.
metadata (dict, optional) – The metadata for the summary images is located in metadata[“Ophys”][“SegmentationImages”].
plane_segmentation_name (str, optional) – The name of the plane segmentation that identifies which images to add.

Returns

The nwbfile passed as an input with the summary images added.

Return type

NWBFile

add_segmentation_to_nwbfile(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: Optional[dict] = None, plane_segmentation_name: Optional[str] = None, background_plane_segmentation_name: Optional[str] = None, include_background_segmentation: bool = False, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Optional[str] = 'image', iterator_options: Optional[dict] = 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, optional) – 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: Optional[Path] = None, nwbfile: Optional[NWBFile] = None, metadata: Optional[dict] = None, overwrite: bool = False, verbose: bool = False, include_background_segmentation: bool = False, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Optional[str] = 'image', iterator_options: Optional[dict] = 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_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, 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’, or None. If None, the mask information is not written to the NWB file.
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: Optional[float] = None, buffer_shape: Optional[tuple] = None, chunk_mb: Optional[float] = None, chunk_shape: Optional[tuple] = None, display_progress: bool = False, progress_bar_class: Optional[tqdm.std.tqdm] = None, progress_bar_options: Optional[dict] = 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.