QSMxT-Nipoppy

This repository provides Nipoppy pipeline configuration files for running QSMxT - an automated Quantitative Susceptibility Mapping (QSM) processing pipeline.

Overview

Nipoppy is a lightweight framework for standardized organization and processing of neuroimaging datasets. It uses the Boutiques framework to describe and execute processing pipelines.

QSMxT is an end-to-end software toolbox for QSM that automatically reconstructs and processes datasets using sensible defaults.

This repository provides:

• A script to fetch the Boutiques descriptor and generate Nipoppy configuration files
• Example dataset with sample DICOM data
• Documentation for using QSMxT with Nipoppy

The Boutiques descriptor is fetched directly from the QSMxT repository using version tags (e.g., v8.2.0), ensuring you always get the correct descriptor for your QSMxT version.

Quick Start

1. Install Nipoppy

pip install nipoppy

2. Set up your Nipoppy dataset

# Create a new Nipoppy dataset
nipoppy init --dataset /path/to/my_dataset

3. Generate QSMxT pipeline configuration

# Clone this repository
git clone https://github.com/QSMxT/qsmxt-nipoppy.git
cd qsmxt-nipoppy

# Generate pipeline config (fetches descriptor from QSMxT v8.2.0 tag)
./scripts/sync_descriptor.sh 8.2.0 /path/to/my_dataset/pipelines/processing/qsmxt-8.2.0

The script fetches the Boutiques descriptor from the QSMxT repository at the specified version tag and generates all required Nipoppy configuration files.

4. Download the QSMxT container

# Pull the container image
apptainer pull docker://vnmd/qsmxt:8.2.0

# Move to your dataset's containers directory
mv qsmxt_8.2.0.sif /path/to/my_dataset/containers/

5. Configure your dataset

Add QSMxT to your global_config.json:

{
    "PROC_PIPELINES": [
        {
            "NAME": "qsmxt",
            "VERSION": "8.2.0"
        }
    ],
    "PIPELINE_VARIABLES": {
        "PROCESSING": {
            "qsmxt": {
                "8.2.0": {
                    "QSMXT_DO_QSM": "on",
                    "QSMXT_PREMADE": "default"
                }
            }
        }
    }
}

6. Run QSMxT

nipoppy process \
    --dataset /path/to/my_dataset \
    --pipeline qsmxt \
    --pipeline-version 8.2.0 \
    --participant sub-01 \
    --session ses-01

Repository Structure

qsmxt-nipoppy/
├── version.txt              # Current tested QSMxT version
├── scripts/
│   └── sync_descriptor.sh   # Fetches descriptor from QSMxT repo
├── example_dataset/         # Example Nipoppy dataset with sample DICOMs
│   ├── global_config.json
│   ├── sourcedata/imaging/pre_reorg/  # Sample DICOM data
│   └── WORKFLOW_INSTRUCTIONS.md
└── .github/workflows/
    └── test.yml             # CI: validates and runs integration test

How It Works

The sync_descriptor.sh script:

1. Fetches the Boutiques descriptor from the QSMxT GitHub repository using the version tag (e.g., v8.2.0)
2. Validates the downloaded JSON
3. Generates Nipoppy configuration files:
   • config.json - Pipeline configuration
   • invocation.json - Runtime parameters with Nipoppy template strings
   • tracker.json - Output file tracking patterns
   • hpc.json - HPC job configuration

This ensures you always get the correct descriptor that matches your QSMxT version.

Pipeline Variables

Customize QSMxT processing via pipeline variables in global_config.json. Below is just a small subset of possible options:

Variable	Options	Description
QSMXT_DO_QSM	on, off	Run QSM pipeline
QSMXT_QSM_ALGORITHM	tgv, tv, nextqsm, rts	QSM algorithm
QSMXT_PREMADE	default, gre, epi, bet, fast, body, nextqsm	Premade preset

HPC Usage

For running on HPC clusters, the generated hpc.json can be customized:

{
    "ACCOUNT": "your_account",
    "TIME": "4:00:00",
    "CORES": "4",
    "MEMORY": "16G"
}

Then run:

nipoppy process --dataset . --pipeline qsmxt --hpc slurm

Testing

The CI workflow runs on every push and:

1. Validates - Fetches descriptor from QSMxT tag, validates with Boutiques
2. Integration test - Runs full pipeline on example DICOM data (self-hosted runner)

Using Different Versions

To use a different QSMxT version:

# Update version.txt (optional, for reference)
echo "8.1.0" > version.txt

# Generate config for that version
./scripts/sync_descriptor.sh 8.1.0 /path/to/dataset/pipelines/processing/qsmxt-8.1.0

# Pull matching container
apptainer pull docker://vnmd/qsmxt:8.1.0

Links

• QSMxT Documentation
• QSMxT GitHub
• Nipoppy Documentation
• Boutiques Documentation

License

MIT License - see LICENSE

Citation

If you use QSMxT via Nipoppy, please cite:

• Stewart AW, et al. (2022). QSMxT: Robust masking and artifact reduction for quantitative susceptibility mapping. Magnetic Resonance in Medicine.
• The Nipoppy development team. Nipoppy: A lightweight framework for neuroimaging data organization and processing.