asl-mri-utils

A repository of utilities for ASL data post-processing.

Utilities for Siemens arterial spin labeling (ASL) DICOM processing:

• Volume-order analysis (asl-mri-utils order): recovers the true LABEL/CONTROL/M0/TI acquisition order of a multi-TI, single- or multi-echo Siemens enhanced-DICOM ASL series directly from per-frame DICOM tags (ASL Context, Siemens private ordering tag), independent of filenames or protocol names.
• DICOM-to-NIfTI conversion (asl-mri-utils convert): wraps a locally installed dcm2niix/dcm2niix_afni binary to convert a Siemens ASL series directory to NIfTI, then merges the per-echo output into a single, oxasl-ready *_asl.nii.gz (label/control volumes, chronologically ordered) and *_mzero.nii.gz (M0 volumes), with a matching *_aslcontext.tsv and an *_oxasl_params.json recording the (iaf, order, tis, tes, rpts) shape for oxasl/oxasl_multite. Volume counts are checked against the DICOM-derived order at every step.
• Perfusion subtraction (asl-mri-utils subtract): computes CONTROL-LABEL difference images per TI using standard pairwise, surround, or sinc subtraction (Liu & Wong 2005, NeuroImage 24:207-215). --recommend block|event_related picks a single method per the paper's design-dependent guidance instead of listing --methods by hand. --sinc-interp swaps the sinc method's estimator for an alternative bidirectional interpolator (windowed-sinc, FFT, Gaussian process regression, or a Kalman filter/RTS smoother; see docs/interpolate.md).
• Series discovery (asl-mri-utils discover): finds candidate DICOM series directories under a root.

Siemens-only by design: this package relies on the standard ASL DICOM tags plus a Siemens private tag for TI ordering, and fails loudly (specific exceptions) rather than guessing when expected tags are absent.

Contents

• docs/dicom.md -- Siemens tag reading, ASL Context classification rule
• docs/order.md -- ordering/pairing logic, order.tsv schema
• docs/discovery.md -- series discovery, DICM sniffing
• docs/convert.md -- dcm2niix wrapping, oxasl_params.json fields
• docs/merge.md -- chronological concatenation into oxasl-ready output
• docs/subtract.md -- Liu & Wong (2005) equations for standard/surround/sinc subtraction
• docs/interpolate.md -- windowed-sinc, FFT, Gaussian process, and Kalman/RTS interpolation, with visual examples

Requirements

A local dcm2niix or dcm2niix_afni installation is required for asl-mri-utils convert (not bundled). Locate it via --dcm2niix-path, the ASL_MRI_UTILS_DCM2NIIX environment variable, or PATH.

Install

pip install asl-mri-utils

For local development, from a clone of this repository:

pip install -e .

Usage

asl-mri-utils order <dicom_series_dir> [<dicom_series_dir> ...] [--outdir DIR]
asl-mri-utils order --all [ROOT] [--outdir DIR]
asl-mri-utils convert <dicom_series_dir> --outdir DIR [--dcm2niix-path PATH] [--overwrite]
asl-mri-utils subtract <nii> <order_tsv> [--ti N ...] [--methods standard surround sinc] [--recommend block|event_related] [--sinc-interp truncated|windowed_sinc|fft|gp|kalman] [--outdir DIR]
asl-mri-utils discover [ROOT]