lbm-caiman-python 1.1.0

Light Beads Microscopy 2P Calcium Imaging Pipeline.

LBM-CaImAn-Python

Installation | Notebooks

Python implementation of the Light Beads Microscopy (LBM) computational pipeline.

For the MATLAB implementation, see here

Pipeline Steps:

1. Image Assembly
   • Extract raw tiffs to planar timeseries
2. Motion Correction
   • Template creation
   • Piecewise-rigid or non-rigid registration
3. Segmentation
   • Iterative CNMF segmentation
   • Deconvolution
   • Refinement
4. Collation
   • Lateral offset correction (between z-planes)
   • Collate images and metadata into a single volume

Requirements

• caiman
• mesmerize-core
• scanreader
• numpy
• scipy
• fastplotlib

:exclamation: Note: This package makes heavy use of Fastplotlib for visualizations.

Fastplotlib runs on Jupyter Lab, but is not guarenteed to work with Jupyter Notebook or Visual Studio Code notebook environments.

Installation

This project is tested on Linux and Windows 10 using Python 3.9 and Python 3.10.

Environment setup is tested using virtualenv and miniforge.

We suggest using python virtual environments for the best results.

(Option 1). Python Virtual Environments

Ensure you have a system-wide Python installation.

This project and it's dependencies are tested using Python 3.9 and Python 3.10.

Note: Make sure you deactivate conda environments before proceeding (conda deactivate).

Verify Python and pip installations:

• Linux/macOS:

python --version

pip --version

• Windows:

py --version

py - m pip --version 

:exclamation: Depending on how Python was installed, you may need to use python3 or python3.x and pip3 or pip3.x instead of python and pip.

You should see a Python version output like 3.10.x and a corresponding pip version.

If Python is not installed, or an unsupported version is installed (i.e. 3.7),

download and install python.org or refer to this installation guide.

You will also need git:

git --version

Create a virtual environment

This is normally in a directory dedicated to virtual environments, but can be anywhere you wish:

python -m venv ~/venv/lbm_caiman_python

Activate the virtual environment:

• Linux/macOS:

  source ~/venv/lbm_caiman_python/bin/activate
  

• Windows:

  source ~/venv/lbm_caiman_python/Scripts/activate
  

Upgrade core tools in the virtual environment:

pip install --upgrade setuptools wheel pip

Clone and install CaImAn

Create a directory to store the cloned repositories.

Again, this can be anywhere you wish:

cd ~
mkdir repos
cd repos

Use git to clone CaImAn:

git clone https://github.com/flatironinstitute/CaImAn.git

Install CaImAn:

1. CaImAn:

   cd CaImAn
   pip install -r requirements.txt
   pip install .
   

   :exclamation: Note: If you encounter errors during the installation of CaImAn, you may need to install Microsoft Visual C++ Build Tools. You can download them from here.

2. Other dependencies:

   pip install mesmerize-core
   pip install lbm_caiman_python
   pip install git+https://github.com/atlab/scanreader.git
   

Run ipython to make sure everyting works

import lbm_caiman_python as lcp
import mesmerize_core as mc
import scanreader as sr

scan = sr.read_scan('path/to/data/*.tif', join_contiguous=True)

virtualenv Troubleshooting

Error During pip install . (CaImAn) on Linux

If you encounter errors during the installation of CaImAn, install the necessary development tools:

sudo apt-get install python3-dev

---

(Option 2). Conda

Miniforge is the supported conda distribution. Anaconda and Miniconda require extra steps and is not covered in this guide.

Note: Sometimes conda or mamba will get stuck at a step, such as creating an environment or installing a package.

Pressing Enter on your keyboard can sometimes help it continue when it pauses.

1. Install mamba into your base environment:

:exclamation: This step may take 10 minutes and display several messages like "Solving environment: failed with..." but it should eventually install mamba.

conda activate base 
conda install -c conda-forge mamba

2. Create a new environment and install mesmerize-core

• Here, we use the -n flag to name the environment lbm , but you can name it whatever you'd like.
• This step will install Python, mesmerize-core, CaImAn, and all required dependencies for those packages.

conda create -n lbm -c conda-forge mesmerize-core

If you already have CaImAn installed:

conda install -n name-of-env-with-caiman mesmerize-core

Activate the environment and install caimanmanager:

• if you used a name other than lbm, be sure to match the name you use here.

conda activate lbm
caimanmanager install

3. Install LBM-CaImAn-Python from pip:

pip install lbm_caiman_python

4. Install scanreader:

pip install git+https://github.com/atlab/scanreader.git

5. (Optional) Install mesmerize-viz:

Several notebooks make use of mesmerize-viz for visualizing registration/segmentation results.

pip install mesmerize-viz

:exclamation: Harware requirements The large CNMF visualizations with contours etc. usually require either a dedicated GPU or integrated GPU with access to at least 1GB of VRAM.

https://www.youtube.com/watch?v=GWvaEeqA1hw

For Developers

To get the newest version of this package:

git clone https://github.com/MillerBrainObservatory/LBM-CaImAn-Python.git

cd LBM-CaImAn-Python

pip install ".[docs]"

Troubleshooting

Conda Slow / Stalling

if conda is behaving slow, clean the conda installation and update conda-forge:

conda clean -a

conda update -c conda-forge --all

Don't forget to press enter a few times if conda is taking a long time.

Recommended Conda Distribution

The recommended conda installer is miniforge.

This is a community-driven conda/mamba installer with pre-configured packages specific to conda-forge.

This helps avoid conda-channel conflicts and avoids any issues with the Anaconda TOS.

You can install the installer from a unix command line:

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"

bash Miniforge3-$(uname)-$(uname -m).sh

Or download the installer for your operating system here.

Graphics Driver Issues

If you are attempting to use fastplotlib and receive errors about graphics drivers, see the fastplotlib driver documentation.