Caiman

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.

Installation

There are two primary ways to install Caiman.

Route A

The easiest route is to install the miniforge distribution of Anaconda, and use that to install the rest using prebuilt packages. Most users should take this path.

Route B

The alternative route is to make sure you have a working compiler, create a python virtualenv, grab the caiman sources, and use pip to populate the virtualenv and build Caiman. This route is not as tested and is not presently documented; it is a standard pip-based install (although it will invoke your C++ compiler to build some components).

Quick start (Route A)

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. The miniforge distribution of conda is preferred; it will require fewer steps and likely encounter fewer issues. If you are using a different distro of conda, you will likely need to add -c conda-forge to the commands you use to make your environment.

Windows users will temporarily need to use an alternative install path.

Step 1: Install Caiman

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

mamba create -n caiman caiman # build a caiman environment
conda activate caiman  # activate the 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 conda 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 lab

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

<your home> in the first line is your home directory, its location depdnding on your OS/computer. On Linux/Mac it is ~ while on Windows it will be something like C:\Users\your_user_name\

Quick Start (Route B)

This differs from the quick start above in two ways:

For the first step only, go to this doc and run through the parts of section 1B relevant to your operating system. After that, steps 2 and onward are the same
You will probably want to manually set some environment variables before any use of caiman; see here for a Linux/OSX example, or here for a Windows example. Either make a note of this or modify your dotfiles/configuration to do it for you.

Route B alternative for Windows users

First, you will need to install Visual Studio 2019 or possibly a later version, with the C++ compiler and commandline utilities. Then you will clone this repo to your windows system, and enter the checkout directory.

Next, you will build and activate a mostly-empty conda environment:

mamba create -n caiman python=3.11 pip vs2019_win-64
conda activate caiman

Finally, you will use pip to install Caiman's prerequisites and Caiman itself: pip install .

This step may fail if the compiler is not correctly installed and is the most fragile part of this install route; reach out if you encounter issues.

After this, assuming you succeed, leave the source directory. Later steps will not function correctly when run in the source/checkout directory.

For installation help

Caiman should install easily on Linux, Mac, and Windows. If you run into problems, we have a dedicated installation page. If you don't find what you need there, create an issue on GitHub.

Upgrading

If you upgrade caiman, you should not generally need to clear out and recreate your caiman_data directory between minor releases (e.g. 1.2.3 to 1.2.4); we try to avoid API changes that might break demos between those releases, although you will miss out on any improvements to notebooks (it is normal for people to change notebooks on their own without renaming them).

If you want to get the latest changes, either remove or rename your caiman_data directory and create a new one with caimanmanager install as above. Afterwards you can move data and/or modified notebooks back in (still possibly losing improvements we've made to notebooks along the way).

If you upgrade caiman between major versions (e.g. 1.0.15 to 1.1.0), APIs are more likely to have changed and you may need to make more substantial changes to integrate your changes into the new versions. The process is the same.

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 case | Demo notebook | Paper | |:-------- |:------------- | --------------------- | | CNMF for 2p or low-noise 1p data | demo_pipeline.ipynb | Pnevmatikakis et al., 2016 | | CNMFE for 1p data | demo_pipeline_cnmfE.ipynb | Zhou et al., 2018 | | Volpy for voltage data | demo_pipeline_voltage_imaging.ipynb | Cai et al., 2021 | | Volumetric (3D) CNMF | demo_caiman_cnmf_3D.ipynb | Mentioned in Giovannucci et al., 2019 | | CNMF for dendrites | demo_dendritic.ipynb | Pnevmatikakis et al., 2016 | | Online CNMF (OnACID) | demo_OnACID_mesoscope.ipynb |Giovannucci et al., 2017 | | Online volumetric CNMF | demo_online_3D.ipynb | Developed by Johannes Friedrich | | Online CNMFE (OnACID-E) | demo_realtime_cnmfE.ipynb |Friedrich et al. 2020 | | Motion correction | demo_motion_correction.ipynb | Pnevmatikakis et al., 2017 | | Seed CNMF with external masks | demo_seeded_CNMF.ipynb | Mentioned in Giovannucci et al., 2019 | | Register cells across sessions | demo_multisession_registration.ipynb | Pnevmatikakis 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

Online documentation contains a lot of general information about Caiman, the parameters, how to interpret its outputs, and more.
GitHub Discussions is our preferred venue for users to ask for help.
The Gitter forum is our old forum: we sometimes

CaImAn

Install / Use

README