Metadata-Version: 2.5
Name: asl-mri-utils
Version: 0.6.1
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 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](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, `oxasl_params.json` fields
- [docs/merge.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/merge.md) -- chronological concatenation into oxasl-ready output
- [docs/subtract.md](https://github.com/srikash/asl-mri-utils/blob/main/docs/subtract.md) -- 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-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> [<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]
```
