Project-MONAI / Project-MONAI/tutorials
Add introductory k-space basics tutorial for MRI reconstruction
Nobody has claimed this yet.
- Dominant language
- Jupyter Notebook
- Stars
- 2.5k
- Forks
- 803
- Avg merge
- 6d 22h
- Merged PRs (30d)
- 3
Description
Summary
Adds a beginner-friendly introductory tutorial for MRI reconstruction using the fastMRI knee single-coil dataset and MONAI's reconstruction transforms.
Changes
- New notebook:
reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb- Part 1: What is k-space (loading real data, inverse FFT)
- Part 2: Fourier transform connection (low vs. high frequencies)
- Part 3: Undersampling and aliasing artifacts (1x, 2x, 4x, 8x)
- Part 4: Random vs. equispaced masks using
RandomKspaceMaskd/EquispacedKspaceMaskd - Part 5: Full MONAI preprocessing pipeline (
FastMRIReader→CenterSpatialCropd→ReferenceBasedNormalizeIntensityd) - Part 6: Zero-filled reconstruction → deep learning connection
- New README:
reconstruction/MRI_reconstruction/tutorials/README.md - Updated
README.md: Added missing Reconstruction section listing this tutorial plus existingunet_demoandvarnet_demo - Updated
runner.sh: Added notebook todoesnt_contain_max_epochs(no training loop)
Dataset
- Uses fastMRI knee single-coil validation set (non-commercial license)
- Only one
.h5file (~300 MB) required — no need for the full ~1.5 TB brain multi-coil download - Added to
skip_run_papermillvia existing.*MRI_reconstruction.*pattern
Design decisions
- Bridges the gap between newcomers and production tutorials (
unet_demo,varnet_demo) - Uses
CenterSpatialCropdinstead ofReferenceBasedSpatialCropdto handle the k-space (640×368) vs ground truth (320×320) dimension mismatch - No training loop — purely educational, runs without GPU
Test plan
- Notebook runs end-to-end on Google Colab with real fastMRI knee data (
file1000000.h5) - All 5 matplotlib visualizations render correctly
- Pipeline output shapes:
kspace_masked_ifftandreconstruction_escboth(1, 320, 320) - PEP 8 passes via
./runner.sh -t reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb --no-run - Copyright header present with correct formatting
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb and compare it with the existing unet_demo and varnet_demo tutorials. Run ./runner.sh -t reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb --no-run, then validate the notebook with fastMRI file1000000.h5 in Colab. Done means the visualizations render, the stated output shapes match, and the README and runner.sh entries are updated.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter-notebook, pytorch
- Domain
- documentation, machine-learning
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100