add guidelines singularity to prediction

README.md

@@ -21,7 +21,7 @@ The AID-HS software is intended for research purposes only and has not been revi
 ### Installations available 
 You can install and use the AID-HS pipeline with :
 - [**docker container**](https://aid-hs.readthedocs.io/en/latest/install_docker.html) recommended for easy installation of the pipeline as all the prerequisite packages are already embeded into the container. Note: Dockers do not work on High Performance Computing (HCP) systems.
-- [**singularity container]**(https://aid-hs.readthedocs.io/en/latest/install_singularity.html) - to run a container on High Performance Computing (HCP) systems. 
+- [**singularity container**](https://aid-hs.readthedocs.io/en/latest/install_singularity.html) - to run a container on High Performance Computing (HCP) systems. 
 - [**native installation**](https://aid-hs.readthedocs.io/en/latest/install_native.html): Not supported 
 
 ### Running the pipeline 

docs/harmonisation.md

@@ -3,15 +3,16 @@
 ## Information about the harmonisation
 The AID-HS pipeline enables the harmonisation of your patient's features before prediction, if you are providing harmonisation parameters.
 
-Harmonisation of your patient data is not mandatory but recommended, to remove any bias induced by the scanner and sequence used, and be able to interprete the normative curves. For more details on the AID-HS performances with and without harmonisation please refers to our (paper)[]
+Harmonisation of your patient data is not mandatory but recommended, to remove any bias induced by the scanner and sequence used, and be able to interprete the normative curves. For more details on the AID-HS performances with and without harmonisation please refers to our (paper)[https://onlinelibrary.wiley.com/doi/10.1002/ana.27089?af=R]
 
 ## Compute the harmonisation paramaters 
 
 The harmonisation parameters are computed using [Distributed Combat](https://doi.org/10.1016/j.neuroimage.2021.118822).
 To get these parameters you will need a cohort of subjects acquired from the same scanner and under the same protocol (sequence, parameters, ...).
-Subjects can be controls and/or patients, but we advise to use ***at least 20 subjects*** to enable an accurate harmonisation, and to not use HS patients for the harmonisation (see (paper)[]). 
+Subjects can be controls and/or patients, but we advise to use ***at least 20 subjects*** to enable an accurate harmonisation, and to not use HS patients for the harmonisation. 
 Try to ensure the data are high quality (i.e no blurring, no artefacts, no cavities in the brain).
 Demographic information (e.g age and sex) will be required for this process, follow the [guidelines](https://aid-hs.readthedocs.io/en/latest/prepare_data.html) 
+
 WARNING: zero variance in the demographics information (e.g. having the same age for all subjects) will lead to Combat failures or errors. 
 
 Once you have done the process once, you can follow the [general guidelines to predict on a new patient](https://aid-hs.readthedocs.io/en/latest/run_prediction_pipeline.html) 
@@ -27,9 +28,27 @@ Once you have done the process once, you can follow the [general guidelines to p
 
 Open a terminal and `cd` to where you extracted the release zip.
 
+::::{tab-set}
+:::{tab-item} Docker
+:sync: docker
+
 ```bash
 DOCKER_USER="$(id -u):$(id -g)" docker compose run aidhs python scripts/new_patient_pipeline/new_patient_pipeline.py -harmo_code <harmo_code> -ids <subjects_list> -demos <demographic_file> --harmo_only
 ```
+:::
+:::{tab-item} Singularity
+:sync: Singularity
+
+First you will need to mount the `aidhs_data_folder` to the `/data` folder of the container by running:
+```bash
+export APPTAINER_BINDPATH=<path_to_aidhs_data_folder>:/data
+```
+And then run:
+```bash
+singularity exec aidhs.sif /bin/bash -c "cd /app && python scripts/new_patient_pipeline/new_patient_pipeline.py -harmo_code <harmo_code> -ids <subjects_list> -demos <demographic_file> --harmo_only"
+```
+:::
+::::
 
 This calls the AID-HS pipeline command. You can tune this command using the variables and flag describes further below. 
 

docs/prepare_data.md

@@ -6,8 +6,8 @@ If you are preparing the data for the harmonisation step, you will also need to
 
 You will need to prepare your data following a specific architecture:
 If not already done, please :
-- 1. Download the <aidhs_data_folder> at https://figshare.com/s/16011ee4d6b5723b14b6
-- 2. Unzip the folder where you want to store the <aidhs_data_folder?
+- 1. Download the <aidhs_data_folder> from [Figshare](https://figshare.com/s/16011ee4d6b5723b14b6). 
+- 2. Unzip the folder where you want to store the <aidhs_data_folder>
 - 3. Follow the guidelines below to prepare your MRI data and demographic information
 
 #### MRI data
@@ -76,9 +76,11 @@ AID-HS provide individualised results, which are adapted for the age and sex of
 - `Harmo code`: the harmonisation code associated with this subject scan or "noHarmo" if you do not want to use the harmonisation
 - `Group`: patient, as you want to predict all subjects will be considered as patients
 - `Age at preoperative`: The age of the subject at the time of the preoperative T1 scan (in years)
-- `Sex`: 1 if male, 0 if female
+- `Sex`: "male" if male, "female" if female
 - `Scanner`: the scanner strenght associated with the MRI data ('3T' for 3 Tesla or '15T' for 1.5 Tesla)
 
+![example](https://raw.githubusercontent.com//MELDProject/AID-HS/main/docs/images/example_demographic_csv.png)
+
 Notes: 
 - please ensure the column names are unchanged and completed with the appropriate values, otherwise the pipeline will fail.
 - note that AID-HS has not been thoroughly evaluated for data from 1.5T scanners

docs/run_prediction_pipeline.md

@@ -15,21 +15,60 @@ Open a terminal and `cd` to where you extracted the release zip.
 ### Running without harmonisation
 
 Ensure "noHarmo" is provided as an harmonisation code for that subject in the `demographics_file` \
+
+::::{tab-set}
+:::{tab-item} Docker
+:sync: docker
+
 Then run:
+
 ```bash
 DOCKER_USER="$(id -u):$(id -g)" docker compose run aidhs python scripts/new_patient_pipeline/new_patient_pipeline.py -id <subject_id> -demos <demographic_file>
 ```
+:::
+:::{tab-item} Singularity
+:sync: Singularity
+
+First you will need to mount the `aidhs_data_folder` to the `/data` folder of the container by running:
+```bash
+export APPTAINER_BINDPATH=<path_to_aidhs_data_folder>:/data
+```
+And then run:
+```bash
+singularity exec aidhs.sif /bin/bash -c "cd /app && python scripts/new_patient_pipeline/new_patient_pipeline.py -id <subject_id> -demos <demographic_file>"
+```
+:::
+::::
 
 
 ### Running with harmonisation
 You will need to have computed the harmonisation parameters for that harmonisation code \
 Ensure you the same harmonisation code is provided for that subject in the `demographics_file` \
+
+::::{tab-set}
+:::{tab-item} Docker
+:sync: docker
+
 Then run: 
 
 ```bash
 DOCKER_USER="$(id -u):$(id -g)" docker compose run aidhs python scripts/new_patient_pipeline/new_patient_pipeline.py -id <subject_id> -demos <demographic_file> -harmo_code <harmonisation_code>
 ```
 
+:::
+:::{tab-item} Singularity
+:sync: Singularity
+
+First you will need to mount the `aidhs_data_folder` to the `/data` folder of the container by running:
+```bash
+export APPTAINER_BINDPATH=<path_to_aidhs_data_folder>:/data
+```
+And then run:
+```bash
+singularity exec aidhs.sif /bin/bash -c "cd /app && python scripts/new_patient_pipeline/new_patient_pipeline.py -id <subject_id> -demos <demographic_file> -harmo_code <harmonisation_code>"
+```
+:::
+::::
 
 ## Tune the command
 
@@ -53,20 +92,66 @@ NOTES:
 ## Examples of use case: 
 
 To run the whole prediction pipeline on subject 'test001' without harmonising the data:
+
+::::{tab-set}
+:::{tab-item} Docker
+:sync: docker
+
 ```bash
 DOCKER_USER="$(id -u):$(id -g)" docker compose run aidhs python scripts/new_patient_pipeline/new_patient_pipeline.py -id sub-test001
 ```
 
+:::
+:::{tab-item} Singularity
+:sync: Singularity
+
+```bash
+singularity exec aidhs.sif /bin/bash -c "cd /app && python scripts/new_patient_pipeline/new_patient_pipeline.py -id sub-test001"
+```
+:::
+::::
+
 To run the whole prediction pipeline on subject 'test001' using harmonisation code H1:
+
+::::{tab-set}
+:::{tab-item} Docker
+:sync: docker
+
 ```bash
 DOCKER_USER="$(id -u):$(id -g)" docker compose run aidhs python scripts/new_patient_pipeline/new_patient_pipeline.py -id sub-test001 -harmo_code H1
 ```
 
+:::
+:::{tab-item} Singularity
+:sync: Singularity
+
+```bash
+singularity exec aidhs.sif /bin/bash -c "cd /app && python scripts/new_patient_pipeline/new_patient_pipeline.py -id sub-test001 -harmo_code H1"
+```
+
+:::
+::::
+
 To run the whole prediction pipeline on multiples subjects with parallelisation:
+
+::::{tab-set}
+:::{tab-item} Docker
+:sync: docker
+
 ```bash
 DOCKER_USER="$(id -u):$(id -g)" docker compose run aidhs python scripts/new_patient_pipeline/new_patient_pipeline.py -ids list_subjects.txt --parallelise
 ```
 
+:::
+:::{tab-item} Singularity
+:sync: Singularity
+
+```bash
+singularity exec aidhs.sif /bin/bash -c "cd /app && python scripts/new_patient_pipeline/new_patient_pipeline.py -ids list_subjects.txt --parallelise"
+```
+
+:::
+::::
 
 ## Interpretation of results