Add k-space basics tutorial for MRI reconstruction

[ViSaReVe]

git push -u origin add-kspace-basics-tutorial
Adds an introductory notebook covering k-space fundamentals, Fourier transform connection, aliasing from undersampling, and MONAI's reconstruction transforms using the fastMRI knee single-coil dataset. Also adds the missing Reconstruction section to the main README.

Fixes # .

Description

A few sentences describing the changes proposed in this pull request.

Checks

• Avoid including large-size files in the PR.
• Clean up long text outputs from code cells in the notebook.
• For security purposes, please check the contents and remove any sensitive info such as user names and private key.
• Ensure (1) hyperlinks and markdown anchors are working (2) use relative paths for tutorial repo files (3) put figure and graphs in the ./figure folder
• Notebook runs automatically ./runner.sh -t <path to .ipynb file>

Summary by CodeRabbit

• New Features

  • Added an MRI Reconstruction tutorial series, including a K‑space basics notebook using fastMRI knee data and demos for U‑Net and VarNet reconstructions.

• Documentation

  • Main README updated with a new "Reconstruction" section replacing a placeholder.
  • Added a tutorials README describing contents, prerequisites, dataset info, and links to related demos.

• Chores

  • Test/runner configuration updated to include the new tutorial in the execution list.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

💤 Files selected but had no reviewable changes (1)

• reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

Adds MRI reconstruction tutorial materials: a new k-space fundamentals Jupyter notebook, a tutorials README, an update to the project README adding a "Reconstruction" section, and the notebook added to the runner exemption list.

Changes

Cohort / File(s)	Summary
Project README README.md	Replaced a non‑English placeholder with a new Reconstruction section listing three MRI reconstruction tutorials: K‑Space Basics, U‑Net, and VarNet.
Tutorials README reconstruction/MRI_reconstruction/tutorials/README.md	Added a folder README describing the MRI reconstruction tutorial series, dataset notes for fastMRI knee (single‑coil), prerequisites, and links to related demos.
Tutorial Notebook reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb	Added a comprehensive notebook covering k‑space fundamentals, undersampling/aliasing, FastMRIReader data loading, MONAI reconstruction transforms and pipelines (e.g., RandomKspaceMaskd, EquispacedKspaceMaskd), zero‑filled vs. ground‑truth reconstructions, visualizations, and cleanup.
Runner Config runner.sh	Added the new notebook to the list of files exempted from max_epochs handling in the runner script.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 I hop through k-space, masks in tow,
FFTs hum soft in silver glow,
Pixels line up, aliasing hides,
U‑Nets learn where truth resides,
I nibble bugs and patch the code. 🥕

🚥 Pre-merge checks | ✅ 3 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete. While it mentions the tutorial and README updates, all checklist items remain unchecked, and specific details about file sizes, output cleanup, and test execution are not addressed.	Complete the checklist by checking applicable items and providing explicit confirmation that the PR meets each requirement, particularly regarding large files, notebook outputs, hyperlinks, and runner.sh testing.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main contribution: adding a k-space basics tutorial for MRI reconstruction, which is reflected in the new notebook and README documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@README.md`:
- Line 397: Remove the garbled terminal/encoding artifact "ECHO�� �����Ǿ�
�ֽ��ϴ�." found at the end of README.md (the text shown in the diff) so the file
ends cleanly; ensure you delete that line, trim any trailing blank lines or
whitespace, and save the README.md with UTF-8 encoding to prevent reintroducing
encoding artifacts.

In
`@reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb`:
- Around line 150-159: Check that data_path exists and contains .h5 files before
using os.listdir and indexing sample_files: verify os.path.exists(data_path) and
os.path.isdir(data_path), catch FileNotFoundError from os.listdir (or test
existence first), build sample_files = [...] and then if not sample_files raise
a clear RuntimeError or ValueError explaining the dataset is missing and how to
download it, otherwise set sample_file = os.path.join(data_path,
sample_files[0]) and print as before; reference symbols: data_path, os.listdir,
sample_files, sample_file.

🧹 Nitpick comments (2)

reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb (2)

462-466: Duplicate utility functions: as_numpy and to_numpy.

as_numpy (line 462) and to_numpy (line 561) are functionally identical — both convert a torch tensor or array to numpy. Consider defining one and reusing it.

Also applies to: 561-565

---

47-51: Minor: spaces in pip extras specifier.

"monai-weekly[pillow, tqdm]" has a space after the comma in the extras specifier. While modern pip handles this, it's unconventional and could cause issues with older pip versions. Consider "monai-weekly[pillow,tqdm]".

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In
`@reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb`:
- Around line 753-755: The cleanup currently removes root_dir even when a temp
directory was created because MONAI_DATA_DIRECTORY is unset; instead, fail early
when MONAI_DATA_DIRECTORY is not provided so users know to set it (or explicitly
opt into using a temp dir). Update the notebook logic around the
directory/root_dir creation (the variable directory and root_dir) to check the
MONAI_DATA_DIRECTORY env var and raise a clear error if it's None (with guidance
to set MONAI_DATA_DIRECTORY to the fastMRI data path), and remove the
unconditional shutil.rmtree(root_dir) cleanup for the fallback case; ensure the
error is raised before any downstream operations (the cells that previously
error out) so the user gets a clear prompt rather than the notebook silently
creating and later deleting a useless temp dir.
- Around line 456-478: The MONAI pipeline returns a full volume but the code
uses ground_truth[slice_idx] (single slice); to fix, extract the same slice_idx
from the MONAI outputs before squeezing: when building rand_recon, index
random_result["kspace_masked_ifft"] with [slice_idx] (or appropriate
channel/slice axis) then call as_numpy(...).squeeze() and take abs; do the same
for equi_recon (and any other recon variables) so their shapes match
ground_truth and imshow renders the correct middle slice; reference variables:
as_numpy, random_result["kspace_masked_ifft"], rand_recon, equi_recon,
ground_truth, slice_idx.

🧹 Nitpick comments (2)

reconstruction/MRI_reconstruction/tutorials/01_kspace_basics_fastmri_knee.ipynb (2)

549-553: Duplicate helper: to_numpy is identical to as_numpy (line 456).

Three near-identical tensor-to-numpy helpers are defined across the notebook (as_numpy, to_numpy, as_numpy_2d). Consider defining a single utility once (e.g., in the imports cell) and reusing it, adding the 2D squeeze variant as an optional parameter or a second thin wrapper.

---

212-212: Non-standard FFT shift ordering (works for even dimensions only).

The standard convention for MRI reconstruction is fftshift(ifft2(ifftshift(kspace))), but this line uses ifftshift(ifft2(fftshift(kspace))) — the shifts are swapped. For even-length dimensions (typical for fastMRI data), fftshift and ifftshift are equivalent, so results are correct. However, since this is a pedagogical tutorial on k-space fundamentals, using the standard ordering would avoid confusing learners who cross-reference with textbooks or other MRI reconstruction code.

Suggested fix

-image_from_kspace = np.fft.ifftshift(np.fft.ifft2(np.fft.fftshift(kspace_slice)))
+image_from_kspace = np.fft.fftshift(np.fft.ifft2(np.fft.ifftshift(kspace_slice)))

[ericspod]

Hi @ViSaReVe thanks for the notebook, I think it looks good though I haven't run it myself and it can't as yet be automatically tested. Please look at the comments I made and coderabbit to update a few things. The errors that have come up from the CI jobs is related to this I think and we're looking into it.

[ViSaReVe]

Thanks for the review @ericspod! I've addressed all comments:

Removed MONAI_DATA_DIRECTORY / root_dir / cleanup cells — now uses data_path = os.path.join("YOUR_DIR_HERE", "knee_singlecoil_val") with error handling
Replaced custom as_numpy() with monai.utils.type_conversion.convert_data_type
Replaced custom ensure_channel_first_2d() with EnsureChannelFirstd(channel_dim="no_channel")
Fixed slice mismatch in Part 4 visualization for multi-slice output

[ericspod]

Hi @ViSaReVe I think it's good now to include. We should be able to get through the CI issues as well. If you wanted you could run the notebook again and not clear the cell output, this would leave plots and code output in place so readers can see what the images are without running the notebook themselves. The file gets larger but that's fine, totally optional though and feel free to merge if you want.

[ViSaReVe]

Thanks @ericspod! I've added the cell outputs from a Colab run — the notebook now includes 4 plots (Parts 1, 2, 3, and 6) and key text outputs (data shapes, pipeline shapes) so readers can see the results without running it. Ready to merge when you are!

[ericspod]

Thanks @ericspod! I've added the cell outputs from a Colab run — the notebook now includes 4 plots (Parts 1, 2, 3, and 6) and key text outputs (data shapes, pipeline shapes) so readers can see the results without running it. Ready to merge when you are!

Thanks for the update but a number of the plots look blank (or nearly so). These are mostly the kspace plots but the middle figure of plot 2 I don't think should be so empty. Can anything be done to work on the axis range of these? I think it's just matplotlib not showing things well rather than the data being wrong since the inverse fft works as expected. If you can improve those that would be great, or we can just merge now.