Project-MONAI / Project-MONAI/tutorials

Add introductory k-space basics tutorial for MRI reconstruction

Open
#2,055 0 comments 0 reactions 0 assignees View on GitHub

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 (FastMRIReaderCenterSpatialCropdReferenceBasedNormalizeIntensityd)
    • 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 existing unet_demo and varnet_demo
  • Updated runner.sh: Added notebook to doesnt_contain_max_epochs (no training loop)
Dataset
  • Uses fastMRI knee single-coil validation set (non-commercial license)
  • Only one .h5 file (~300 MB) required — no need for the full ~1.5 TB brain multi-coil download
  • Added to skip_run_papermill via existing .*MRI_reconstruction.* pattern
Design decisions
  • Bridges the gap between newcomers and production tutorials (unet_demo, varnet_demo)
  • Uses CenterSpatialCropd instead of ReferenceBasedSpatialCropd to 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_ifft and reconstruction_esc both (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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.