ROI extractors#

Interface with roiextractors#

get_default_ophys_metadata() → DeepDict[source]#

Fill default metadata for Device and ImagingPlane.

get_default_segmentation_metadata() → DeepDict[source]#

Fill default metadata for segmentation.

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)

  • photon_series_type ({‘OnePhotonSeries’, ‘TwoPhotonSeries’}, optional)

add_devices(nwbfile: NWBFile, metadata: dict) → 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.

_create_imaging_plane_from_metadata(nwbfile: NWBFile, imaging_plane_metadata: dict) → ImagingPlane[source]#

Private auxiliary function to create an ImagingPlane object from pynwb using the imaging_plane_metadata.

Parameters

  • nwbfile (NWBFile) – An previously defined -in memory- NWBFile.

  • imaging_plane_metadata (dict) – The metadata to create the ImagingPlane object.

Returns

The created ImagingPlane.

Return type

ImagingPlane

add_imaging_plane(nwbfile: NWBFile, metadata: dict, imaging_plane_name: Optional[str] = None, imaging_plane_index: Optional[int] = 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(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(imaging: ImagingExtractor, nwbfile: NWBFile, metadata: dict, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries', photon_series_index: int = 0, parent_container: Literal['acquisition', 'processing/ophys'] = 'acquisition', two_photon_series_index: Optional[int] = None, iterator_type: Optional[str] = 'v2', iterator_options: Optional[dict] = None) → 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'].

Returns

The NWBFile passed as an input with the photon series added.

Return type

NWBFile

check_if_imaging_fits_into_memory(imaging: ImagingExtractor) → None[source]#

Raise an error if the full traces of an imaging extractor are larger than available memory.

Parameters

imaging (ImagingExtractor) – An imaging extractor object from roiextractors.

Raises

MemoryError –

_imaging_frames_to_hdmf_iterator(imaging: ImagingExtractor, iterator_type: Optional[str] = 'v2', iterator_options: Optional[dict] = None)[source]#

Private auxiliary method to wrap frames from an ImagingExtractor into a DataChunkIterator.

Parameters

  • imaging (ImagingExtractor) – The imaging extractor to get the data from.

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

Returns

The frames of the imaging extractor wrapped in an iterator object.

Return type

DataChunkIterator

write_imaging(imaging: ImagingExtractor, nwbfile_path: Optional[FilePathType] = None, nwbfile: Optional[NWBFile] = None, metadata: Optional[dict] = None, overwrite: bool = False, verbose: bool = True, iterator_type: str = 'v2', iterator_options: Optional[dict] = None, photon_series_type: Literal['TwoPhotonSeries', 'OnePhotonSeries'] = 'TwoPhotonSeries', buffer_size: Optional[int] = 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 (FilePathType) – 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

sgmextractor (SegmentationExtractor)

add_plane_segmentation(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: Optional[dict], plane_segmentation_name: Optional[str] = None, plane_segmentation_index: Optional[int] = None, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Optional[str] = 'image', iterator_options: Optional[dict] = None, compression_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 ({‘image’, ‘pixel’, ‘voxel’}, optional) – There are two types of ROI masks in NWB: ImageMasks and PixelMasks. 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 three as mask_type=’image’, ‘pixel’, ‘voxel’, or None. If None, the mask information is not written to the NWB file. Defaults to ‘image’.

  • iterator_options (dict, optional) – The options to use when iterating over the image masks of the segmentation extractor.

  • compression_options (dict, optional) – The options to use when compressing the image masks of the segmentation extractor.

Returns

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

Return type

NWBFile

add_fluorescence_traces(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: Optional[dict], plane_segmentation_name: Optional[str] = None, plane_index: Optional[int] = None, 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.

  • iterator_options (dict, optional)

  • compression_options (dict, optional)

Returns

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

Return type

NWBFile

_create_roi_table_region(segmentation_extractor: SegmentationExtractor, nwbfile: NWBFile, metadata: dict, plane_segmentation_name: Optional[str] = None, plane_index: Optional[int] = None)[source]#

Private method to create ROI table region.

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 that identifies which plane to add the ROI table region to.

_get_segmentation_data_interface(nwbfile: NWBFile, data_interface_name: str)[source]#

Private method to get the container for the segmentation data. If the container does not exist, it is created.

add_summary_images(nwbfile: NWBFile, segmentation_extractor: SegmentationExtractor, metadata: Optional[dict] = None, plane_segmentation_name: Optional[str] = None, images_set_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

write_segmentation(segmentation_extractor: SegmentationExtractor, nwbfile_path: Optional[FilePathType] = None, nwbfile: Optional[NWBFile] = None, metadata: Optional[dict] = None, overwrite: bool = False, verbose: bool = True, include_roi_centroids: bool = True, include_roi_acceptance: bool = True, mask_type: Optional[str] = 'image', iterator_options: Optional[dict] = None, compression_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 (FilePathType) – 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.

  • buffer_size (int, default: 10) – The buffer size in GB.

  • plane_num (int, default: 0) – The plane number to be extracted.

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

    Defaults to True.

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

    Defaults to True.

  • mask_type (str, optional) – There are two types of ROI masks in NWB: ImageMasks and PixelMasks. 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. Defaults to ‘image’.

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_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. For more details, see https://support.hdfgroup.org/HDF5/doc/TechNotes/TechNote-HDF5-ImprovingIOPerformanceCompressedDatasets.pdf

  • 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_options (dict, optional) – Dictionary of keyword arguments to be passed directly to tqdm. See tqdm/tqdm for options.

_get_default_chunk_shape(chunk_mb: float) → tuple[source]#

Select the chunk_shape less than the threshold of chunk_mb while keeping the original image size.

_get_scaled_buffer_shape(buffer_gb: float, chunk_shape: tuple) → tuple[source]#

Select the buffer_shape less than the threshold of buffer_gb that is also a multiple of the chunk_shape.

_get_dtype() → dtype[source]#

Retrieve the dtype of the data using minimal I/O.

_get_maxshape() → tuple[source]#

Retrieve the maximum bounds of the data shape using minimal I/O.

_get_data(selection: Tuple[slice]) → ndarray[source]#

Retrieve the data specified by the selection using minimal I/O.

The developer of a new implementation of the GenericDataChunkIterator must ensure the data is actually loaded into memory, and not simply mapped.

Parameters

selection (Tuple[slice]) – tuple of slices, each indicating the selection indexed with respect to maxshape for that axis. Each axis of tuple is a slice of the full shape from which to pull data into the buffer.

Returns

Array of data specified by selection

Return type

numpy.ndarray