CAT12 BIDS Pipeline - Complete Summary

What You’ve Built

A complete BIDS App for processing structural MRI data with CAT12 standalone, featuring:

✅ BIDS App Compliance - Follows standard BIDS Apps specifications ✅ Automatic Longitudinal Detection - No manual flags needed ✅ Modular Processing - Opt-in stages for flexibility
✅ Contained Installation - Everything in project directory using UV ✅ No MATLAB License - Uses CAT12 standalone ✅ Server Optimized - No GUI, CUDA support ✅ Comprehensive Documentation - Multiple guides for different needs

Project Structure

bids-cat12-wrapper/
├── README.md                          # Main documentation
├── LICENSE                            # MIT license
├── pyproject.toml                     # Python project config (UV-compatible)
├── requirements.txt                   # Python dependencies
├── Makefile                           # Convenient commands
│
├── Installation
├── scripts/install_cat12_standalone.sh # Main installation script
├── scripts/test_installation.sh        # Verify installation
├── activate_cat12.sh                   # Environment activation (created by installer)
├── .env                                # Environment variables (created by installer)
│
├── Main Application
├── cat12_prepro                       # Preprocessing wrapper (auto activates env)
├── cat12_stats                        # Longitudinal statistics wrapper
├── bids_cat12_processor.py            # Compatibility entrypoint (optional)
│
├── Processing Scripts
├── scripts/
│   ├── preprocessing/                 # Preprocessing implementation (Python)
│   └── stats/                         # Longitudinal stats implementation (Bash/MATLAB)
│
├── Utilities
├── utils/
│   ├── bids_utils.py                 # BIDS validation & session management
│   └── cat12_utils.py                # CAT12 script generation & execution
│
├── Configuration
├── config/
│   └── processing_config.yaml        # Processing configuration
│
├── Documentation
├── docs/
│   ├── QUICK_START.md                # 5-minute getting started guide
│   ├── BIDS_APP_USAGE.md             # Complete usage guide
│   └── CAT12_COMMANDS.md             # CAT12 command reference
│
└── Generated by Installation
    ├── external/                      # CAT12 + MATLAB Runtime
   │   ├── cat12/
   │   └── MCR/
    └── .venv/                         # Python virtual environment

Key Design Decisions

1. BIDS App Convention

Decision: Follow BIDS Apps specification with required positional arguments

./cat12_prepro <bids_dir> <output_dir> <analysis_level> [options]

Benefits:

  • Standardized interface

  • Compatible with workflow managers (Nipype, etc.)

  • Familiar to neuroimaging community

2. Automatic Longitudinal Detection

Decision: Auto-detect longitudinal data based on sessions, no manual flag needed

Logic:

  • Multiple sessions (ses-01, ses-02) → Longitudinal processing

  • Single session or no session → Cross-sectional processing

Benefits:

  • User-friendly (less error-prone)

  • Smart defaults

  • Follows principle of least surprise

3. Opt-In Processing Stages

Decision: All processing stages are opt-in (must be explicitly requested)

Stages:

  • --preproc - Preprocessing/segmentation

  • --smooth-volume - Volume smoothing

  • --smooth-surface - Surface smoothing

  • --qa - Quality assessment

  • --tiv - TIV estimation

  • --roi - ROI extraction

Benefits:

  • User has full control

  • Clear what will be executed

  • Modular and flexible

4. Opt-Out Options

Decision: Some options enabled by default, can be disabled

Options:

  • --no-surface - Skip surface extraction (enabled by default)

  • --no-validate - Skip BIDS validation (enabled by default)

Benefits:

  • Sensible defaults

  • Easy to speed up processing when needed

  • Clear intent with “no-” prefix

5. Contained Installation with UV

Decision: Use UV for Python package management, install everything in project directory

Benefits:

  • Fast, reliable package installation

  • No system-wide modifications

  • Easy cleanup (just delete folder)

  • Reproducible environments

Usage Patterns

Pattern 1: Volume-Only Analysis (Fastest)

./cat12_prepro /data/bids /data/output participant \
    --preproc --no-surface

Use When:

  • Only interested in VBM

  • Need fast processing

  • Limited computational resources

Pattern 2: Complete Structural Analysis

./cat12_prepro /data/bids /data/output participant \
   --preproc --smooth-volume "6" --smooth-surface "12" --qa --tiv

Use When:

  • Comprehensive analysis needed

  • Have sufficient compute time

  • Want both volume and surface measures

Pattern 3: Incremental Processing

# Step 1: Preprocessing only
./cat12_prepro /data/bids /data/output participant --preproc

# Step 2: Add smoothing later
./cat12_prepro /data/bids /data/output participant --smooth-volume "6"

# Step 3: Add QA
./cat12_prepro /data/bids /data/output participant --qa --tiv

Use When:

  • Testing pipeline

  • Incremental workflow

  • Different stages at different times

Command Mapping to CAT12

Preprocessing

User Command:

--preproc

CAT12 Command:

cat_standalone.sh -m $MCR_ROOT \
  -b cat_standalone_segment_enigma.m \
  <T1w_files>

With –no-surface:

cat_standalone.sh -m $MCR_ROOT \
  -b cat_standalone_segment_enigma.m \
  -a "matlabbatch{1}.spm.tools.cat.estwrite.output.surface = 0;" \
  <T1w_files>

Volume Smoothing

User Command:

--smooth-volume "6"

CAT12 Command:

cat_standalone.sh -m $MCR_ROOT \
  -b cat_standalone_smooth.m \
  <mwp1_files> \
  -a1 "[6 6 6]" -a2 "'s6'"

Surface Smoothing

User Command:

--smooth-surface "12"

CAT12 Command:

cat_standalone.sh -m $MCR_ROOT \
  -b cat_standalone_resample.m \
  <lh.thickness_files> \
  -a1 "12" -a2 "1"

Quality Assessment

User Command:

--qa

CAT12 Commands:

# Volume QA
cat_standalone.sh -m $MCR_ROOT \
  -b cat_standalone_get_quality.m \
  <mwp1_files> -a1 "'quality_measures_volumes.csv'" -a2 "1"

# Surface QA
cat_standalone.sh -m $MCR_ROOT \
  -b cat_standalone_get_quality.m \
  <surf_files> -a1 "'quality_measures_surfaces.csv'"

# IQR
cat_standalone.sh -m $MCR_ROOT \
  -b cat_standalone_get_IQR.m \
  <cat_xml_files> -a1 "'IQR.txt'"

TIV Estimation

User Command:

--tiv

CAT12 Command:

cat_standalone.sh -m $MCR_ROOT \
  -b cat_standalone_get_TIV.m \
  <cat_xml_files> -a1 "'TIV.txt'" -a2 "1" -a3 "0"

Implementation Status

✅ Implemented

  • [x] BIDS App command-line interface

  • [x] Automatic longitudinal detection

  • [x] Modular processing stage framework

  • [x] Installation script with UV

  • [x] Environment activation script

  • [x] Test suite

  • [x] Comprehensive documentation

  • [x] Configuration system

  • [x] BIDS validation

  • [x] Preprocessing script generation

  • [x] Quality reporting structure

  • [x] QA metrics parsing and aggregation (basic implementation)

  • [x] TIV extraction from XML (placeholder implementation)

  • [x] ROI extraction implementation (placeholder implementation)

🚧 To Be Implemented

These are placeholders in the code (marked with # TODO:):

  • [ ] Actual CAT12 command execution for each stage

  • [ ] Volume smoothing implementation

  • [ ] Surface smoothing implementation

  • [ ] Parallel processing with joblib

  • [ ] Group-level analysis

  • [ ] Docker/Singularity containers

Next Steps for Development

High Priority

  1. Implement CAT12 Execution

    • Connect CAT12Processor.execute_script() to actual CAT12 calls

    • Test with real data

    • Handle errors and retries

  2. Implement Smoothing Stages

    • smooth_volume_data() → call cat_standalone_smooth.m

    • smooth_surface_data() → call cat_standalone_resample.m

    • Test with different kernel sizes

  3. Implement QA Stages

    • Parse CAT12 XML quality reports

    • Aggregate metrics to CSV

    • Generate summary visualizations

  4. Implement TIV Extraction

    • Parse XML files

    • Extract TIV and global volumes

    • Save to standardized format

Medium Priority

  1. Add Parallel Processing

    • Use joblib for parallel subject processing

    • Implement proper job distribution

    • Handle job failures gracefully

  2. Add ROI Extraction

    • Call cat_standalone_get_ROI_values.m

    • Parse ROI XMLs

    • Generate ROI summary tables

  3. Improve Error Handling

    • Better error messages

    • Automatic retry logic

    • Partial processing recovery

Low Priority

  1. Create Docker Container

    • Dockerfile for complete environment

    • Singularity recipe

    • Docker Hub / Singularity Hub

  2. Add Group-Level Analysis

    • Statistical tests

    • Visualization

    • Report generation

  3. Add Tests

    • Unit tests for utilities

    • Integration tests with sample data

    • CI/CD pipeline

Testing Strategy

Test Data

Create minimal test dataset:

test_data/
├── dataset_description.json
├── sub-01/
│   ├── ses-01/anat/sub-01_ses-01_T1w.nii.gz
│   └── ses-02/anat/sub-01_ses-02_T1w.nii.gz
└── sub-02/
    └── ses-01/anat/sub-02_ses-01_T1w.nii.gz

Test Commands

# Test 1: Volume-only preprocessing
./cat12_prepro test_data test_output participant \
    --preproc --no-surface --participant-label 01

# Test 2: Complete pipeline
./cat12_prepro test_data test_output participant \
   --preproc --smooth-volume "6" --smooth-surface "12" --qa --tiv

# Test 3: Specific session
./cat12_prepro test_data test_output participant \
    --preproc --session-label 01

User Documentation Summary

For Quick Start Users

→ Read docs/QUICK_START.md

  • 5-minute guide

  • Common use cases

  • Troubleshooting

For BIDS App Users

→ Read docs/BIDS_APP_USAGE.md

  • Complete flag reference

  • Workflow examples

  • Integration with other tools

For CAT12 Experts

→ Read docs/CAT12_COMMANDS.md

  • All CAT12 standalone commands

  • Parameter explanations

  • Output file descriptions

For Developers

→ Read source code + this file

  • Implementation details

  • Extension points

  • Contributing guidelines

Success Criteria

This pipeline is successful when:

  1. ✅ User can install with single command

  2. ✅ Clear, BIDS App-style interface

  3. ✅ Automatic longitudinal detection works

  4. ⏳ All processing stages execute correctly

  5. ⏳ Outputs follow BIDS derivatives spec

  6. ⏳ Quality reports are generated

  7. ✅ Comprehensive documentation exists

  8. ⏳ Can process real datasets end-to-end

References

  • BIDS Specification: https://bids-specification.readthedocs.io/

  • BIDS Apps: https://bids-apps.neuroimaging.io/

  • CAT12: http://www.neuro.uni-jena.de/cat12/

  • ENIGMA Protocol: https://neuro-jena.github.io/enigma-cat12/

  • UV Package Manager: https://github.com/astral-sh/uv