[DOC] Refactor UKB-To-BIDS documentation page (#1284)

* First proposition for ukb conv * WIP 2 * Last changes * Changes upon suggestions * Add copy * Fix link
aramis-lab · Sep 9, 2024 · 01f9061 · 01f9061
1 parent bc3661b
commit 01f9061
Show file tree

Hide file tree

Showing 4 changed files with 81 additions and 47 deletions.
diff --git a/docs/Converters/IXItoBIDS.md b/docs/Converters/IXItoBIDS.md
@@ -1,14 +1,14 @@
 # `ixi-to-bids` – Conversion of Information eXtraction from Images (IXI) to BIDS format
 ??? quote "Dataset Description"
     The [Information eXtraction from Images](https://brain-development.org/ixi-dataset/)
-    is a project which issued a dataset of nearly 600 images from healthy subjects. The MR acquisition
-    protocol includes T1,T2, PD weighted, MRA and diffusion-weighted images.
+    is a project which issued a dataset of nearly 600 nifti images from healthy subjects.
+    The MR acquisition protocol includes T1,T2, PD weighted, MRA and diffusion-weighted images.
     Three hospitals in London were involved in data collection.
 
 ## Downloading the data
 The IXI dataset can be downloaded freely from the [IXI webpage](https://brain-development.org/ixi-dataset/).
 !!! danger "Organising data with the aim of using the converter"
-    The folders and files downloaded from the website should be left as they are (name, inner organisation...) but can be
+    The folders and files downloaded from the website should be left **as they are** (name, inner organisation...) but can be
     placed where the user wants them.
 
 ## Using the converter
@@ -24,13 +24,13 @@ DTI ; T1 ; T2 ; PD ; angiography.
 If you [installed clinica](../Installation.md#install-clinica), this converter needs no further dependencies.
 
 ### Understanding the command line
-```bash
-clinica convert ixi-to-bids DATASET_DIRECTORY BIDS_DIRECTORY CLINICAL_DATA_DIRECTORY
+```{ .bash .copy }
+clinica convert ixi-to-bids DATASET_DIRECTORY BIDS_DIRECTORY CLINICAL_DATA_DIRECTORY [OPTIONS]
 ```
 where :
 
 - `DATASET_DIRECTORY` is the path to the raw IXI dataset directory, which should contain all the IXI folders previously downloaded :
-  ```
+  ```text title="DATASET_DIRECTORY Organisation"
   DATASET_DIRECTORY
   ├── IXI-T1
   │   ├── IXI002-Guys-0828-T1.nii.gz
@@ -43,10 +43,10 @@ where :
 
 - `BIDS_DIRECTORY` is the path to the BIDS folder to be created
 - `CLINICAL_DATA_DIRECTORY` is the path to the folder where the clinical data of the IXI dataset is stored.
-```
-CLINICAL_DATA_DIRECTORY
-├── IXI.xls
-...
+```text title="CLINICAL_DATA_DIRECTORY Organisation"
+    CLINICAL_DATA_DIRECTORY
+    ├── IXI.xls
+    ...
 ```
 
 --8<-- "snippets/converters_options.md"
diff --git a/docs/Converters/UKBtoBIDS.md b/docs/Converters/UKBtoBIDS.md
@@ -1,70 +1,89 @@
 <!-- markdownlint-disable MD046 -->
 # `ukb-to-bids` – Conversion of the UK Biobank (UKB) to BIDS
 
-!!! quote "Description reproduced from the [UK Biobank webpage](https://www.ukbiobank.ac.uk/)"
+??? quote "Description reproduced from the [UK Biobank webpage](https://www.ukbiobank.ac.uk/)"
     UK Biobank is a large-scale biomedical database and research resource, containing in-depth genetic and health information from half a million UK participants. The database is regularly augmented with additional data and is globally accessible to approved researchers undertaking vital research into the most common and life-threatening diseases. It is a major contributor to the advancement of modern medicine it and has led to the discovery of several scientific advances and numerous treatments to improve human health.
 
-## Dependencies
+## Downloading the Data
 
-If you installed the core of Clinica, this converter needs the `dcm2niix` package.
+The UKB to BIDS converter assumes that the user has already got access to the data and has downloaded both imaging and clinical data locally.
 
-## Downloading UK Biobank
+!!! danger "Organising data with the aim of using the converter"
+    Be careful, the file {==clinical_data.csv==}  needs to contain the following information about the subject :
+    *sex, year of birth, age at recruitment, age at sessions*.
+    There are two columns as there are two imaging sessions.
+    The names of the columns should be kept as they are when downloaded using `ukbconv` using options `csv`.
 
-The UK Biobank to BIDS converter assumes that the user has already applied to get access to the data and that the imaging and clinical data have already been downloaded locally.
 
-The imaging data can be downloaded and extracted using [this tutorial](https://biobank.ctsu.ox.ac.uk/~bbdatan/Accessing_UKB_data_v2.3.pdf). The clinical data can be extracted using the information from [this repository](https://github.com/kenhanscombe/ukbtools).
 
-Be careful, the file `clinical_data.csv` needs to contain the following information about the subject: sex, year of birth, age at recruitment, age at sessions (there are two columns as there are two imaging sessions). The names of the columns should be kept as they are when downloaded using `ukbconv` using options `csv`.
+## Using the converter
+### Dependencies
 
-## Supported modalities
+If you [installed the core of Clinica](../Installation.md#install-clinica), this converter needs the [dcm2niix](../Third-party.md#converters) package.
 
-Please note that this converter processes the following modalities : 
-- T1W (nifti)
-- T2 Flair (nifti)
-- DWI (nifti)
-- SWI (nifti)
-- tfMRI (dicom)
-- rsfMRI (dicom)
+### Supported modalities
 
-!!! Chosen files    
-    Whenever is possible, the converter uses the rawest files found. This decision allows the user to choose the processing needed. When available the converter get the associated json.
-| Modality    | Chosen image(s) | Justification |
-| :----------:|:---------------:|:-------:|
-| T1W                     | T1.nii.gz       | Defaced and cropped so there is no neck. The rawest image would be the simply defaced one, but brain studies usually are not interested in the region of the neck. No other corrections are included. |
-| T2 Flair    | T2_FLAIR.nii.gz | Defaced and cropped so there is no neck. The reasons for choosing this image are the same as for T1. |
-| DWI         | AP/PAnii.gz     | It is the rawest images we can get. bvals and bvec are also available. |
-| rsfMRI      | rsfMRI.dcm | Since the nii.gz version doesn't always include a json and in consideration for it's usage, we convert the dicom. |
-| tfMRI       | tfMRI.dcm   | Same as rsfMRI.|
-| SWI         | SWI.nii.gz      | Combined coil version. We would get a rawer version, but `dcm2niix` has trouble handling the slices direction, so it is simpler to go with this version. In addition, SWI modality is not fully integrated to BIDS specification and some changes may be coming. A simple version is available in the current version of this converter. | 
-
+<div class="annotate" markdown>
+Please note that this converter processes the following modalities (1) :
+</div>
 
-## Using the converter
+1. Whenever possible, the converter uses the rawest files available. This decision allows the user to choose the processing they need. If possible the converter also gets the associated json.
+
+| Modality    | Chosen image | Format |                                                                                                                                                              Justification                                                                                                                                                               |
+| :----------:|:---------------:|:-------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
+| T1W         | T1.nii.gz       | nifti |                                                                  Defaced and cropped so there is no neck. The rawest image would be the simply defaced one, but brain studies usually are not interested in the region of the neck. No other corrections are included.                                                                   |
+| T2 Flair    | T2_FLAIR.nii.gz | nifti |                                                                                                                                           Defaced and cropped so there is no neck. Same as T1.                                                                                                                                           |
+| DWI         | AP/PA.nii.gz     | nifti |                                                                                                                                          Rawest existing images with available bvals and bvec.                                                                                                                                           |
+| rsfMRI      | rsfMRI.dcm | dicom |                                                                                                               The nifti doesn't always include a json and in consideration for its usage, the dicom is converted instead.                                                                                                                |
+| tfMRI       | tfMRI.dcm   | dicom |                                                                                                                                                             Same as rsfMRI.                                                                                                                                                              |
+| SWI         | SWI.nii.gz      | nifti | Combined coil version. We would get a rawer version, but `dcm2niix` has trouble handling the slices direction, so it is simpler to go with this version. In addition, SWI modality is not fully integrated to BIDS specification and some changes may be coming. A simple version is available in the current version of this converter. |
+
+
+### Understanding the command line
 
 The converter can be run with the following command line:
 
-```Text
-clinica convert ukb-to-bids [OPTIONS] DATASET_DIRECTORY CLINICAL_DATA_DIRECTORY BIDS_DIRECTORY 
+```{ .bash .copy }
+clinica convert ukb-to-bids DATASET_DIRECTORY CLINICAL_DATA_DIRECTORY BIDS_DIRECTORY [OPTIONS]
 ```
 
 where:
 
-- `DATASET_DIRECTORY` is the path to the original UK BIobank imaging directory, whose content should look like:
+<div class="grid" markdown>
 
-    ```text
+=== "Imaging data :"
+
+    - `DATASET_DIRECTORY` is the path to the
+    original UK Biobank imaging directory.
+
+    - `BIDS_DIRECTORY` is the path to the
+    output directory where the BIDS-converted
+    version of UK Biobank will be stored.
+
+
+```title="DATASET_DIRECTORY Organisation"
     DATASET_DIRECTORY
     ├── 1000223_20227_2_0.zip
     ├── 1000223_20249_2_0.zip
     ├── 1000223_20250_2_0.zip
-    ├── 1000223_20251_2_0.zip
-    ├── 1000223_20252_2_0.zip
-    ├── 1000223_20253_2_0.zip
     ├── 3338337_20251_2_0.zip
     └── 5566112_20253_2_0.zip
-    ```
+```
+
+=== "Clinical data :"
+
+    - `CLINICAL_DATA_DIRECTORY` is the path to the directory
+    containing the clinical CSV file.
+
+```title="CLINICAL_DATA_DIRECTORY Organisation"
+    CLINICAL_DATA_DIRECTORY
+    ├── clinical_data.csv
+    ├── ...
+```
+
+</div>
 
-- `CLINICAL_DATA_DIRECTORY` is the path to the directory containing the clinical CSV file.
 
-- `BIDS_DIRECTORY` is the path to the output directory where the BIDS-converted version of UK Biobank will be stored.
 
 !!! note
     In order to improve the readability, the BIDS subject ID is different from the original UK Biobank ID and is defined as follows:
@@ -76,6 +95,10 @@ where:
     !!! example
         If the original subject ID is `0001`, the final BIDS ID will be `sub-UKB0001`.
 
+
+--8<-- "snippets/converters_options.md"
+
+
 ## Citing this converter in your paper
 
 !!! cite "Example of paragraph:"

diff --git a/docs/snippets/abbreviations.md b/docs/snippets/abbreviations.md
@@ -2,12 +2,20 @@
 *[DTI] : Diffusion Tensor Imaging
 *[DWI] : Diffusion Weighted Imaging
 *[CSV] : Comma-Separated Values
+*[fMRI] : Functional MRI
 *[FWHM] : Full Width at Half Maximum
 *[GLM] : Generalized Linear Model
 *[JSON] : JavaScript Object Notation
+*[MRI] : Medical Resonance Imaging
 *[PD] : Phase Difference
 *[PET] : Positron Emission Tomography
 *[PSF] : Point Spread Function
 *[PVC] : Partial-Volume Correction
+*[rsfMRI] : Resting State fMRI
 *[SUVR] : Standardized Uptake Value Ratio
+*[SWI] : Susceptibility Weighted Imaging
+*[tfMRI] : Task fMRI
 *[TSV] : Tab-Separated Values
+*[T1W] : T1 Weighted MRI
+*[T2W] : T2 Weighted MRI
+*[UKB] : UK-Biobank
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -18,6 +18,7 @@ theme:
   name: material
   icon:
     repo: material/github
+    annotation: material/help-circle
   language: en
   palette:
     primary: light blue
@@ -56,6 +57,8 @@ markdown_extensions:
   - pymdownx.emoji
   - pymdownx.keys
   - pymdownx.superfences
+  - pymdownx.critic
+  - md_in_html
   - abbr
   - attr_list
   - pymdownx.snippets: