Metadata-Version: 2.5
Name: asl-mri-utils
Version: 0.8.0
Summary: Utilities for Siemens arterial spin labeling (ASL) DICOM volume-order analysis and DICOM-to-NIfTI conversion
Project-URL: Homepage, https://github.com/srikash/asl-mri-utils
Project-URL: Repository, https://github.com/srikash/asl-mri-utils
Project-URL: Issues, https://github.com/srikash/asl-mri-utils/issues
Project-URL: Documentation, https://github.com/srikash/asl-mri-utils/tree/main/docs
Author-email: Sriranga Kashyap <srikashmri@gmail.com>
Maintainer-email: Sriranga Kashyap <srikashmri@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ASL,DICOM,MRI,NIfTI,Siemens,arterial spin labeling,neuroimaging,perfusion
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: nibabel>=5.0
Requires-Dist: numpy>=1.26
Requires-Dist: pydicom>=3.0
Description-Content-Type: text/markdown

# 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](https://github.com/srikash/asl-mri-utils/blob/main/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](https://github.com/srikash/asl-mri-utils/blob/main/docs/dicom.md) -- Siemens tag reading, ASL Context classification rule
- [docs/order.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/order.md) -- ordering/pairing logic, `order.tsv` schema
- [docs/discovery.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/discovery.md) -- series discovery, DICM sniffing
- [docs/convert.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/convert.md) -- dcm2niix wrapping, per-echo `oxasl_params.json` fields, slice-timing embedding
- [docs/merge.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/merge.md) -- chronological splitting into one echo's oxasl-ready output
- [docs/split.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/split.md) -- per-TI, per-label/control timeseries splitting
- [docs/subtract.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/subtract.md) -- the `simple` method plus Liu & Wong (2005) equations for standard/surround/sinc subtraction
- [docs/interpolate.md](https://github.com/srikash/asl-mri-utils/blob/main/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]
```
