Home

Awesome

<a href="https://colab.research.google.com/drive/1vkp-uPV8tKavmX12bcN2L-jYH8_MgmHL?usp=sharing"><img src="https://img.shields.io/badge/-Colab%20Demo-blue" /></a>

CaImAn

<img src="https://github.com/flatironinstitute/CaImAn/blob/main/docs/LOGOS/Caiman_logo_2.png" width="400" align="right">

A Python toolbox for large-scale Calcium Imaging Analysis.

CaImAn implements a set of essential methods required to analyze calcium and voltage imaging data. It provides fast and scalable algorithms for motion correction, source extraction, spike deconvolution, and registering neurons across multiple sessions. It is suitable for both two-photon and one-photon fluorescence microscopy data, and can be run in both offline and online modes. Documentation is here.

Caiman Central

Quick start

Follow these three steps to get started quickly, from installation to working through a demo notebook. If you do not already have conda installed, you can find it here. There is a video walkthrough of the following steps here.

Step 1: Install caiman

The following is all done in your anaconda prompt, starting in your base environment:

conda install -n base -c conda-forge mamba   # install mamba in base environment
mamba create -n caiman -c conda-forge caiman # install caiman
conda activate caiman  # activate virtual environment

Step 2: Download code samples and data sets

Create a working directory called caiman_data that includes code samples and related data. Run the following command from the same virtual environment that you created in Step 1:

caimanmanager install

Step 3: Try out a demo notebook

Go into the working directory you created in Step 2, and open a Jupyter notebook:

cd <your home>/caiman_data/
jupyter notebook 

Jupyter will open. Navigate to demos/notebooks/ and click on demo_pipeline.ipynb to get started with a demo.

Note that what counts as <your home> in the first line depends on your OS/computer. Be sure to fill in your actual home directory. On Linux/Mac it is ~ while on Windows it will be something like C:\Users\your_user_name\

For installation help

Caiman should install easily on Linux, Mac, and Windows. If you run into problems, we have a dedicated installation page: the details there should help you troubleshoot. If you don't find what you need there, please create an issue at GitHub, and we will help you get it sorted out.

Demo notebooks

Caiman provides demo notebooks to showcase each of our main features, from motion correction to online CNMF. We recommend starting with the CNMF notebook (demo_pipeline.ipynb), which contains more explanation and details than the other notebooks: it covers many concepts that will be used without explanation in the other notebooks. The CNMFE notebook (demo_pipeline_cnmfE.ipynb), is also more detailed. Once you've gotten things set up and worked through those "anchor" notebooks, the best way to get started is to work through the demo notebook that most closely matches your use case; you should be able to adapt it for your particular needs.

The main use cases and notebooks are listed in the following table:

Use caseDemo notebookPaper
CNMF for 2p or low-noise 1p datademo_pipeline.ipynbPnevmatikakis et al., 2016
CNMFE for 1p datademo_pipeline_cnmfE.ipynbZhou et al., 2018
Volpy for voltage datademo_pipeline_voltage_imaging.ipynbCai et al., 2021
Volumetric (3D) CNMFdemo_caiman_cnmf_3D.ipynbMentioned in Giovannucci et al., 2019
CNMF for dendritesdemo_dendritic.ipynbPnevmatikakis et al., 2016
Online CNMF (OnACID)demo_OnACID_mesoscope.ipynbGiovannucci et al., 2017
Online volumetric CNMFdemo_online_3D.ipynbDeveloped by Johannes Friedrich
Online CNMFE (OnACID-E)demo_realtime_cnmfE.ipynbFriedrich et al. 2020
Motion correctiondemo_motion_correction.ipynbPnevmatikakis et al., 2017
Seed CNMF with external masksdemo_seeded_CNMF.ipynbMentioned in Giovannucci et al., 2019
Register cells across sessionsdemo_multisession_registration.ipynbPnevmatikakis et al., 2016

A comprehensive list of references, where you can find detailed discussion of the methods and their development, can be found here.

CLI demos

Caiman also provides commandline demos, similar to the notebooks, demonstrating how to work with the codebase outside of Jupyter. They take their configuration primarily from json files (which you will want to modify to work with your data and its specifics) and should be reasonably easy to modify if they don't already do what you want them to do (in particular, saving things; a standard output format for Caiman is something intended for future releases). To run them, activate your environment, and find the demos in demos/general under your caiman data directory; you can run them like you would any other python application, or edit them with your code editor. Each demo comes with a json configuration file that you can customise. There is a README in the demos directory that covers some of this.

How to get help

How to contribute

Caiman is an open-source project and improves because of contributions from users all over the world. If there is something about Caiman that you would like to work on, then please reach out. We are always looking for more contributors, so please come read the contributors page for more details about how.

Videos

There are multiple online videos by Andrea Giovannucci from past Caiman workshops/events that are an excellent start for newcomers.

The following talk provides a good high-level introduction to Caiman:
https://www.youtube.com/watch?v=5APzPRbzUIA

The following talks are more in depth:

Related repositories

There are many repositories that use Caiman, or help make using Caiman easier.

If you have questions about these related packages please reach out to their maintainers directly. If you would like your software to be in this list, please contact one of the developers or open an issue.

Citing Caiman and related papers

If you publish a paper that relied on Caiman, we kindly ask that you cite Giovannucci et al., 2019:

@article{giovannucci2019caiman,
  title={CaImAn: An open source tool for scalable Calcium Imaging data Analysis},
  author={Giovannucci, Andrea and Friedrich, Johannes and Gunn, Pat and Kalfon, Jeremie and Brown, Brandon L and Koay, Sue Ann and Taxidis, Jiannis and Najafi, Farzaneh and Gauthier, Jeffrey L and Zhou, Pengcheng and Khakh, Baljit S and Tank, David W and Chklovskii, Dmitri B and Pnevmatikakis, Eftychios A},
  journal={eLife},
  volume={8},
  pages={e38173},
  year={2019},
  publisher={eLife Sciences Publications Limited}
}

If possible, we'd also ask that you cite the papers where the original algorithms you use (such as CNMF) were developed. A list of such references can be found here.

Main developers

A complete list of contributors can be found here. Currently Pat Gunn, Johannes Friedrich, and Eric Thomson are the most active contributors.

Acknowledgements

Special thanks to the following people for letting us use their datasets in demo files:

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.