Package: fastmri
fastMRIWebsite|Dataset|GitHub|PublicationsAccelerating Magnetic Resonance Imaging (MRI) by acquiring fewer measurements
has the potential to reduce medical costs, minimize stress to patients and make
MR imaging possible in applications where it is currently prohibitively slow or
expensive.fastMRIis a collaborative research project from
Facebook AI Research (FAIR) and NYU Langone Health to investigate the use of AI
to make MRI scans faster. NYU Langone Health has released fully anonymized knee
and brain MRI datasets that can be downloaded fromthe fastMRI dataset page. Publications
associated with the fastMRI project can be foundat the end of this README.This repository contains convenient PyTorch data loaders, subsampling
functions, evaluation metrics, and reference implementations of simple baseline
methods. It also contains implementations for methods in some of the
publications of the fastMRI project.DocumentationThe fastMRI DatasetThere are multiple publications describing different subcomponents of the data
(e.g., brain vs. knee) and associated baselines. All of the fastMRI data can be
downloaded from thefastMRI dataset page.Project Summary, Datasets, Baselines:fastMRI: An Open Dataset and Benchmarks for Accelerated MRI ({J. Zbontar*, F. Knoll*, A. Sriram*} et al., 2018)Knee Data:fastMRI: A Publicly Available Raw k-Space and DICOM Dataset of Knee Images for Accelerated MR Image Reconstruction Using Machine Learning ({F. Knoll*, J. Zbontar*} et al., 2020)Brain Dataset Properties:Supplemental MaterialofResults of the 2020 fastMRI Challenge for Machine Learning MR Image Reconstruction ({M. Muckley*, B. Riemenschneider*} et al., 2021)Prostate Data:FastMRI Prostate: A Publicly Available, Biparametric MRI Dataset to Advance Machine Learning for Prostate Cancer Imaging (Tibrewala et al., 2023)Code RepositoryFor code documentation, most functions and classes have accompanying docstrings
that you can access via thehelpfunction in IPython. For example:fromfastmri.dataimportSliceDatasethelp(SliceDataset)Dependencies and InstallationNote:Contributions to the code are continuously tested via GitHub actions.
If you encounter an issue, the best first thing to do is to try to match thetestsenvironment insetup.cfg, e.g.,pip install --editable ".[tests]"when installing from source.Note:As documented inIssue 215,
there is currently a memory leak when usingh5pyinstalled frompipand
converting to atorch.Tensor. To avoid the leak, you need to useh5pywith
a version of HDF5 before 1.12.1. As of February 16, 2022, thecondaversion
ofh5py3.6.0 used HDF5 1.10.6, which avoids the leak.First install PyTorch according to the directions at thePyTorch Websitefor your operating system
and CUDA setup. Then, runpipinstallfastmripipwill handle all package dependencies. After this you should be able to
run most of the code in the repository.Installing Directly from SourceIf you want to install directly from the GitHub source, clone the repository,
navigate to thefastmriroot directory and runpipinstall-e.Package Structure & UsageThe repository is centered around thefastmrimodule. The following breaks
down the basic structure:fastmri: Contains a number of basic tools for complex number math, coil
combinations, etc.fastmri.data: Contains data utility functions from originaldatafolder
that can be used to create sampling masks and submission files.fastmri.models: Contains reconstruction models, such as the U-Net and
VarNet.fastmri.pl_modules: PyTorch Lightning modules for data loading, training,
and logging.Examples and ReproducibilityThefastmri_examplesandbanding_removalfolders include code for
reproducibility. The baseline models were used in thearXiv paper.A brief summary of implementions based on papers with links to code follows.
For completeness we also mention work on active acquisition, which is hosted
in another repository.Baseline ModelsZero-filled examples for saving images for leaderboard submissionESPIRiT—an eigenvalue approach to autocalibrating parallel MRI: where SENSE meets GRAPPA (M. Uecker et al., 2013)U-Net: Convolutional networks for biomedical image segmentation (O. Ronneberger et al., 2015)Sampling, Reconstruction and Artifact CorrectionOffset Sampling Improves Deep Learning based Accelerated MRI Reconstructions by Exploiting Symmetry (A. Defazio, 2019)End-to-End Variational Networks for Accelerated MRI Reconstruction ({A. Sriram*, J. Zbontar*} et al., 2020)MRI Banding Removal via Adversarial Training (A. Defazio, et al., 2020)Deep Learning Reconstruction Enables Prospectively Accelerated Clinical Knee MRI (P. Johnson et al., 2023)Active Acquisition(external repository)Reducing uncertainty in undersampled MRI reconstruction with active acquisition (Z. Zhang et al., 2019)(external repository)Active MR k-space Sampling with Reinforcement Learning (L. Pineda et al., 2020)On learning adaptive acquisition policies for undersampled multi-coil MRI reconstruction (T. Bakker et al., 2022)Prostate Data(external respository)FastMRI Prostate: A Publicly Available, Biparametric MRI Dataset to Advance Machine Learning for Prostate Cancer Imaging (Tibrewala et al., 2023)TestingRunpytest tests. By default integration tests that use the fastMRI data are
skipped. If you would like to run these tests, setSKIP_INTEGRATIONStoFalsein theconftest.Training a modelThedata READMEhas a bare-bones example for how to
load data and incorporate data transforms. Thisjupyter notebookcontains a simple tutorial
explaining how to get started working with the data.Please look atthis U-Net demo scriptfor an
example of how to train a model using the PyTorch Lightning framework.Submitting to the LeaderboardNOTICE:As documented inDiscussion 293,
the fastmri.org domain was transferred from Meta ownership to NYU ownership on
2023-04-17, and NYU has not yet rebuilt the site. Until the site and
leaderbaords are rebuilt by NYU, leaderboards will be unavailable. Mitigations
are presented inDiscussion 293.LicensefastMRI is MIT licensed, as found in theLICENSE file.CiteIf you use the fastMRI data or code in your project, please cite the arXiv
paper:@misc{zbontar2018fastMRI,title={{fastMRI}: An Open Dataset and Benchmarks for Accelerated {MRI}},author={Jure Zbontar and Florian Knoll and Anuroop Sriram and Tullie Murrell and Zhengnan Huang and Matthew J. Muckley and Aaron Defazio and Ruben Stern and Patricia Johnson and Mary Bruno and Marc Parente and Krzysztof J. Geras and Joe Katsnelson and Hersh Chandarana and Zizhao Zhang and Michal Drozdzal and Adriana Romero and Michael Rabbat and Pascal Vincent and Nafissa Yakubova and James Pinkerton and Duo Wang and Erich Owens and C. Lawrence Zitnick and Michael P. Recht and Daniel K. Sodickson and Yvonne W. Lui},journal={ArXiv e-prints},archivePrefix="arXiv",eprint={1811.08839},year={2018}}If you use the fastMRI prostate data or code in your project, please cite that
paper:@misc{tibrewala2023fastmri,title={{FastMRI Prostate}: A Publicly Available, Biparametric {MRI} Dataset to Advance Machine Learning for Prostate Cancer Imaging},author={Tibrewala, Radhika and Dutt, Tarun and Tong, Angela and Ginocchio, Luke and Keerthivasan, Mahesh B and Baete, Steven H and Chopra, Sumit and Lui, Yvonne W and Sodickson, Daniel K and Chandarana, Hersh and Johnson, Patricia M},journal={ArXiv e-prints},archivePrefix="arXiv",eprint={2304.09254},year={2023}}List of PapersThe following lists titles of papers from the fastMRI project. The
corresponding abstracts, as well as links to preprints and code can be foundhere.Zbontar, J.*, Knoll, F.*, Sriram, A.*, Murrell, T., Huang, Z., Muckley, M. J., ... & Lui, Y. W. (2018).fastMRI: An Open Dataset and Benchmarks for Accelerated MRI.arXiv preprint arXiv:1811.08839.Zhang, Z., Romero, A., Muckley, M. J., Vincent, P., Yang, L., & Drozdzal, M. (2019).Reducing uncertainty in undersampled MRI reconstruction with active acquisition. InCVPR, pages 2049-2058.Defazio, A. (2019).Offset Sampling Improves Deep Learning based Accelerated MRI Reconstructions by Exploiting Symmetry.arXiv preprint, arXiv:1912.01101.Knoll, F.*, Zbontar, J.*, Sriram, A., Muckley, M. J., Bruno, M., Defazio, A., ... & Lui, Y. W. (2020).fastMRI: A Publicly Available Raw k-Space and DICOM Dataset of Knee Images for Accelerated MR Image Reconstruction Using Machine Learning.Radiology: Artificial Intelligence, 2(1), page e190007.Knoll, F.*, Murrell, T.*, Sriram, A.*, Yakubova, N., Zbontar, J., Rabbat, M., ... & Recht, M. P. (2020).Advancing machine learning for MR image reconstruction with an open competition: Overview of the 2019 fastMRI challenge.Magnetic Resonance in Medicine, 84(6), pages 3054-3070.Sriram, A., Zbontar, J., Murrell, T., Zitnick, C. L., Defazio, A., & Sodickson, D. K. (2020).GrappaNet: Combining parallel imaging with deep learning for multi-coil MRI reconstruction. InCVPR, pages 14315-14322.Recht, M. P., Zbontar, J., Sodickson, D. K., Knoll, F., Yakubova, N., Sriram, A., ... & Zitnick, C. L. (2020).Using Deep Learning to Accelerate Knee MRI at 3T: Results of an Interchangeability Study.American Journal of Roentgenology, 215(6), pages 1421-1429.Pineda, L., Basu, S., Romero, A., Calandra, R., & Drozdzal, M. (2020).Active MR k-space Sampling with Reinforcement Learning. InMICCAI, pages 23-33.Sriram, A.*, Zbontar, J.*, Murrell, T., Defazio, A., Zitnick, C. L., Yakubova, N., ... & Johnson, P. (2020).End-to-End Variational Networks for Accelerated MRI Reconstruction. InMICCAI, pages 64-73.Defazio, A., Murrell, T., & Recht, M. P. (2020).MRI Banding Removal via Adversarial Training. InAdvances in Neural Information Processing Systems, 33, pages 7660-7670.Muckley, M. J.*, Riemenschneider, B.*, Radmanesh, A., Kim, S., Jeong, G., Ko, J., ... & Knoll, F. (2021).Results of the 2020 fastMRI Challenge for Machine Learning MR Image Reconstruction.IEEE Transactions on Medical Imaging, 40(9), pages 2306-2317.Johnson, P. M., Jeong, G., Hammernik, K., Schlemper, J., Qin, C., Duan, J., ..., & Knoll, F. (2021).Evaluation of the Robustness of Learned MR Image Reconstruction to Systematic Deviations Between Training and Test Data for the Models from the fastMRI Challenge. InMICCAI MLMIR Workshop, pages 25–34,Bakker, T., Muckley, M.J., Romero-Soriano, A., Drozdzal, M. & Pineda, L. (2022).On learning adaptive acquisition policies for undersampled multi-coil MRI reconstruction. InMIDL, pages 63-85.Radmanesh, A.*, Muckley, M. J.*, Murrell, T., Lindsey, E., Sriram, A., Knoll, F., ... & Lui, Y. W. (2022).Exploring the Acceleration Limits of Deep Learning VarNet-based Two-dimensional Brain MRI.Radiology: Artificial Intelligence, 4(6), page e210313.Johnson, P.M., Lin, D.J., Zbontar, J., Zitnick, C.L., Sriram, A., Muckley, M., Babb, J.S., Kline, M., Ciavarra, G., Alaia, E., ..., & Knoll, F. (2023).Deep Learning Reconstruction Enables Prospectively Accelerated Clinical Knee MRI.Radiology, 307(2), page e220425.Tibrewala, R., Dutt, T., Tong, A., Ginocchio, L., Keerthivasan, M.B., Baete, S.H., Lui, Y.W., Sodickson, D.K., Chandarana, H., Johnson, P.M. (2023).FastMRI Prostate: A Publicly Available, Biparametric MRI Dataset to Advance Machine Learning for Prostate Cancer Imaging.arXiv preprint, arXiv:2034.09254.