2P Calcium Imaging Pipeline

A full end-to-end pipeline for processing two-photon calcium imaging data using CaImAn. The pipeline handles motion correction, source extraction via CNMF, quality control, and output of spatial/temporal components.

---

Features

• Rigid and piecewise-rigid motion correction (NoRMCorre)
• Constrained Non-negative Matrix Factorization (CNMF) source extraction
• Support for both 1-photon and 2-photon data
• Automated component quality control (SNR, spatial correlation, CNN classifier)
• Component visualization (spatial footprints + temporal traces)
• Structured output directory with videos, matrices, logs, and plots
• Full logging with timestamped log files

---

Requirements

• Python ≥ 3.8
• CaImAn (and its dependencies)
• NumPy
• Matplotlib

Installation

The quickest route is the bundled conda environment file:

conda env create -f environment.yml
conda activate caiman-snb

Or install CaImAn yourself and add the remaining packages with pip:

conda create -n caiman -c conda-forge caiman
conda activate caiman
pip install -r requirements.txt

CaImAn is installed through conda rather than pip because it pulls in compiled dependencies that pip does not always resolve cleanly. For detailed installation instructions, see the CaImAn documentation.

---

Usage

python main.py --input /path/to/movie.tif --outdir /path/to/output

Minimal example

python main.py \
  --input recording.tif \
  --outdir results/

Full example with custom parameters

python main.py \
  --input recording.tif \
  --outdir results/ \
  --fr 30 \
  --decay_time 0.4 \
  --K 30 \
  --gSig 4 4 \
  --min_SNR 2.5 \
  --rval_thr 0.85 \
  --cnn_thr 0.99 \
  --n_components 10 \
  --cleanup

---

Arguments

Required

Argument	Description
--input	Path to input TIFF file
--outdir	Path to output directory (created if it does not exist)

Acquisition

Argument	Default	Description
--fr	30.0	Imaging frame rate (Hz)
--decay_time	0.4	Calcium indicator decay time (seconds)
--is_1p	False	Flag for 1-photon data (enables spatial high-pass filter)

Motion Correction

Argument	Default	Description
--max_shifts	12 12	Maximum allowed shifts in x and y (pixels)
--strides	48 48	Patch strides for piecewise-rigid correction
--overlaps	24 24	Patch overlaps for piecewise-rigid correction

CNMF Source Extraction

Argument	Default	Description
--gSig	4 4	Expected half-size of neurons (pixels)
--K	20	Maximum number of components per patch
--min_SNR	2.0	Minimum SNR for component acceptance
--rval_thr	0.85	Minimum spatial correlation threshold
--cnn_thr	0.99	CNN classifier threshold (upper bound)
--cnn_lowest	0.1	CNN classifier threshold (lower bound)

Optional

Argument	Default	Description
--n_components	5	Number of components to include in the summary plot
--cleanup	False	Remove temporary files after pipeline completes

---

Output Structure

outdir/
├── orig.tif                    # Copy of the raw input file
├── videos/
│   ├── orig.mp4                # Downsampled raw movie
│   ├── orig_mc.mp4             # Downsampled motion-corrected movie
│   ├── AC_before_qc.mp4        # Reconstructed activity movie (pre-QC)
│   └── AC.mp4                  # Reconstructed activity movie (post-refit)
├── matrices/
│   ├── A.npy                   # Spatial footprints (pixels × components)
│   ├── C.npy                   # Temporal traces (components × frames)
│   ├── b.npy                   # Background spatial component
│   └── f.npy                   # Background temporal component
├── plots/
│   └── components.pdf          # Spatial footprints + temporal traces figure
└── logs/
    └── pipeline_YYYYMMDD_HHMMSS.log

---

Output Details

Matrices

File	Shape	Description
A.npy	(pixels, n_components)	Sparse spatial footprints
C.npy	(n_components, T)	Denoised fluorescence traces
b.npy	(pixels, nb)	Background spatial components
f.npy	(nb, T)	Background temporal components

Component Plot

The summary figure (plots/components.pdf) shows, for each of the top --n_components components:

• Left: Spatial footprint rendered on the FOV
• Right: Normalized temporal activity trace

---

Notes

• The pipeline uses piecewise-rigid motion correction (pw_rigid) by default, which is more robust to non-uniform motion than rigid correction.
• For 1-photon data (--is_1p), a spatial high-pass filter (gSig_filt = (3, 3)) is applied before motion correction to suppress low-frequency background.
• The refit step re-estimates components on the motion-corrected data for improved accuracy.
• Temporary memory-mapped files (.mmap) are written to the output directory and can be deleted with --cleanup.

---

Citation

If you use this pipeline in your work, please cite the CaImAn paper:

Giovannucci et al. (2019). CaImAn: An open source tool for scalable Calcium Imaging data Analysis. eLife, 8, e38173. https://doi.org/10.7554/eLife.38173

---

License

This pipeline script is released under the MIT License. CaImAn itself is licensed separately under the GNU GPL v2.