suite2p (Custom Fork)

This is a fork of the official suite2p repository.
Maintained by Ahmed Jamali / Yaksi- Lab / Kavli Institute for Systems Neuroscience / Norwegian University of Science and Technology.

This fork contains modifications and extra code snippets to handle the processing of SciScan raw files and other specialized use cases.
It retains the GPL v3 license from the original authors.

For the official Suite2p code, issues, or documentation, please visit the
MouseLand suite2p GitHub.

---

---

Original README (with slight edits for fork)

Pipeline for processing two-photon calcium imaging data.
Copyright (C) 2018 Howard Hughes Medical Institute Janelia Research Campus

suite2p includes the following modules:

• Registration
• Cell detection
• Spike detection
• Visualization GUI

This code was written by Carsen Stringer and Marius Pachitariu.
For support on the official version, please open an issue on the official repo.

The reference paper is here.
The deconvolution algorithm is based on this paper,
with settings based on this paper.

You can also run suite2p in Google Colab (no local install needed, though recommended):

Note: In a Colab environment, the GUI is not accessible, but you can process data and then download outputs locally to view in the GUI.

See this twitter thread for GUI demonstrations.

The older MATLAB version is available here.
Note that the algorithm is older and may not work as well on non-circular ROIs.

Lectures on how suite2p works are available here.

CITATION

If you use this package in your research, please cite the paper:

Pachitariu, M., Stringer, C., Schröder, S., Dipoppa, M., Rossi, L. F., Carandini, M., & Harris, K. D. (2016). Suite2p: beyond 10,000 neurons with standard two-photon microscopy. BioRxiv, 061507.

Documentation

For full documentation, please see the official Suite2p docs.

Local installation

1. Install an Anaconda distribution of Python -- Choose Python 3.8 and your operating system. Note you might need to use an anaconda prompt if you did not add anaconda to the path.
2. Open an anaconda prompt / command prompt with conda for python 3 in the path
3. Create a new environment with conda create --name suite2pR python=3.9.
4. To activate this new environment, run conda activate suite2pR.
5. The simplest way is

pip install git+https://github.com/AhmedJamali/suite2pR.git

6. with GUI dependencies:

pip install "suite2p[gui] @ git+https://github.com/AhmedJamali/suite2pR.git#subdirectory=."

Dependencies

This package relies on the awesomeness of pyqtgraph, PyQt6, torch, numpy, numba, scanimage-tiff-reader, scipy, scikit-learn, tifffile, natsort, and our neural visualization tool rastermap. You can pip install or conda install all of these packages. If having issues with PyQt6, then try to install within it conda install pyqt. On Ubuntu you may need to sudo apt-get install libegl1 to support PyQt6. Alternatively, you can use PyQt5 by running pip uninstall PyQt6 and pip install PyQt5. If you already have a PyQt version installed, suite2p will not install a new one.

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.

Installing the latest github version of the code

If you want to download and edit the code, and use that version,

1. Clone the repository with git and cd suite2p
2. Run pip install -e . in that folder

Examples from the official repository

An example dataset is provided here. It's a single-plane, single-channel recording.

Getting started

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 data_path (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 save_path ((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).

Using the GUI

The suite2p output goes to a folder called "suite2p" inside your save_path, which by default is the same as the data_path. If you ran suite2p in the GUI, it loads the results automatically. Otherwise, you can load the results with File -> Load results or by dragging and dropping the stat.npy file into the GUI.

The GUI serves two main functions:

1. Checking the quality of the data and results.
   • there are currently several views such as the enhanced mean image, the ROI masks, the correlation map, the correlation among cells, and the ROI+neuropil traces
   • by selecting multiple cells (with "Draw selection" or ctrl+left-click), you can view the activity of multiple ROIs simultaneously in the lower plot
   • there are also population-level visualizations, such as rastermap
2. Classify ROIs into cell / not cell (left and right views respectively)
   • the default classifier included should work well in a variety of scenarios.
   • a user-classifier can be learnt from manual curation, thus adapting to the statistics of your own data.
   • the GUI automatically saves which ROIs are good in "iscell.npy". The second column contains the probability that the ROI is a cell based on the currently loaded classifier.

Main GUI controls (works in all views):

1. Pan = Left-Click + drag
2. Zoom = (Scroll wheel) OR (Right-Click + drag)
3. Full view = Double left-click OR escape key
4. Swap cell = Right-click on the cell
5. Select multiple cells = (Ctrl + left-click) OR (SHIFT + left-click) AND/OR ("Draw selection" button)

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.

Other ways to call Suite2p

1. From the command line:

suite2p --ops <path to ops.npy> --db <path to db.npy>

2. From Python/Jupyter

from suite2p.run_s2p import run_s2p
ops1 = run_s2p(ops, db)

See our example jupyter notebook here.

Outputs

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

License

Copyright (C) 2023 Howard Hughes Medical Institute Janelia Research Campus, the labs of Carsen Stringer and Marius Pachitariu.

This code is licensed under GPL v3 (no redistribution without credit, and no redistribution in private repos, see the license for more details).

Logo

Logo was designed by Shelby Stringer and Chris Czaja.

NOTE: For questions related to this custom fork or its modifications, please contact Ahmed Jamali / Yaksi- Lab / Kavli Institute for Systems Neuroscience / Norwegian University of Science and Technology. For official Suite2p help or issues, go to the official Suite2p repo.