Python-based module for extracting from, converting between, and handling recorded and optical imaging data from several file formats. Inspired by SpikeExtractors.
Developed by CatalystNeuro.
pip install roiextractors
- HDF5
- TIFF
- STK
- FLI
- SBX
- calciumImagingAnalysis (CNMF-E, EXTRACT)
- SIMA
- NWB
- suite2p
- Numpy (a data format for manual input of optical physiology data as various numpy datasets)
Interconversion amongst the various data formats as well as conversion to the NWB format and back.
- SegmentationExtractor object:
seg_obj.get_channel_names()
: List of optical channel namesseg_obj.get_num_channels()
: Number of channelsseg_obj.get_movie_framesize()
: (height, width) of raw movieseg_obj.get_movie_location()
: Location of storage of movie/tiff imagesseg_obj.get_image_masks(self, roi_ids=None)
: Image masks as (ht, wd, num_rois) with each value as the weight given during segmentation operation.seg_obj.get_pixel_masks(roi_ids=None)
: Get pixel masks as (total_pixels(ht*wid), no_rois)seg_obj.get_traces(self, roi_ids=None, start_frame=None, end_frame=None)
: df/F trace as (num_rois, num_frames)seg_obj.get_sampling_frequency()
: Sampling frequency of movie/df/F trace.seg_obj.get_roi_locations()
: Centroid pixel location of the ROI (Regions Of Interest) as (x,y).seg_obj.get_num_rois()
: Total number of ROIs after segmentation operation.seg_obj.get_roi_ids()
: Any integer tags associated with an ROI, defaults to0:num_of_rois
import roiextractors
import numpy as np
seg_obj_cnmfe = roiextractors.CnmfeSegmentationExtractor('cnmfe_filename.mat') # cnmfe
seg_obj_extract = roiextractors.ExtractSegmentationExtractor('extract_filename.mat') # extract
seg_obj_sima = roiextractors.SimaSegmentationExtractor('sima_filename.sima') # SIMA
seg_obj_numpy = roiextractors.NumpySegmentationExtractor(
filepath = 'path-to-file',
masks=np.random.rand(movie_size[0],movie_size[1],no_rois),
signal=np.random.randn(num_rois,num_frames),
roi_idx=np.random.randint(no_rois,size=[1,no_rois]),
no_of_channels=None,
summary_image=None,
channel_names=['Blue'],
) # Numpy object
seg_obj_nwb = roiextractors.NwbSegmentationExtractor(
filepath_of_nwb, optical_channel_name=None, # optical channel to extract and store info from
imaging_plane_name=None, image_series_name=None, # imaging plane to extract and store data from
processing_module_name=None,
neuron_roi_response_series_name=None, # roi_response_series name to extract and store data from
background_roi_response_series_name=None) # nwb object
roiextractors.NwbSegmentationExtractor.write_segmentation(seg_obj, saveloc,
propertydict=[{'name': 'ROI feature 1,
'description': 'additional attribute of each ROI',
'data': np.random.rand(1,no_rois),
'id': seg_obj.get_roi_ids()},
{'name': 'ROI feature 2,
'description': 'additional attribute of each ROI',
'data': np.random.rand(1,no_rois),
'id': seg_obj.get_roi_ids()}],
nwbfile_kwargs={'session_description': 'nwbfiledesc',
'experimenter': 'experimenter name',
'lab': 'test lab',
'session_id': 'test sess id'},
emission_lambda=400.0, excitation_lambda=500.0)
Example datasets are maintained at https://gin.g-node.org/CatalystNeuro/ophys_testing_data.
To download test data on your machine,
- Install the gin client (instructions here)
- Use gin to download data.
gin get CatalystNeuro/ophys_testing_data
cd ophys_testing_data
gin get-content
- Change the file at
roiextractors/tests/gin_test_config.json
to point to the path of this test data
To update data later, cd
into the test directory and run gin get-content
-
SegmentationExtractor: An abstract class that contains all the meta-data and output data from the ROI segmentation operation when applied to the pre-processed data. It also contains methods to read from and write to various data formats ouput from the processing pipelines like SIMA, CaImAn, Suite2p, CNNM-E.
-
NumpySegmentationExtractor: Contains all data coming from a file format for which there is currently no support. To construct this, all data must be entered manually as arguments.
-
CnmfeSegmentationExtractor: This class inherits from the SegmentationExtractor class, having all its funtionality specifically applied to the dataset output from the 'CNMF-E' ROI segmentation method.
-
ExtractSegmentationExtractor: This class inherits from the SegmentationExtractor class, having all its funtionality specifically applied to the dataset output from the 'EXTRACT' ROI segmentation method.
-
SimaSegmentationExtractor: This class inherits from the SegmentationExtractor class, having all its funtionality specifically applied to the dataset output from the 'SIMA' ROI segmentation method.
-
NwbSegmentationExtractor: Extracts data from the NWB data format. Also implements a static method to write any format specific object to NWB.
-
Suite2PSegmentationExtractor: Extracts data from suite2p format.
Will need a manual installation for package dependency SIMA since it does not currently support python 3.7:
- Download SIMA wheels distribution here.
pip install <download-path-to-wheels.whl>
pip install roiextractors
- Stanford University as part of the Ripple U19 project (U19NS104590).
- LBNL as part of the NWB U24 (U24NS120057).