cell detection in calcium imaging recordings
Pipeline for processing two-photon calcium imaging data.
Copyright (C) 2018 Howard Hughes Medical Institute Janelia Research Campus
suite2p includes the following modules:
This code was written by Carsen Stringer and Marius Pachitariu.
For support, please open an issue.
The reference paper is here.
The deconvolution algorithm is based on this paper, with settings based on this paper.
See this twitter thread for GUI demonstrations.
The matlab version is available here. Note that the algorithm is older and will not work as well on non-circular ROIs.
Lectures on how suite2p works are available here.
Install an Anaconda distribution of Python -- Choose Python 3.x and your operating system. Note you might need to use an anaconda prompt if you did not add anaconda to the path.
environment.ymlfile from the repository. You can do this by cloning the repository, or copy-pasting the text from the file into a text document on your local computer.
condafor python 3 in the path
environment.ymlis and run
conda env create -f environment.yml
conda activate suite2p
python -m suite2pand you're all set.
suite2p --versionin the terminal will print the install version of suite2p.
If you have an older
suite2penvironment you can remove it with
conda env remove -n suite2pbefore creating a new one.
Note you will always have to run conda activate suite2p before you run suite2p. Conda ensures mkl_fft and numba run correctly and quickly on your machine. If you want to run jupyter notebooks in this environment, then also
conda install jupyter.
To upgrade the suite2p (package here), run the following in the environment: ~~~~ pip install --upgrade suite2p ~~~~
Common issues
If you are on Yosemite Mac OS, PyQt doesn't work, and you won't be able to install suite2p. More recent versions of Mac OS are fine.
The software has been heavily tested on Windows 10 and Ubuntu 18.04, and less well tested on Mac OS. Please post an issue if you have installation problems. The registration step runs faster on Ubuntu than Windows, so if you have a choice we recommend using the Ubuntu OS.
cd suite2pin an anaconda prompt / command prompt with
condafor python 3 in the path
conda env create -f environment.yml
conda activate suite2p(you will have to activate every time you want to run suite2p)
pip install -e .[data]
dvc pull -r gdrive-travis(read-only access). If you need to have read/write access to the files, run
dvc pulland follow the authentication instructions in the output. Note: do not commit the json credentials file that comes out afterwards, git should ignore it.
python setup.py test
An example dataset is provided here. It's a single-plane, single-channel recording.
The quickest way to start is to open the GUI from a command line terminal. You might need to open an anaconda prompt if you did not add anaconda to the path. Make sure to run this from a directory in which you have WRITE access (suite2p saves a couple temporary files in your current directory): ~~~~ suite2p ~~~~ Then: 1. File -> Run suite2p (or ctrl+r) 2. Setup a configuration - -> Add directory which contains tiffs to datapath (can be multiple folders, but add them one at a time) - -> OR choose an h5 file which has a key with the data, data shape should be time x pixels x pixels (you can type in the key name for the data after you choose the file) - -> Add savepath ((otherwise the data directory is used as save path)) - -> Add fast_disk (this is where the binary file of registered data will be created, choose an SSD for this path) ((otherwise the save path is used as the fast disk path)) - Set some parameters (see full list below). At the minimum: ~~~~ nplanes, nchannels, tau, fs ~~~~ 3. Press run and wait. Messages should start appearing in the embedded command line. 4. When the run is finished, the results will open in the GUI window and there you can visualize and refine the results (see below).
suite2p output goes to a folder called "suite2p" inside your savepath, which by default is the same as the datapath. If you ran suite2p in the GUI, it loads the results automatically. Otherwise, load the results with File -> Load results.
The GUI serves two main functions:
Main GUI controls (works in all views):
You can add your manual curation to a pre-built classifier by clicking "Add current data to classifier". Or you can make a brand-new classifier from a list of "iscell.npy" files that you've manually curated. The default classifier in the GUI is initialized as the suite2p classifier, but you can overwrite it by adding to it, or loading a different classifier and saving it as the default. The default classifier is used in the pipeline to produce the initial "iscell.npy" file.
From the command line: ~~~~ suite2p --ops --db ~~~~
From Python/Jupyter ~~~~python from suite2p.runs2p import runs2p ops1 = run_s2p(ops, db) ~~~~
See our example jupyter notebook here. It also explains how to batch-run suite2p.
F.npy: array of fluorescence traces (ROIs by timepoints) Fneu.npy: array of neuropil fluorescence traces (ROIs by timepoints) spks.npy: array of deconvolved traces (ROIs by timepoints) stat.npy: array of statistics computed for each cell (ROIs by 1) ops.npy: options and intermediate outputs iscell.npy: specifies whether an ROI is a cell, first column is 0/1, and second column is probability that the ROI is a cell based on the default classifier
suite2p relies on the following excellent packages (which are automatically installed with conda/pip if missing): - rastermap - pyqtgraph - PyQt5 - numpy (>=1.16.0) - numba - mkl_fft - scanimage-tiff-reader - scipy - h5py - scikit-learn - scanimage-tiff-reader - tifffile - natsort - matplotlib (not for plotting (only using hsvtorgb and colormap function), should not conflict with PyQt5)
Logo was designed by Shelby Stringer and Chris Czaja.