Suite2p

Fast, accurate, and automated pipeline for processing two-photon calcium imaging data

Neuroscience-Specific Analysis Tools Advanced Specialized Tool Explore Provisional Teaching
Download Documentation

Our View

Explore Provisional Teaching

Suite2p provides a complete, automated pipeline for calcium imaging analysis from raw TIFF files to extracted neural activity traces. Its GUI makes it accessible for beginners while its Python API enables advanced customization and batch processing.

Provisional positions are editorial proposals awaiting group review.

Teaching — Recorded in topic offerings; consult the dated event links for availability.

1 topics with recorded teaching · 2 past offerings · 1 upcoming offerings

Related themes: Neural Data Analysis

Related topics: Calcium Imaging Analysis

Common use cases

  • Automated ROI detection in two-photon data
  • Motion correction of calcium imaging recordings
  • Cell segmentation and neuropil correction
  • Spike inference from calcium traces

Getting started

Suite2p is a comprehensive pipeline for processing two-photon calcium imaging data. It handles the entire workflow from raw TIFF files to extracted neural traces, including motion correction, ROI detection, signal extraction, and spike inference.

Why Suite2p?

  • Fully Automated: Complete pipeline with minimal manual intervention
  • Fast: Optimized for large datasets
  • Accurate: State-of-the-art algorithms for cell detection
  • User-Friendly GUI: Easy to use for non-programmers
  • Python API: Scriptable for batch processing
  • Well-Maintained: Active development and community support

Key Features

Motion Correction

  • Rigid and non-rigid registration
  • Phase correlation-based alignment
  • Fast processing of large datasets

ROI Detection

  • Automated cell detection
  • Neuropil masks for background correction
  • Handles overlapping cells

Signal Extraction

  • Fluorescence trace extraction
  • Neuropil correction
  • ΔF/F calculation

Spike Inference

  • Deconvolution to infer spikes
  • Multiple algorithms available
  • Temporal dynamics preserved

Using the GUI

Starting Suite2p

# After installation
python -m suite2p

# Or from Python
import suite2p
suite2p.run_gui()

Basic Workflow

  1. Set Data Path: Point to folder with TIFF files
  2. Configure Settings: Choose parameters (defaults work well)
  3. Run Pipeline: Click “Run Suite2p”
  4. View Results: ROIs, traces, and quality metrics
  5. Manual Curation: Refine ROI selection if needed

Key Parameters

  • nplanes: Number of imaging planes
  • nchannels: Number of channels (typically 1 or 2)
  • tau: GCaMP decay timescale (seconds)
  • threshold_scaling: ROI detection sensitivity
  • max_overlap: Maximum allowed overlap between ROIs

Using the Python API

Basic Processing

import suite2p
from pathlib import Path

# Set up paths
data_path = Path('data/calcium_imaging')
output_path = Path('results/suite2p')

# Configure options
ops = suite2p.default_ops()
ops['data_path'] = [str(data_path)]
ops['save_path0'] = str(output_path)
ops['nplanes'] = 1
ops['nchannels'] = 1
ops['tau'] = 1.0  # GCaMP6f

# Run pipeline
opsEnd = suite2p.run_s2p(ops=ops)

Load Results

import numpy as np
from pathlib import Path

# Load Suite2p output
suite2p_dir = Path('results/suite2p/plane0')

# Load fluorescence traces
F = np.load(suite2p_dir / 'F.npy')  # Raw fluorescence
Fneu = np.load(suite2p_dir / 'Fneu.npy')  # Neuropil
spks = np.load(suite2p_dir / 'spks.npy')  # Inferred spikes

# Load ROI information
stat = np.load(suite2p_dir / 'stat.npy', allow_pickle=True)
iscell = np.load(suite2p_dir / 'iscell.npy')

# Filter for cells only
cell_mask = iscell[:, 0] == 1
F_cells = F[cell_mask]
spks_cells = spks[cell_mask]

print(f"Detected {cell_mask.sum()} cells")

Output Files

Key Outputs

  • F.npy: Raw fluorescence traces (n_rois × n_frames)
  • Fneu.npy: Neuropil fluorescence
  • spks.npy: Deconvolved spike traces
  • stat.npy: ROI statistics (coordinates, size, etc.)
  • iscell.npy: Cell classification (cell vs artifact)
  • ops.npy: Processing parameters used

Analyzing Results

Plot ROI Locations

import matplotlib.pyplot as plt
import numpy as np

# Load mean image and stats
ops = np.load(suite2p_dir / 'ops.npy', allow_pickle=True).item()
stat = np.load(suite2p_dir / 'stat.npy', allow_pickle=True)
iscell = np.load(suite2p_dir / 'iscell.npy')

# Get mean image
mean_img = ops['meanImg']

# Plot
fig, ax = plt.subplots(figsize=(10, 10))
ax.imshow(mean_img, cmap='gray')

# Overlay ROIs
for i, (s, is_cell) in enumerate(zip(stat, iscell)):
    if is_cell[0]:  # Only plot cells
        ypix = s['ypix']
        xpix = s['xpix']
        ax.scatter(xpix, ypix, s=0.5, alpha=0.3)

ax.set_title(f'{iscell[:, 0].sum():.0f} Cells Detected')
plt.show()

Plot Traces

import matplotlib.pyplot as plt

# Load data
F = np.load(suite2p_dir / 'F.npy')
Fneu = np.load(suite2p_dir / 'Fneu.npy')
iscell = np.load(suite2p_dir / 'iscell.npy')

# Neuropil-corrected fluorescence
neuropil_coef = 0.7
F_corrected = F - neuropil_coef * Fneu

# Calculate ΔF/F
F0 = np.percentile(F_corrected, 10, axis=1, keepdims=True)
dFF = (F_corrected - F0) / F0

# Plot first 5 cells
cell_indices = np.where(iscell[:, 0] == 1)[0][:5]

fig, axes = plt.subplots(len(cell_indices), 1, figsize=(15, 10), sharex=True)
for ax, idx in zip(axes, cell_indices):
    ax.plot(dFF[idx], linewidth=0.5)
    ax.set_ylabel(f'Cell {idx}')
    ax.set_ylim([-0.5, 3])

axes[-1].set_xlabel('Frame')
plt.tight_layout()
plt.show()

Plot Spike Inference

import matplotlib.pyplot as plt

# Load spikes
spks = np.load(suite2p_dir / 'spks.npy')
iscell = np.load(suite2p_dir / 'iscell.npy')

# Get first cell
cell_idx = np.where(iscell[:, 0] == 1)[0][0]

# Plot fluorescence and inferred spikes
fig, axes = plt.subplots(2, 1, figsize=(15, 6), sharex=True)

# ΔF/F
axes[0].plot(dFF[cell_idx], 'g', linewidth=1)
axes[0].set_ylabel('ΔF/F')
axes[0].set_title(f'Cell {cell_idx}')

# Inferred spikes
axes[1].plot(spks[cell_idx], 'k', linewidth=1)
axes[1].set_ylabel('Spike Rate (AU)')
axes[1].set_xlabel('Frame')

plt.tight_layout()
plt.show()

Batch Processing

Process Multiple Sessions

import suite2p
from pathlib import Path

# List of data directories
data_dirs = [
    'data/subject01/session01',
    'data/subject01/session02',
    'data/subject02/session01',
]

# Process each session
for data_dir in data_dirs:
    print(f"Processing {data_dir}...")

    ops = suite2p.default_ops()
    ops['data_path'] = [data_dir]
    ops['save_path0'] = f'results/{Path(data_dir).name}'

    # Run
    suite2p.run_s2p(ops=ops)

Advanced Configuration

Custom Detection Parameters

ops = suite2p.default_ops()

# Motion correction
ops['do_registration'] = 1
ops['nimg_init'] = 300
ops['maxregshift'] = 0.1  # Max shift as fraction of image

# Cell detection
ops['threshold_scaling'] = 1.0  # Lower = more sensitive
ops['max_overlap'] = 0.75
ops['diameter'] = 12  # Expected cell diameter (pixels)

# Neuropil
ops['allow_overlap'] = False
ops['inner_neuropil_radius'] = 2
ops['min_neuropil_pixels'] = 350

# Spike deconvolution
ops['neucoeff'] = 0.7  # Neuropil coefficient
ops['baseline'] = 'maximin'  # Baseline estimation method

Integration with Other Tools

Export to NWB Format

from suite2p.io.nwb import save_nwb

# Save Suite2p output as NWB
save_nwb(
    save_path='results/suite2p/plane0',
    output_file='data.nwb'
)

Use with CaImAn

# Suite2p and CaImAn can be used in sequence
# 1. Use Suite2p for initial processing
# 2. Export ROIs for CaImAn refinement

Troubleshooting

Common Issues

Too Few Cells Detected:

  • Decrease threshold_scaling
  • Adjust diameter parameter
  • Check meanImg quality

Too Many False Positives:

  • Increase threshold_scaling
  • Increase max_overlap threshold
  • Manual curation in GUI

Motion Correction Fails:

  • Increase nimg_init
  • Reduce maxregshift
  • Check for bleaching artifacts

Performance Tips

  • Use SSD for data storage
  • Allocate sufficient RAM (16GB+ recommended)
  • Process planes in parallel if multiple planes
  • Use GPU version for faster processing
  • Downsample if necessary

Installation

# Basic installation
pip install suite2p

# With GUI support
pip install suite2p[gui]

# With GPU support (CUDA)
pip install suite2p[cuda]

# Or with pixi
pixi add suite2p

Best Practices

  • Start with default parameters
  • Visually inspect mean/max projections before processing
  • Always review automated ROI detection
  • Use manual curation for critical analyses
  • Save processing parameters (ops.npy)
  • Document any parameter changes
  • Compare results across parameter sets
  • Validate with ground truth when available

Resources

Summary

Suite2p provides a complete, automated pipeline for calcium imaging analysis:

  • Fast and accurate ROI detection
  • Handles large datasets efficiently
  • User-friendly GUI + Python API
  • Industry-standard tool for 2P imaging

For most two-photon calcium imaging projects, Suite2p is the recommended starting point.