iBOTS
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
- Set Data Path: Point to folder with TIFF files
- Configure Settings: Choose parameters (defaults work well)
- Run Pipeline: Click “Run Suite2p”
- View Results: ROIs, traces, and quality metrics
- Manual Curation: Refine ROI selection if needed
Key Parameters
nplanes: Number of imaging planesnchannels: Number of channels (typically 1 or 2)tau: GCaMP decay timescale (seconds)threshold_scaling: ROI detection sensitivitymax_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 fluorescencespks.npy: Deconvolved spike tracesstat.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
diameterparameter - Check
meanImgquality
Too Many False Positives:
- Increase
threshold_scaling - Increase
max_overlapthreshold - 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
- Documentation: https://suite2p.readthedocs.io/
- GitHub: https://github.com/MouseLand/suite2p
- Paper: Pachitariu et al., bioRxiv 2017
- Tutorial Videos: Available on GitHub
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.