diff --git a/projects/CMRxRecon/README.rst b/projects/CMRxRecon/README.rst new file mode 100644 index 00000000..84cd06d0 --- /dev/null +++ b/projects/CMRxRecon/README.rst @@ -0,0 +1,151 @@ +Deep Cardiac MRI Reconstruction with ADMM (CMRxRecon Challenge 2023) +===================================================================== + +This project contains necessary configuration files to reproduce experiments of 2nd top-ranking approach +to both tasks of CMRxRecon Challenge 2023 as presented in `Deep Cardiac MRI Reconstruction with ADMM +`_. +This will also help you set up the training and inference data directories. + +Setting up data directory +------------------------- + +This project aims to help you set up directories for training and validation +data using the specified directory structures necessary to run with DIRECT. +You will need to run this process twice: once for "Cine" data and once for "Mapping" data. + +Prerequisites +~~~~~~~~~~~~~ + +Before you begin, make sure you have downloaded the CMRxRecon Challenge +data. Check `https://cmrxrecon.github.io/Challenge.html`_ for more information. + +Assumed Base Path Structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The script assumes that CMRxRecon data is organized according to the following directory structure: + +.. code-block:: plaintext + + base_path + ├── MultiCoil + │ ├── Cine_or_Mapping + │ │ ├── TrainingSet + │ │ │ ├── FullSample + │ │ │ ├── AccFactor04 + │ │ │ ├── AccFactor08 + │ │ │ └── AccFactor10 + │ │ ├── ValidationSet + │ │ │ ├── AccFactor04 + │ │ │ ├── AccFactor08 + │ │ │ └── AccFactor10 + │ │ ├── TestSet + │ │ │ ├── AccFactor04 + │ │ │ ├── AccFactor08 + │ │ │ └── AccFactor10 + +Symlinks Path Structure +~~~~~~~~~~~~~~~~~~~~~~~ + +The script will create symbolic links (symlinks) in a target directory with the following structure: + +.. code-block:: plaintext + + target_path + target_path + ├── MultiCoil + │ ├── training + │ │ ├── P001_T1map.h5 + │ │ ├── with_masks_P001_T1map.h5 + │ │ ├── P001_cine_sax.h5 + │ │ ├── with_masks_P001_cine_sax.h5 + │ ├── Cine_or_Mapping + │ │ ├── validation + │ │ │ ├── AccFactor04 + │ │ │ | ├── P001_<..>.h5 + │ │ │ ├── AccFactor08 + │ │ │ | ├── P001_<..>.h5 + │ │ │ └── AccFactor10 + │ │ │ | ├── P001_<..>.h5 + │ │ ├── test + │ │ │ ├── AccFactor04 + │ │ │ | ├── P001_<..>.h5 + │ │ │ ├── AccFactor08 + │ │ │ | ├── P001_<..>.h5 + │ │ │ └── AccFactor10 + │ │ │ | ├── P001_<..>.h5 + +Create Symbolic Directories +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following creates files of fully sampled data with the respective masks, and creates +symbolic paths of data in single directories to be used with DIRECT. + +.. code-block:: bash + + python3 create_data_dir.py --base_path path_to_base_data --target_path path_to_target_directory --data_type Cine + python3 create_data_dir.py --base_path path_to_base_data --target_path path_to_target_directory --data_type Mapping + +Experiments +----------- + +Configuration Files +~~~~~~~~~~~~~~~~~~~ + +We provide configuration files for DIRECT for experiments presented in `Deep Cardiac MRI Reconstruction with ADMM +`_ in the `configs folder <./configs>`_. + +Training +~~~~~~~~ + +In `direct/` run the following command to begin training on the training data. + +.. code-block:: bash + + direct train \ + --training-root /MultiCoil/training/ \ + --validation-root /MultiCoil/training/ \ + --cfg projects/CMRxRecon/configs/base_.yaml \ + --num-gpus \ + --num-workers + +Note that for validation a subset of the training data is used since full validation data have not been released. + +Inference +~~~~~~~~~ + +Note that inference is performed for a single dataset, therefore a single acceleration factor. +For example, the following entry for `inference` will perform predictions for acceleration factor of 4x +on validation data. Change `kspace_key: kspace_sub04` to `kspace_key: kspace_sub08` for 8x and +`kspace_key: kspace_sub10` for 10x. + +.. code-block:: yaml + + inference: + batch_size: 8 + dataset: + name: CMRxRecon + kspace_key: kspace_sub04 + compute_mask: true + transforms: + cropping: + crop: null + sensitivity_map_estimation: + estimate_sensitivity_maps: true + normalization: + scaling_key: masked_kspace + scale_percentile: 0.99 + masking: null + text_description: inference-4x + crop: null + +In `direct/` run the following command to perform inference, for instance on 4x: + +.. code-block:: bash + + direct predict + --checkpoint \ + --cfg projects/CMRxRecon/configs/base_.yaml \ + --data-root /MultiCoil//validation/AccFactor<04_or_08_or_10> \ + --num-gpus \ + --num-workers \ + [--other-flags] diff --git a/projects/CMRxRecon/tools/create_data_dir.py b/projects/CMRxRecon/tools/create_data_dir.py index cb39a4b9..08df9ea6 100644 --- a/projects/CMRxRecon/tools/create_data_dir.py +++ b/projects/CMRxRecon/tools/create_data_dir.py @@ -43,10 +43,12 @@ SYMLINKS_PATH_STRUCTURE = """ target_path ├── MultiCoil + │ ├── training + │ │ ├── P001_T1map.h5 + │ │ ├── with_masks_P001_T1map.h5 + │ │ ├── P001_cine_sax.h5 + │ │ ├── with_masks_P001_cine_sax.h5 │ ├── Cine_or_Mapping - │ │ ├── training - │ │ │ ├── P001_<..>.h5 - │ │ │ ├── with_masks_P001_<..>.h5 │ │ ├── validation │ │ │ ├── AccFactor04 │ │ │ | ├── P001_<..>.h5 @@ -111,7 +113,7 @@ full_sample_path = training_set_path / "FullSample" full_sample_with_masks_path = training_set_path / "FullSampleWithMasks" -training_symbolic_path = args.target_path / "MultiCoil" / args.data_type / "training" +training_symbolic_path = args.target_path / "MultiCoil" / "training" # Check if the required directories exist if not data_path.exists():