Metadata-Version: 2.4
Name: asl-qc
Version: 0.1.0
Summary: CBF-only QEI-Net quality estimation
License-Expression: MIT
Project-URL: Repository, https://github.com/xavibeltranurbano/ASL-QC
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==2.4.3
Requires-Dist: nibabel==5.4.0
Requires-Dist: torch==2.11.0
Requires-Dist: torchio==1.2.0
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/xavibeltranurbano/ASL-QC/main/docs/images/logo.png" width="40%" alt="ASL-QC">
</p>

# ASL-QC

[![Python
versions](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/)
[![PyPI
package](https://img.shields.io/badge/package-asl--qc-orange.svg)](https://pypi.org/project/asl-qc/)

ASL-QC is a Python library for automated quality assessment of arterial
spin labeling (ASL) cerebral blood flow (CBF) maps using deep learning. It is developed by the [Detre Lab at the University of Pennsylvania](https://hosting.med.upenn.edu/detrelab/) and distributed as open-source software.

## Overview

ASL-QC provides automated quality assessment of ASL-derived CBF maps. Given a
single CBF NIfTI image, ASL-QC returns a continuous quality score between 0 and 1:

- `0` — lowest predicted quality
- `1` — highest predicted quality

The model operates directly on the CBF map and does not require the underlying
ASL images, a structural image, or any additional input.

## Installation

ASL-QC requires Python 3.13 or later. We recommend installing it in a
dedicated environment, for example with conda:

``` bash
conda create -n asl-qc python=3.13
conda activate asl-qc
```

ASL-QC can then be installed either from PyPI or directly from the source
repository.

### Option 1: Install from PyPI

``` bash
python -m pip install asl-qc
```

### Option 2: Install from repository

``` bash
git clone https://github.com/xavibeltranurbano/ASL-QC
cd ASL-QC
python -m pip install .
```

## Getting Started

### Python API

``` python
from asl_qc import predict_quality

quality = predict_quality("/path/to/cbf.nii.gz")
print(quality)
```

By default the model runs on the GPU if one is available and on the CPU
otherwise. To choose the device explicitly, pass `device="cpu"` or
`device="cuda"`:

``` python
quality = predict_quality("/path/to/cbf.nii.gz", device="cpu")
```

The returned quality score ranges from 0 to 1, with higher values
indicating higher predicted CBF map quality.

### Command-Line Interface

ASL-QC can also be run directly from the command line:

``` bash
asl-qc --path-cbf /path/to/cbf.nii.gz
```

Use `--device cpu` or `--device cuda` to select the device (default: `auto`).

### Input Preprocessing

Before quality estimation, each CBF image is automatically:

1.  Converted to canonical RAS orientation
2.  Resampled to 2.5 mm isotropic resolution
3.  Cropped or padded around the nonzero CBF support to `96 × 96 × 64`
4.  Clipped to `[-100, 100]`
5.  Scaled by `100`

## Training

The training scripts can be found in
[src/training_scripts/](https://github.com/xavibeltranurbano/ASL-QC/tree/main/src/training_scripts).

## Model Development

ASL-QC was developed using a 3D residual convolutional neural network
with four convolutional blocks and a fully connected regression head.
Model development and evaluation used nested five-fold cross-validation,
with folds stratified by scanner vendor and quality rating. The released model is an ensemble of the five models trained across the
outer cross-validation folds. Each model was optimized using mean
squared error (MSE) between the predicted quality score and the mean
expert rating for the corresponding CBF map.

![ASL-QC architecture](https://raw.githubusercontent.com/xavibeltranurbano/ASL-QC/main/docs/images/framework.png)

### Training Dataset

The training dataset contains 450 CBF maps from multiple cohorts, sites,
scanner vendors, ASL acquisition protocols, and background-suppression
(BS) configurations.

| Cohort | Scanner | Age<br>(mean ± SD) | Female<br>n (%) | PLD | Labeling<br>time | Protocol | BS | Maps |
| :--- | :--- | ---: | ---: | ---: | ---: | :--- | :---: | ---: |
| ADNI | Siemens | 73.3 ± 7.4 | 17 (40%) | 1.9 s | 0.7 s | 2D PASL | No | 43 |
| ADNI | GE | 74.9 ± 7.5 | 12 (40%) | 2.025 s | 1.45 s | 3D PCASL | Yes | 30 |
| MESA | Siemens | 66.9 ± 8.6 | 25 (56%) | 2 s | 1.5 s | 3D PCASL | Yes | 45 |
| SPRINT | Siemens | 65.5 ± 8.2 | 13 (42%) | 1.5 s | 1.5 s | 2D PCASL | No | 31 |
| SPRINT | GE | 74.2 ± 7.7 | 7 (23%) | 2.025 s | 1.45 s | 3D PCASL | Yes | 30 |
| SPRINT | Philips | 67.3 ± 8.9 | 21 (42%) | 1.5 s | 1.5 s | 2D PCASL | No | 50 |
| DLBS | Philips | 54.9 ± 22.6 | 16 (64%) | 1.525 s | 1.65 s | 2D PCASL | No | 25 |
| CARDIA | Siemens | 50.5 ± 3.5 | 12 (63%) | 1.5 s | 1.5 s | 2D PCASL | No | 19 |
| NACC | Siemens | 69.1 ± 12.8 | 29 (53%) | 1.8 s | 1.8 s | 3D PCASL | Yes | 55 |
| VCID | Siemens | 54.4 ± 9.2 | 26 (58%) | 2 s | 3 s | 3D PCASL | Yes | 45 |
| VCID | GE | 61.2 ± 11.0 | 22 (55%) | 2 s | 3 s | 3D PCASL | Yes | 40 |
| Institutional data | Siemens | 45.5 ± 19.2 | 18 (49%) | 1.2–2 s | 1.8–3 s | 3D PCASL | Yes | 37 |
| **Total** | **Siemens 275; GE 100; Philips 75** | **63.9 ± 14.4** | **218 (48%)** | **1.2–2.025 s** | **0.7–3 s** | **3D PCASL 282; 2D PCASL 125; 2D PASL 43** | **Yes 282; No 168** | **450** |

### Rating Strategy

Four expert raters independently evaluated each CBF map using a five-point
quality scale. The ground-truth quality score was defined as the mean of the
four expert ratings and normalized to the range `[0, 1]`.

| Rating | Interpretation guidelines |
| :---: | --- |
| **0.00** | No discernible brain anatomy; severe artifacts and/or poor resolution; completely uninterpretable. |
| **0.25** | Anatomy is barely recognizable; major artifacts and/or poor resolution; very limited interpretability. |
| **0.50** | Anatomy is recognizable; minor artifacts and/or smoothness; moderate spatial resolution; basic interpretability. |
| **0.75** | Good anatomical detail; limited artifacts and/or smoothness; good spatial resolution; good interpretability. |
| **1.00** | Excellent anatomical detail; no artifacts; high spatial resolution; good interpretability. |

![Rating strategy](https://raw.githubusercontent.com/xavibeltranurbano/ASL-QC/main/docs/images/rating_strategy.png)


## Citation

If you use ASL-QC or its pretrained model in your work, please cite:

> Beltran-Urbano X, Taso M, Nasrallah I, Detre JA, Wang Z, Dolui S.\
> **QEI-Net: A deep learning-based automated quality evaluation index
> for ASL CBF maps.**\
> *Proceedings of the 2025 ISMRM & ISMRT Annual Meeting & Exhibition.*
> 2025;0730.

## License

Please see the [LICENSE](https://github.com/xavibeltranurbano/ASL-QC/blob/main/LICENSE) file for licensing information.

## Links

-   [PyPI](https://pypi.org/project/asl-qc/)
