Lizard Wizard

Calcium Image Processing Nextflow pipeline for the Arc Institute.

The Lizard Wizard pipeline helps researchers analyze subcellular Ca²⁺ signals captured using fluorescent Ca²⁺ indicators. This pipeline automates the detection and analysis of calcium signals, simplifying complex image processing tasks and providing detailed metrics for understanding neural activity.

Table of Contents

• Lizard Wizard
  • Overview
  • Features
• Installation
  • Conda & mamba install
  • Nextflow install
  • Pipeline install
    • Add ssh key to GitHub
    • Clone the Repository
    • Pipeline conda environments
• Usage
  • Quick Start
  • Example Run
  • Parameters
  • Tutorials
  • Secrets
• Resources
  • Output Files
  • License
  • Acknowledgments

Overview

Calcium imaging is a powerful technique for monitoring cellular activity, but processing and analyzing this data involves multiple complex steps. Lizard Wizard automates this entire process for biologists, from input image preprocessing to detailed neuron-level analysis, integrating:

• CaImAn for calcium event detection
• Cellpose for cell segmentation
• Wizards-Staff for pairwise correlations, synchronicity analysis, and more

This integrated approach makes calcium imaging analysis more accessible, reproducible, and efficient.

Features

• Comprehensive Pipeline: Processes raw calcium imaging data from multiple microscope types (Molecular Devices, Zeiss) through a complete analysis workflow
• Automated Masking: Uses Cellpose for precise identification of regions of interest (ROIs)
• Calcium Event Analysis: Leverages CaImAn for automated extraction of neuronal activity
• Detailed Metrics Calculation: performed via automated Wizard's Staff Integration.

Installation

Conda & mamba install

mamba is needed to run the pipeline. It is a faster version of conda. mamba can be installed via conda.

To install both conda and mamba, see the conda/mamba Notion docs.

Nextflow install

It is easiest to install Nextflow using mamba:

mamba install -n nextflow_env -c bioconda nextflow

Make sure to activate the environment before running the pipeline:

mamba activate nextflow_env

Pipeline install

Clone the Repository

git clone [email protected]:ArcInstitute/Lizard-Wizard.git \
  && cd Lizard-Wizard

Pipeline conda environments

The first time you run the pipeline, Nextflow will automatically create all necessary conda environments. This process may take some time but only happens once.

Note: it can take a while to create the environments, even with mamba.

Usage

Quick Start

nextflow run main.nf \
  -profile conda,slurm \
  -work-dir /scratch/$(id -gn)/$(whoami)/nextflow-work/lizard-wizard \
  --input_dir /path/to/your/images/ \
  --output_dir /path/to/output/location/ \
  --test_image_count 2 \
  -N [email protected]

Example Run

We recommend a two-step approach:

1. Spot Check: Run the pipeline on a few images first to verify parameters. This will run Lizard Wizard utilizing preset parameters, we recommend reading through the general Tutorial for detailed information on how to adjust parameters to your dataset during this step.

   nextflow run main.nf \
     -profile conda,slurm \
     -work-dir /scratch/$(id -gn)/$(whoami)/nextflow-work/lizard-wizard \
     --input_dir /path/to/image/files/ \
     --output_dir /path/to/output/location/ \
     --test_image_count 3 \
     -N [email protected]

   Update -work-dir as needed for your file system

2. Full Run: Process the entire dataset using the same output directory

   nextflow run main.nf \
     -profile conda,slurm \
     -work-dir /scratch/$(id -gn)/$(whoami)/nextflow-work/lizard-wizard \
     --input_dir /path/to/image/files/ \
     --output_dir /path/to/output/location/ \
     -N [email protected] \
     -resume

   Update -work-dir as needed for your file system

Parameters

The pipeline has many configurable parameters that can be set via command line or config files. See either nextflow.config or the general Tutorial for detailed information about setting these parameters for your specific data type.

Key parameters include:

• --input_dir: Path to input images
• --output_dir: Where to save results
• --file_type: Set to "moldev" or "zeiss" depending on your microscope
• --use_2d: Set to true for 2D images instead of 3D (default: false)
• --test_image_count: Number of random images to process for testing
• --test_image_names: Specify particular images to process (comma-separated)

Tutorials

For detailed guidance on how to use Lizard Wizard and the accompanying Wizards Staff with your data, see:

• Lizard Wizard Tutorial - How to configure parameters for Lizard Wizard and account for different data types
• Output Files Guide - Understanding the outputs of the Lizard Wizard pipeline
• Troubleshooting Guide - Common issues and solutions

Secrets

[Optional] The pipeline uses gpt-4o(-mini) to summarize the log files. This optional feature requires an OPENAI_API_KEY to be set as a Nextflow secret. To set the secret (assuming that OPENAI_API_KEY is set in the environment):

nextflow secrets set OPENAI_API_KEY $OPENAI_API_KEY

Notes:

• If you do not set OPENAI_API_KEY, then the log summaries will be blank.

Output Files

The pipeline produces a structured output directory containing:

• Processed images
• Neuronal activity data
• Metrics tables
• Visualization plots
• Log summaries

See the Output Files Guide for detailed information.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• CaImAn for calcium imaging analysis
• Cellpose for cell segmentation
• Nextflow for workflow management
• Arc Institute for supporting this research