README.md

---
license: apache-2.0
library_name: direct
tags:
  - mri
  - reconstruction
  - vsharp
  - fastmri
  - cmrxrecon
pipeline_tag: image-to-image
---

# DIRECT — vSHARP multi-anatomy

Pretrained [vSHARP](https://arxiv.org/abs/2309.09954) models for multi-coil MRI reconstruction. Each release is an inference-ready pair:

```text
vsharp_<name>.yaml   # inference-only DIRECT config
vsharp_<name>.pt     # weights
```

Paper: [arXiv:2309.09954](https://arxiv.org/abs/2309.09954) · Framework: [DIRECT](https://github.com/NKI-AI/direct)

## Datasets & provenance

Official portals (accept each dataset’s Data Sharing Agreement where required):

| Model | Official source | Notes |
|-------|-----------------|-------|
| `vsharp_brain` | [fastMRI brain](https://fastmri.med.nyu.edu/) (multi-coil Cartesian) | Same portal as knee; original challenge data / papers via NYU FAIR fastMRI. |
| `vsharp_knee` | [fastMRI knee](https://fastmri.med.nyu.edu/) (multi-coil Cartesian) | Fully sampled multi-coil knee MRI ([Zbontar et al.](https://arxiv.org/abs/1811.08839)). |
| `vsharp_prostate` | [fastMRI prostate](https://fastmri.med.nyu.edu/) · [Sci Data](https://www.nature.com/articles/s41597-024-03252-w) · [code](https://github.com/cai2r/fastMRI_prostate) | T2 multi-coil. Raw volumes are `(averages, slices, coils, readout, phase)` with **three averages at GRAPPA R=2** (odd/even line interleaving across averages). For these models, each average was **GRAPPA-reconstructed**, then the averages were **combined into a single fully sampled multi-coil volume** `(slices, coils, readout, phase)` using the official T2 GRAPPA pipeline ([`prostate_t2_recon.py`](https://github.com/cai2r/fastMRI_prostate/blob/main/fastmri_prostate/reconstruction/t2/prostate_t2_recon.py)). |
| `vsharp_breast` | [fastMRI breast](https://fastmri.med.nyu.edu/) · [Radiol AI](https://pubs.rsna.org/doi/10.1148/ryai.240345) · [code](https://github.com/eddysolo/demo_dce_recon) | Native acquisition is **radial GRASP DCE**. For these models, radial k-space was **regridded to Cartesian** multi-coil volumes before training / inference with DIRECT. |
| `vsharp_cardiac` | [CMRxRecon](https://cmrxrecon.github.io/) 2023 cine · Synapse [`syn51471091`](https://www.synapse.org/#!Synapse:syn51471091) · [Sci Data](https://doi.org/10.1038/s41597-024-03525-4) | Multi-coil cine cardiac MRI from the 2023 challenge release. |
| `vsharp_universal` | fastMRI brain/knee/prostate/breast + CMRxRecon **2023 / 2024 / 2025** | Same preprocessing as the anatomy-specific models above. CMRxRecon hub: [cmrxrecon.github.io](https://cmrxrecon.github.io/); Synapse portals for later challenges are linked from that site. |

## Training protocol

These models were **not** trained at a single fixed acceleration or scheme. All used the same mixed schedule:

| | Values |
|---|---|
| Accelerations \(R\) | `2, 4, 6, 8, 10` |
| Center fractions (ACS) | `0.16, 0.08, 0.06, 0.04, 0.02` (paired with \(R\): 2→0.16, 4→0.08, 6→0.06, 8→0.04, 10→0.02) |
| Sampling schemes | FastMRIEquispaced, FastMRIRandom, Gaussian1D, Gaussian2D, VariableDensityPoisson, Radial |

`vsharp_universal` was trained jointly across the anatomies / challenges above; anatomy-specific models were trained on one dataset each.

## Files & default inference masks

Released YAMLs are **inference-only** (no `training` / `validation` blocks). Each pins **one** acceleration and **one** ACS fraction — DIRECT’s mask sampler draws randomly from lists, so multi-\(R\) lists belong in training only.

| File pair | Default mask | Default \(R\) / ACS |
|-----------|--------------|---------------------|
| `vsharp_brain.{yaml,pt}` | FastMRIRandom | 4× / 0.08 |
| `vsharp_knee.{yaml,pt}` | FastMRIEquispaced | 4× / 0.08 |
| `vsharp_prostate.{yaml,pt}` | FastMRIEquispaced | 4× / 0.08 |
| `vsharp_breast.{yaml,pt}` | Radial | 4× / 0.08 |
| `vsharp_cardiac.{yaml,pt}` | FastMRIEquispaced | 4× / 0.08 |
| `vsharp_universal.{yaml,pt}` | FastMRIEquispaced | 4× / 0.08 |

## Changing acceleration or scheme

Edit `inference.dataset.transforms.masking` and keep **both lists length 1**:

```yaml
inference:
  dataset:
    transforms:
      masking:
        name: FastMRIEquispaced   # any training scheme above
        accelerations: [8]        # single R
        center_fractions: [0.04]  # matching ACS
```

| Target \(R\) | `accelerations` | `center_fractions` |
|-------------|-----------------|--------------------|
| 2× | `[2]` | `[0.16]` |
| 4× | `[4]` | `[0.08]` |
| 6× | `[6]` | `[0.06]` |
| 8× | `[8]` | `[0.04]` |
| 10× | `[10]` | `[0.02]` |

## Install DIRECT

```bash
git clone https://github.com/NKI-AI/direct.git
cd direct
conda create --name direct python=3.12
conda activate direct
pip install meson-python meson ninja
pip install --no-build-isolation -e ".[dev]"
```

## Usage

```bash
hf download NKI-AI/direct-vsharp-multianatomy --local-dir ./vsharp_multianatomy

direct predict ./predictions \
  --cfg ./vsharp_multianatomy/vsharp_knee.yaml \
  --checkpoint ./vsharp_multianatomy/vsharp_knee.pt \
  --data-root /path/to/fastmri/knee/multicoil_val \
  --num-gpus 1
```

The first argument is the **prediction output directory**.

## Citation

If you use these models or [DIRECT](https://github.com/NKI-AI/direct), please cite the DIRECT toolkit and the method paper(s) below.

### DIRECT

```bibtex
@article{DIRECTTOOLKIT,
  title={DIRECT: Deep Image REConstruction Toolkit},
  author={Yiasemis, George and Moriakov, Nikita and Karkalousos, Dimitrios and Caan, Matthan and Teuwen, Jonas},
  journal={Journal of Open Source Software},
  volume={7},
  number={73},
  pages={4278},
  year={2022},
  doi={10.21105/joss.04278},
  url={https://doi.org/10.21105/joss.04278}
}
```

### Method

```bibtex
@article{yiasemis2024vsharp,
  title={vSHARP: variable Splitting Half-quadratic {ADMM} algorithm for Reconstruction of inverse Problems},
  author={Yiasemis, George and Moriakov, Nikita and S{\'a}nchez, Clara I. and Sonke, Jan-Jakob and Teuwen, Jonas},
  journal={Magnetic Resonance Materials in Physics, Biology and Medicine},
  year={2024},
  doi={10.1007/s10334-024-01189-0}
}
```