Command Line Interface¶

The SPIMquant command-line interface is built on Snakemake and follows the BIDS App specification.

Complete CLI Reference

For a complete auto-generated reference of all command-line options, see the CLI Reference page.

Basic Usage¶

pixi run spimquant <bids_dir> <output_dir> <analysis_level> [options]

Required Arguments¶

bids_dir: Path to BIDS dataset (can be local path or S3/GCS URL)
output_dir: Path to output directory
analysis_level: Either participant or group

Analysis Levels¶

Participant Level¶

Process individual subjects:

pixi run spimquant /path/to/bids /path/to/output participant --cores all

This performs:

Template registration
Segmentation
Atlas-based quantification
Quality control outputs

Group Level¶

Perform group statistical analysis:

pixi run spimquant /path/to/bids /path/to/output group \
  --group-stats-model "metric ~ C(treatment) + age" \
  --group-stats-pairwise treatment \
  --cores all

Requires completed participant-level analysis.

Common Options¶

BIDS Filtering¶

Filter specific subjects or sessions:

# Process specific subjects
pixi run spimquant ... participant --filter_subjects 01 02 03

# Filter by SPIM data type
pixi run spimquant ... participant --filter-spim extension='ome.zarr.zip'

Parallelization¶

Control computational resources:

# Use all available cores
pixi run spimquant ... --cores all

# Use specific number of cores
pixi run spimquant ... --cores 8

# Limit concurrent jobs
pixi run spimquant ... --jobs 4

Workflow Control¶

# Dry run (don't execute, just plan)
pixi run spimquant ... -n

# Force re-run all steps
pixi run spimquant ... --forceall

# Re-run specific rule
pixi run spimquant ... --forcerun register_to_template

# Run until specific rule
pixi run spimquant ... --until convert_to_nifti

Output Options¶

# Generate HTML report
pixi run spimquant ... --report

# Keep temporary files
pixi run spimquant ... --notemp

# Quiet mode
pixi run spimquant ... --quiet

Advanced Options¶

Template Selection¶

# Use specific template
pixi run spimquant ... --template gubra

# Available templates: ABAv3, gubra, MBMv3, turone, MouseIn

Registration Options¶

# Specify registration stain
pixi run spimquant ... --registration_stain YOPRO

Segmentation Options¶

# Choose segmentation method
pixi run spimquant ... --segmentation_method threshold

Cloud Storage¶

# Read from S3
pixi run spimquant s3://bucket/bids /local/output participant --cores all

# Read from GCS
pixi run spimquant gs://bucket/bids /local/output participant --cores all

Group Analysis Options¶

When using analysis_level group:

# Basic pairwise comparison between all levels of a factor
pixi run spimquant /bids /output group \
  --group-stats-model "metric ~ C(treatment) + age" \
  --group-stats-pairwise treatment \
  --cores all

# Restrict the inference cohort with --group-stats-where
# Only subjects with treatment pbs or lecanemab will be included in the model
# and contrasts; subjects with treatment control or n/a are excluded entirely.
pixi run spimquant /bids /output group \
  --group-stats-model "metric ~ C(treatment) + age" \
  --group-stats-pairwise treatment \
  --group-stats-where "treatment in ['pbs', 'lecanemab']" \
  --cores all

# Stratified pairwise contrasts (within each genotype)
pixi run spimquant /bids /output group \
  --group-stats-model "metric ~ C(treatment) * C(genotype) + age" \
  --group-stats-pairwise treatment \
  --group-stats-within genotype \
  --cores all

The --group-stats-where option accepts any pandas query expression. It is applied at both planning time (to enumerate contrasts) and at runtime (before model fitting), so the inference cohort is consistent throughout.

Generates (under <output_dir>/group/<label>/):

*_allsubjects.tsv: Merged per-subject ROI table with participant metadata (always produced)
*_contrast-<label>_groupstats.tsv: Statistical results per pairwise contrast
*_contrast-<label>_groupstats.png: Heatmap visualizations
*_contrast-<label>_groupstats.nii: 3D volumetric stat maps

Configuration File¶

SPIMquant can also be configured via YAML files. See Configuration Guide for details.

Environment Variables¶

# Set Dask configuration
export DASK_CONFIG=/path/to/dask.yaml

# AWS credentials for S3
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

Snakemake Options¶

SPIMquant inherits all Snakemake CLI options. Key options include:

# Visualization
--dag                 # Output DAG visualization
--rulegraph          # Output rule graph

# Debugging
--debug              # Enable debug mode
--printshellcmds     # Print shell commands

# Resource management  
--resources mem_mb=64000  # Set memory limit
--latency-wait 60    # Wait time for file system

Examples¶

Basic Processing¶

# Process all subjects
pixi run spimquant ./bids ./output participant --cores all

Advanced Workflow¶

# Process with custom settings
pixi run spimquant ./bids ./output participant \
  --filter_subjects 01 02 \
  --template gubra \
  --cores 16 \
  --report

Cluster Execution¶

# Submit to SLURM cluster
pixi run spimquant ./bids ./output participant \
  --profile slurm \
  --jobs 100

Getting Help¶

# Show help message
pixi run spimquant --help

# Show Snakemake help
pixi run spimquant --help-snakemake

For more detailed information, see: