Skip to main content

Python module for extracting optical physiology ROIs and traces for various file types and formats

Project description


Python-based module for extracting from, converting between, and handling recorded and optical imaging data from several file formats. Inspired by SpikeExtractors. image

Getting Started:

Installation (<=python3.6) :

pip install segmentationextractors

Installation (>=python3.7) :

Will need a manual installation for package dependency SIMA since it does not currently support python 3.7:

  1. Download SIMA wheels distribution here.
  2. pip install <download-path-to-wheels.whl>
  3. pip install segmentationextractors


Currently supported file types:

  1. calciumImagingAnalysis (CNMF-E, EXTRACT),
  2. SIMA,
  3. NWB,
  4. 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.


  1. SegmentationExtractor object:
    • seg_obj.get_channel_names() : List of optical channel names
    • seg_obj.get_num_channels() : Number of channels
    • seg_obj.get_movie_framesize(): (height, width) of raw movie
    • seg_obj.get_movie_location(): Location of storage of movie/tiff images
    • seg_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 to 0:num_of_rois

SegmentationExtractor object creation:

import segmentationextractors
seg_obj_cnmfe = segmentationextractors.CnmfeSegmentationExtractor('cnmfe_filename.mat') # cnmfe
seg_obj_extract = segmentationextractors.ExtractSegmentationExtractor('extract_filename.mat') # extract
seg_obj_sima = segmentationextractors.SimaSegmentationExtractor('sima_filename.sima') # SIMA
seg_obj_numpy = segmentationextractors.NumpySegmentationExtractor(
                    filepath = 'path-to-file',
                    channel_names=['Blue']) # Numpy object
seg_obj_nwb = segmentationextractors.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
                    neuron_roi_response_series_name=None, # roi_response_series name to extract and store data from
                    background_roi_response_series_name=None) # nwb object

Data format conversion: SegmentationExtractor to NWB:

    segmentationextractors.NwbSegmentationExtractor.write_recording(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:

  • Example datasets for each of the file formats can be downloaded here.

Class description:

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

  • NumpySegmentationExtractor objects are built to contain 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:

  • Class used to extract data from the NWB data format. Also implements a static method to write any format specific object to NWB.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

segmentationextractors-0.1.0.tar.gz (19.5 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page