Automated ALPS App

Automated DTI-ALPS (Diffusion Tensor Imaging Along the Perivascular Space) analysis tool. Uses template-based registration to place ROIs in projection and association fiber regions, then calculates the DTI-ALPS index from diffusion tensor imaging data.

In: a folder of DWI subjects: NIfTI + .bvec / .bval, optionally a reverse phase-encode image for distortion correction.

Out: an alps_results.csv with one row per subject (left, right, and combined ALPS index), the ROI masks each number came from, and a timestamped run log.

The app can run in two ways:

1. GUI for setting up and inspecting a study,
2. CLI for headless batch processing on a cluster.

Quick start

pipx install dti-alps                                      # or grab the AppImage
dti-alps                                                   # launch the GUI
dti-alps run --subjects /data/cohort --output /data/out     # or process a cohort headless

MRtrix3 and FSL are not bundled — see Requirements.

Installation

Four routes. Pick by what you already have:

• pipx — you have Python 3.10+ and want dti-alps on your PATH
• AppImage — you want a double-click file and no Python setup
• conda — you already manage environments with conda
• From source

Whichever you choose, MRtrix3 and FSL must be installed separately and on your PATH (see External neuroimaging software).

pipx install dti-alps
dti-alps            # launch the GUI

chmod +x dti-alps-*-x86_64.AppImage
./dti-alps-*-x86_64.AppImage

conda install -c conda-forge pyside6 numpy scipy nibabel
pip install dti-alps

conda config --add channels conda-forge
conda config --set channel_priority strict

pip install -e ".[gui]"

Requirements

Python 3.10+, plus MRtrix3 and FSL on your PATH.

External neuroimaging software

These third-party programs must be installed and available on your system PATH. dti-alps run checks for them before starting and exits with code 3 if any are missing.

Usage

dti-alps                    # Launch GUI (default)
dti-alps run --subjects /data/cohort --output /data/out   # Process a cohort
dti-alps view               # Launch Results Viewer
dti-alps view /path         # Launch viewer with specific output folder
dti-alps report /path       # Generate quality reports
dti-alps reanalyze /path --sphere 3  # Reanalyze with different ROI shapes

dti-alps VERB --help lists the flags for any one verb.

Headless processing

dti-alps run executes the whole pipeline with no display attached.

# The simplest complete run: discovery, defaults, one command
dti-alps run --subjects /data/cohort --output /data/out

# A BIDS cohort, a protocol exported from the GUI, tuned ROIs
dti-alps run --subjects /bids/sub-*/ses-1/dwi --output /data/out \
    --config study-protocol.json --id-depth 3 --sphere 2,3 --nthreads 8

# Check what would happen before committing to a long run
dti-alps run --subjects /bids/sub-*/ses-1/dwi --output /data/out --dry-run

# Pick up where a preempted node left off
dti-alps run --subjects /data/cohort --output /data/out --resume

Protocol files

Rather than retyping long argument lists, save the analysis settings once and pass the file. Export a config file from the GUI's Output Setup page, then hand it to any run:

dti-alps run --subjects /data/cohort --output /data/out --config study-protocol.json

A protocol file holds what the analysis is; it is portable and shareable across machines. Where the results land is never part of it, which is why --output is always required.

--opt STAGE:NAME=VALUE sets any tool option inline, so you are never blocked on authoring a file:

dti-alps run --subjects /data/cohort --output /data/out \
    --opt dwifslpreproc:-eddy_options='--repol --slm=linear'

Output

A run fills --output with one directory per subject plus the cohort-level results:

/data/out/
├── alps_results.csv              # one row per subject: left, right, combined ALPS
├── alps_results_sphere2.csv      # one more CSV per extra ROI shape
├── dti_alps_20260803_141200.log  # the full run log
└── sub-01/
    ├── alps_result.json          # per-subject completion marker; --resume reads this
    ├── registration/             # brain mask, skull-stripped FA, transforms
    ├── rois/                     # the four masks: sub-01_left_proj.nii.gz, ...
    └── ...                       # intermediate NIfTIs (denoised, tensor, FA)

• dti-alps view /data/out opens this folder in the results viewer
• dti-alps report /data/out adds a quality_report_{shape}.csv alongside the results.

Troubleshooting

sudo apt install libxcb-cursor0     # Debian/Ubuntu

conda install -c conda-forge freetype harfbuzz --update-deps