Create README.md

README.md

@@ -0,0 +1,137 @@
+---
+language:
+- en
+license: apache-2.0
+library_name: atommic
+datasets:
+- AHEAD
+thumbnail: null
+tags:
+- quantitative-mri-mapping
+- qVarNet
+- ATOMMIC
+- pytorch
+model-index:
+- name: QMRI_qVarNet_AHEAD_gaussian2d_12x
+  results: []
+
+---
+
+
+## Model Overview
+
+quantitative Variational Network (qVarNet) for 12x accelerated quantitative MRI mapping of R2*, S0, B0, phi maps on the AHEAD 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/qMRI/AHEAD/conf).
+
+
+### Automatically instantiate the model
+
+```base
+pretrained: true
+checkpoint: https://huggingface.co/wdika/QMRI_qVarNet_AHEAD_gaussian2d_12x/blob/main/QMRI_qVarNet_AHEAD_gaussian2d_12x.atommic
+mode: test
+```
+
+### Usage
+
+You need to download the AHEAD dataset to effectively use this model. Check the [AHEAD](https://github.com/wdika/atommic/blob/main/projects/qMRI/AHEAD/README.md) page for more information.
+
+
+## Model Architecture
+```base
+model:
+  model_name: qVN
+  use_reconstruction_module: false
+  quantitative_module_num_cascades: 8
+  quantitative_module_channels: 18
+  quantitative_module_pooling_layers: 4
+  quantitative_module_in_channels: 8
+  quantitative_module_out_channels: 8
+  quantitative_module_padding_size: 11
+  quantitative_module_normalize: true
+  quantitative_module_no_dc: false
+  quantitative_module_signal_forward_model_sequence: MEGRE
+  quantitative_module_dimensionality: 2
+  quantitative_maps_scaling_factor: 1e-3
+  quantitative_maps_regularization_factors:
+    - 150.0
+    - 150.0
+    - 1000.0
+    - 150.0
+  quantitative_loss:
+    ssim: 1.0
+  kspace_quantitative_loss: false
+  total_quantitative_loss_weight: 1.0  # balance between reconstruction and quantitative loss
+  quantitative_parameters_regularization_factors:
+    - R2star: 1.0
+    - S0: 1.0
+    - B0: 1.0
+    - phi: 1.0
+```
+
+## Training
+```base
+  optim:
+    name: adam
+    lr: 1e-4
+    betas:
+      - 0.9
+      - 0.98
+    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/qMRI/AHEAD/conf/targets) configuration files.
+
+Evaluation can be performed using the [evaluation](https://github.com/wdika/atommic/blob/main/tools/evaluation/qmapping.py) script for the qmri task, with --evaluation_type per_slice.
+
+Results
+-------
+
+Evaluation against R2*, S0, B0, phi targets
+-------------------------------------------
+12x: MSE = 0.005571 +/- 0.02725 NMSE = 0.192 +/- 0.3344 PSNR = 24.36 +/- 7.791 SSIM = 0.7838 +/- 0.2059
+
+
+## Limitations
+
+This model was trained on very few subjects on the AHEAD dataset. It is not guaranteed to generalize to other datasets.
+
+
+## References
+
+[1] [ATOMMIC](https://github.com/wdika/atommic)
+
+[2] Alkemade A, Mulder MJ, Groot JM, et al. The Amsterdam Ultra-high field adult lifespan database (AHEAD): A freely available multimodal 7 Tesla submillimeter magnetic resonance imaging database. NeuroImage 2020;221.