Synthetic Calcium Imaging

Generate realistic synthetic calcium imaging videos with configurable optical effects.

Overview

This package generates synthetic two-photon microscopy calcium imaging videos. It simulates:

• Neural dynamics (spike generation and calcium fluorescence decay)
• Optical degradation (point spread function blur, photon noise, electronics noise, background)
• Configurable parameters (preset noise levels or custom values)
• Multiple output formats (TIF video, MP4 video, JSON metadata, PNG visualization)

Use it for algorithm testing, training data generation, or pipeline validation.

Installation

pip install synthetic-calcium-imaging

Quick Start

Python API

from synthetic_calcium_imaging import generate_video

# Simple: use default (medium noise)
result = generate_video()

# With preset and overrides
result = generate_video(preset='high_noise', num_cells=100, num_frames=5000)

# Returns dict with video, metadata, and output directory
print(result['output_dir'])  # Where files were saved

Command Line

# Generate with defaults
calcium-imaging generate

# Generate with preset
calcium-imaging generate --preset high_noise

# Generate with custom parameters
calcium-imaging generate --preset high_noise --num-cells 100 --num-frames 5000

# View available presets
calcium-imaging presets

# View default parameters
calcium-imaging info

Available Presets

• clean - No noise
• low_noise - Minimal optical degradation
• medium_noise - Realistic moderate noise (default)
• high_noise - Strong noise and blur
• very_high_noise - Challenging conditions

Output Files

Generated simulations produce:

• video.tif - Lossless video (uint16, LZW compression)
• video.mp4 - Playable video (H.264 codec)
• metadata.json - Parameters, cell positions, calcium traces
• summary.png - 4-panel visualization
• README.txt - Configuration summary

Architecture

Built with Hexagonal Architecture for clean separation of concerns:

• Core - Pure simulation logic (config, simulation, optics)
• Adapters - I/O operations (file output)
• Interfaces - User-facing APIs (Python API, CLI)

Parameters

Simulation

• num_cells - Number of neurons (default: 49)
• num_frames - Video length (default: 1000)
• image_size - Resolution in pixels (default: 256)

Dynamics

• spike_probability - Probability of spike per cell per frame (default: 0.0025)
• decay_tau - Calcium decay time constant in frames (default: 50)
• max_amplitude - Peak fluorescence (default: 1000)
• cell_sigma - Cell soma width in pixels (default: 13)

Optical Effects

• psf_sigma - PSF blur width (default: 1.5)
• psf_size - PSF kernel size (default: 11)
• gaussian_noise_std - Electronics noise (default: 5.0)
• background_amplitude - Background fluorescence (default: 20)
• background_sigma - Background smoothness (default: 80)

Example

from synthetic_calcium_imaging import generate_video
from pathlib import Path

# Generate challenging conditions
result = generate_video(
    preset='very_high_noise',
    num_cells=64,
    num_frames=2000,
    output_dir=Path('./my_simulations')
)

# Access results
video = result['video']  # (2000, 256, 256) array
positions = result['positions']  # Cell positions
calcium = result['calcium_traces']  # Ground truth calcium
config = result['config']  # Configuration used
output_dir = result['output_dir']  # Where files saved

License

MIT License