Create README.md

README.md

@@ -0,0 +1,136 @@
+---
+language:
+- en
+license: apache-2.0
+library_name: atommic
+datasets:
+- CC359
+thumbnail: null
+tags:
+- image-reconstruction
+- RVN
+- ATOMMIC
+- pytorch
+model-index:
+- name: REC_RVN_CC359_12_channel_poisson2d_5x_10x_NNEstimationCSM
+  results: []
+
+---
+
+
+## Model Overview
+
+Recurrent Variational Network (RVN) for 5x & 10x accelerated MRI Reconstruction on the CC359 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/CC359/conf).
+
+### Automatically instantiate the model
+
+```base
+pretrained: true
+checkpoint: https://huggingface.co/wdika/REC_RVN_CC359_12_channel_poisson2d_5x_10x_NNEstimationCSM/blob/main/REC_RVN_CC359_12_channel_poisson2d_5x_10x_NNEstimationCSM.atommic
+mode: test
+```
+
+### Usage
+
+You need to download the CC359 dataset to effectively use this model. Check the [CC359](https://github.com/wdika/atommic/blob/main/projects/REC/CC359/README.md) page for more information.
+
+
+## Model Architecture
+```base
+model:
+  model_name: RVN
+  in_channels: 2
+  recurrent_hidden_channels: 64
+  recurrent_num_layers: 4
+  num_steps: 8
+  no_parameter_sharing: true
+  learned_initializer: true
+  initializer_initialization: "sense"
+  initializer_channels:
+    - 32
+    - 32
+    - 64
+    - 64
+  initializer_dilations:
+    - 1
+    - 1
+    - 2
+    - 4
+  initializer_multiscale: 1
+  accumulate_predictions: false
+  dimensionality: 2
+  reconstruction_loss:
+    l1: 0.1
+    ssim: 0.9
+  estimate_coil_sensitivity_maps_with_nn: true
+```
+
+## Training
+```base
+  optim:
+    name: adamw
+    lr: 1e-4
+    betas:
+      - 0.9
+      - 0.999
+    weight_decay: 0.0
+    sched:
+        name: CosineAnnealing
+        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/CC359/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
+------------------------------
+5x: MSE = 0.001627 +/- 0.001304 NMSE = 0.02511 +/- 0.02188 PSNR = 28.14 +/- 3.531 SSIM = 0.8449 +/- 0.06722
+
+10x: MSE = 0.002677 +/- 0.00225 NMSE = 0.0416 +/- 0.03916 PSNR = 26.03 +/- 3.767 SSIM = 0.787 +/- 0.09309
+
+
+## Limitations
+
+This model was trained on the CC359 using a UNet coil sensitivity maps estimation and might differ from the results reported on the challenge leaderboard.
+
+
+## References
+
+[1] [ATOMMIC](https://github.com/wdika/atommic)
+
+[2] Beauferris, Y., Teuwen, J., Karkalousos, D., Moriakov, N., Caan, M., Yiasemis, G., Rodrigues, L., Lopes, A., Pedrini, H., Rittner, L., Dannecker, M., Studenyak, V., Gröger, F., Vyas, D., Faghih-Roohi, S., Kumar Jethi, A., Chandra Raju, J., Sivaprakasam, M., Lasby, M., … Souza, R. (2022). Multi-Coil MRI Reconstruction Challenge—Assessing Brain MRI Reconstruction Models and Their Generalizability to Varying Coil Configurations. Frontiers in Neuroscience, 16. https://doi.org/10.3389/fnins.2022.919186