Detect and lateralize HS on MRI data

The AID-HS pipeline offers a unique command line to detect and lateralize HS from T1w scan.

If you wish to use the harmonisation feature of the AID-HS pipeline, you will need to first have computed the harmonisation parameters for the scanner used to acquire the data and used the harmonisation code into the main pipeline command as described bellow. Please refer to our guidelines to harmonise a new scanner.

Here is the video tutorial about how to run the AID-HS pipeline: Tutorial on how to run the AID-HS pipeline.

Running

Ensure you have installed the AID-HS pipeline with docker container
Ensure you have organised your data into BIDS format before running this pipeline
Ensure you have computed the harmonisation parameters if you want to use the harmonisation parameters

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
Then run:

Docker Linux

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>

Docker Windows/Mac

docker compose run aidhs python scripts/new_patient_pipeline/new_patient_pipeline.py -id <subject_id> -demos <demographic_file>

Singularity

First you will need to mount the aidhs_data_folder to the /data folder of the container by running:

export APPTAINER_BINDPATH=<path_to_aidhs_data_folder>:/data

And then run:

singularity exec aidhs.sif /bin/bash -c "cd /app && python scripts/new_patient_pipeline/new_patient_pipeline.py -id <subject_id> -demos <demographic_file>"

Native

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
Then run:

Docker Linux

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>

Docker Windows/Mac

docker compose run aidhs python scripts/new_patient_pipeline/new_patient_pipeline.py -id <subject_id> -demos <demographic_file> -harmo_code <harmonisation_code>

Singularity

First you will need to mount the aidhs_data_folder to the /data folder of the container by running:

export APPTAINER_BINDPATH=<path_to_aidhs_data_folder>:/data

And then run:

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>"

Native

python scripts/new_patient_pipeline/new_patient_pipeline.py -id <subject_id> -demos <demographic_file> -harmo_code <harmonisation_code>

Tune the command

You can tune the AID-HS pipeline command using additional variables and flags as detailed bellow:

Mandatory variables	Comment
either `-id <subject_id>`	if you want to run the pipeline on 1 single subject.
or `-ids <subjects_list>`	if you want to run the pipeline on more than 1 subject, you can pass the name of a text file containing the list of subjects. An example ‘subjects_list.txt’ is provided in the <aidhs_data_folder>.
`-demos <demographic_file>`	The name of the csv file containing the demographic information as detailled in the guidelines and provided demographic information. An example ‘demographics_file.csv’ is provided in the <aidhs_data_folder>.
Optional variables
`-harmo_code <harmo_code>`	provide the harmonisation code if you want to harmonise your data before prediction. This requires to have computed the harmonisation parameters beforehand. The harmonisation code should start with H, e.g. H1.
`--parallelise`	use this flag to speed up the segmentation by running HippUnfold on multiple subjects in parallel.
`--skip_segmentation`	use this flag to skips the hippocampal segmentation and features extraction. Usefull if you already have these outputs and you just want to run the preprocessing and the predictions (e.g: after harmonisation)
More advanced variables
`--debug_mode`	use this flag to print additional information to debug the code (e.g print the commands, print errors)

NOTES:

Outputs of the pipeline (AID-HS reports) are stored in the folder output/predictions_reports/<subject_id>. See guidelines on how to interepret the results for more details.

Interpretation of results

Refer to our guidelines for details on how to read and interprete the AID-HS pipeline results