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 one Siemens ASL series directory to NIfTI, entirely per echo. For each echo, writes an oxasl-ready *_echo-0N_asl.nii.gz (label/control volumes, chronologically ordered) and *_echo-0N_mzero.nii.gz (M0 volumes), a matching *_echo-0N_aslcontext.tsv, and an *_echo-0N_oxasl_params.json recording the (iaf, order, ntis, tis_ms, rpts) shape for oxasl (tis_ms is auto-derived from the DICOM header where the acquisition protocol's TIs are present there, null with a note otherwise). Also embeds each NIfTI's BIDS SliceTiming into its header via 3drefit -Tslices, when an AFNI install and a JSON sidecar with that field are available. Volume counts are checked against the DICOM-derived order at every step.
• Timeseries splitting (asl-mri-utils split): splits one echo's timeseries into per-TI NIfTIs (*_TI<k>.nii.gz), each further split into its label-only and control-only subseries (*_TI<k>_label.nii.gz, *_TI<k>_control.nii.gz). Accepts either the raw per-echo timeseries or the paired *_asl.nii.gz, auto-detected from its own volume count.
• Perfusion subtraction (asl-mri-utils subtract): computes perfusion-weighted difference images per TI. The default method, simple, is just label - control (and its negation) built directly on split's own per-TI output; pass --methods standard surround sinc instead for Liu & Wong (2005, NeuroImage 24:207-215) pairwise/surround/sinc subtraction (CONTROL - LABEL). --recommend block|event_related picks one of those three per the paper's design-dependent guidance instead of listing --methods by hand. --mc motion-corrects first (mcflirt -spline_final -cost normmi); --mean/--tsnr add a temporal-mean or temporal-mean/temporal-std companion for every diff file produced. --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, per-echo oxasl_params.json fields, slice-timing embedding
• docs/merge.md -- chronological splitting into one echo's oxasl-ready output
• docs/split.md -- per-TI, per-label/control timeseries splitting
• docs/subtract.md -- the simple method plus 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-bin, the ASL_MRI_UTILS_DCM2NIIX environment variable, or PATH.

An AFNI installation (3drefit) is optional for convert's slice-timing embedding step -- skipped, not raised, if it isn't found. An FSL installation (mcflirt) is required for asl-mri-utils subtract --mc (not bundled). Locate it via --mcflirt-bin, the ASL_MRI_UTILS_MCFLIRT 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 <in_dir> <out_dir> [--dcm2niix-bin PATH] [--overwrite]
asl-mri-utils split <nii> <order_tsv> [--echo N] [--ti N ...] [--outdir DIR]
asl-mri-utils subtract <nii> <order_tsv> [--ti N ...] [--methods simple|standard|surround|sinc ...] [--recommend block|event_related] [--sinc-interp truncated|windowed_sinc|fft|gp|kalman] [--mc] [--mcflirt-bin PATH] [--mean] [--tsnr] [--outdir DIR]
asl-mri-utils discover [ROOT]