Create README.md

README.md

@@ -0,0 +1,157 @@
+---
+language:
+- en
+license: apache-2.0
+library_name: atommic
+datasets:
+- fastMRIBrainsMulticoil
+thumbnail: null
+tags:
+- image-reconstruction
+- CIRIM
+- ATOMMIC
+- pytorch
+model-index:
+- name: REC_CIRIM_fastMRIBrainsMulticoil_equispaced_4x_8x_GDCC_1_coil_NNEstimationCSM
+  results: []
+
+---
+
+
+## Model Overview
+
+Cascades of Independently Recurrent Inference Machines (CIRIM) for 4x & 8x accelerated MRI Reconstruction on the fastMRIBrainsMulticoil dataset.
+
+
+## ATOMMIC: Training
+
+To train, fine-tune, or test the model you will need to install [ATOMMIC](https://github.com/wdika/atommic). We recommend you install it after you've installed latest Pytorch version.
+```
+pip install atommic['all']
+```
+
+## How to Use this Model
+
+The model is available for use in ATOMMIC, and can be used as a pre-trained checkpoint for inference or for fine-tuning on another dataset.
+
+Corresponding configuration YAML files can be found [here](https://github.com/wdika/atommic/tree/main/projects/REC/fastMRIBrainsMulticoil/conf).
+
+### Automatically instantiate the model
+
+```base
+pretrained: true
+checkpoint: https://huggingface.co/wdika/REC_CIRIM_fastMRIBrainsMulticoil_equispaced_4x_8x_GDCC_1_coil_NNEstimationCSM/blob/main/REC_CIRIM_fastMRIBrainsMulticoil_equispaced_4x_8x_GDCC_1_coil_NNEstimationCSM.atommic
+mode: test
+```
+
+### Usage
+
+You need to download the fastMRI Brains dataset to effectively use this model. Check the [fastMRIBrainsMulticoil](https://github.com/wdika/atommic/blob/main/projects/REC/fastMRIBrainsMulticoil/README.md) page for more information.
+
+
+## Model Architecture
+```base
+model:
+  model_name: CIRIM
+  recurrent_layer: IndRNN
+  conv_filters:
+    - 64
+    - 64
+    - 2
+  conv_kernels:
+    - 5
+    - 3
+    - 3
+  conv_dilations:
+    - 1
+    - 2
+    - 1
+  conv_bias:
+    - true
+    - true
+    - false
+  recurrent_filters:
+    - 64
+    - 64
+    - 0
+  recurrent_kernels:
+    - 1
+    - 1
+    - 0
+  recurrent_dilations:
+    - 1
+    - 1
+    - 0
+  recurrent_bias:
+    - true
+    - true
+    - false
+  depth: 2
+  time_steps: 8
+  conv_dim: 2
+  num_cascades: 5
+  no_dc: true
+  keep_prediction: true
+  accumulate_predictions: true
+  dimensionality: 2
+  reconstruction_loss:
+    l1: 0.1
+    ssim: 0.9
+  estimate_coil_sensitivity_maps_with_nn: true
+```
+
+## Training
+```base
+  optim:
+    name: adam
+    lr: 1e-4
+    betas:
+      - 0.9
+      - 0.999
+    weight_decay: 0.0
+    sched:
+        name: InverseSquareRootAnnealing
+        min_lr: 0.0
+        last_epoch: -1
+        warmup_ratio: 0.1
+
+trainer:
+  strategy: ddp_find_unused_parameters_false
+  accelerator: gpu
+  devices: 1
+  num_nodes: 1
+  max_epochs: 20
+  precision: 16-mixed
+  enable_checkpointing: false
+  logger: false
+  log_every_n_steps: 50
+  check_val_every_n_epoch: -1
+  max_steps: -1
+```
+
+## Performance
+
+To compute the targets using the raw k-space and the chosen coil combination method, accompanied with the chosen coil sensitivity maps estimation method, you can use [targets](https://github.com/wdika/atommic/tree/main/projects/REC/fastMRIBrainsMulticoil/conf/targets) configuration files.
+
+Evaluation can be performed using the [evaluation](https://github.com/wdika/atommic/blob/main/tools/evaluation/reconstruction.py) script for the reconstruction task, with --evaluation_type per_slice.
+
+Results
+-------
+
+Evaluation against RSS targets
+------------------------------
+4x: MSE = 0.0006283 +/- 0.002808 NMSE = 0.01679 +/- 0.05832 PSNR = 33.83 +/- 6.113 SSIM = 0.8916 +/- 0.1844
+
+8x: MSE = 0.00126 +/- 0.003477 NMSE = 0.0328 +/- 0.07764 PSNR = 30.23 +/- 5.665 SSIM = 0.8464 +/- 0.2017
+
+
+## Limitations
+
+This model was trained on the fastMRIBrainsMulticoil batch0 dataset using a UNet coil sensitivity maps estimation and Geometric Decomposition Coil-Compressions to 1-coil, and might differ from the results reported on the challenge leaderboard.
+
+
+## References
+
+[1] [ATOMMIC](https://github.com/wdika/atommic)
+
+[2] Muckley MJ, Riemenschneider B, Radmanesh A, Kim S, Jeong G, Ko J, Jun Y, Shin H, Hwang D, Mostapha M, Arberet S, Nickel D, Ramzi Z, Ciuciu P, Starck JL, Teuwen J, Karkalousos D, Zhang C, Sriram A, Huang Z, Yakubova N, Lui YW, Knoll F. Results of the 2020 fastMRI Challenge for Machine Learning MR Image Reconstruction. IEEE Trans Med Imaging. 2021 Sep;40(9):2306-2317. doi: 10.1109/TMI.2021.3075856. Epub 2021 Aug 31. PMID: 33929957; PMCID: PMC8428775.