Metadata-Version: 2.1
Name: segmentationextractors
Version: 0.1.0
Summary: Python module for extracting optical physiology ROIs and traces for various file types and formats
Home-page: https://github.com/ben-dichter-consulting/segmentationextractors
Author: Saksham Sharda, Ben Dichter
Author-email: saksham20.sharda@gmail.com
License: UNKNOWN
Description: # SegmentationExtractors
        Python-based module for extracting from, converting between, and handling recorded and optical imaging data from several file formats. Inspired by [SpikeExtractors](https://github.com/SpikeInterface/spikeextractors).
        ![image](https://drive.google.com/uc?export=view&id=1bhRA3kyu3SA3k-xWz5psRxLsuP3BJEBg)
        
        ## 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](https://www.lfd.uci.edu/~gohlke/pythonlibs/#sima).
        2.  `pip install <download-path-to-wheels.whl>`
        3.  `pip install segmentationextractors`
        
        ## Usage:
        #### Currently supported file types:
        1. [calciumImagingAnalysis](https://github.com/bahanonu/calciumImagingAnalysis) (CNMF-E, EXTRACT),
        2. [SIMA](http://www.losonczylab.org/sima/1.3.2/),
        3. [NWB](https://pynwb.readthedocs.io/en/stable/),
        4. Numpy (a data format for manual input of optical physiology data as various numpy datasets)
        
        #### Functionality:
        Interconversion amongst the various data formats as well as conversion to the NWB format and back.  
        
        #### Features:
        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',
                            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 = 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
                            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
        ```
        #### 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](https://drive.google.com/drive/folders/1CeDfr6yza_bh0vYD2E1HF_3_S8pg2yLW?usp=sharing).
        
        ## 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.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Description-Content-Type: text/markdown
