Docker container

The Docker container has all the prerequisites embedded into it. This makes it easier to install and compatible with most OS systems.

Notes:

tested on Linux, Windows
You will need ~20GB of space to install the container
The docker image contains Miniconda 3, HippUnfold v1.1.0, and AID-HS. The whole image is ~18GB.

Here is the video tutorial demonstrating how to do the docker installation - Docker and Singularity Installation of AID-HS Tutorial. Note that some part of the installation video are outdated for AID-HS > v1.1.0. Please follow the github guidelines for up to date instructions.

Prerequisites

Install Docker

You will need to have docker installed. You can check if docker is installed on your computer by running:

docker --version

If this command displays the docker version then it is already installed. If not, please follow the guidelines to install docker on your machine. Make sure to download the correct version for your OS system!

Enable GPUs

Enabling your computer’s GPUs for running the pipeline accelerates the HippUnfold segmentation . Follow instructions for your operating system to install.

Install the nvidia container toolkit.

AID-HS license

In order to run AID-HS you need to have a aidhs_license.txt in the aidhs folder. To get this file, please fill out the AID-HS registration form. Once submitted, your application will be automatically reviewed and the aidhs_license.txt file will be send to your email.

Installation & configuration

In order to run the docker, you’ll need to configure a couple of files

Download aidhs.zip from the latest github release and extract it.
Copy the aidhs_license.txt into the extracted folder (see above how to get the AID-HS license)
Create the aidhs_data folder, if it doesn’t exist already. This folder is where you would like to store MRI data to run the classifier
In the AID-HS folder, open and edit the compose.yml to add the path to the aidhs_data_folder. The initial compose.yml file looks like :

services:
  aidhs:
    image: meldproject/aidhs:latest
    platform: "linux/amd64"
    volumes:
      - volumes:/data
    environment: 
      - AIDHS_LICENSE=/run/secrets/aidhs_license.txt
    secrets:
      - aidhs_license.txt
    user: $DOCKER_USER
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
              count: 0

secrets:
  aidhs_license.txt:
    file: ./aidhs_license.txt

Change the line below “volumes:” to point to the aidhs_data_folder. Do not delete the “:/data” at the end.
For example, if you wanted the folder to be on a mounted drive such as “/mnt/datadrive/aidhs-data” you should change the line as showed below:

    volumes:
      - /mnt/datadrive/aidhs-data:/data

Windows

On windows, if you’re using absolute paths, use forward slashes and quotes:

    volumes:
      - "C:/Users/John/Desktop/aidhs-data:/data"

WARNING: If you do not have GPU on your computer (e.g. Mac laptop) you will need to open the compose.yml file and remove the 6th lines of the text below (everything that includes deploy up to secrets).
Your file should look like that:

services:
  aidhs:
    image: meldproject/aidhs:latest
    platform: "linux/amd64"
    volumes:
      - volumes:/data
    environment: 
      - AIDHS_LICENSE=/run/secrets/aidhs_license.txt
    secrets:
      - aidhs_license.txt
    user: $DOCKER_USER

secrets:
  aidhs_license.txt:
    file: ./aidhs_license.txt

WARNING If you are running docker with Docker Desktop, you will need to ensure that the memory usage allowed by docker is to the maximum, as Docker Desktop halves the memory usage by default. For that you can go in the Docker Desktop settings and change the memory limit (more help in this post)

Set up paths and download model

Before being able to use AID-HS on your data, data paths need to be set up and the pretrained model needs to be downloaded.

Make sure you have 20GB of storage space available for the docker, and 1GB available for the aidhs data.
Run this command to download the docker image and the data folder

Linux

DOCKER_USER="$(id -u):$(id -g)" docker compose run aidhs python scripts/new_patient_pipeline/prepare_aidhs.py

Windows

docker compose run aidhs python scripts/new_patient_pipeline/prepare_aidhs.py

Verify installation

The line below will download AID-HS and then run a test to verify that everything is installed and set up properly. It may take up to an 1h to download the docker image and then takes approximately 1 minute to run the test.

Linux

DOCKER_USER="$(id -u):$(id -g)" docker compose run aidhs pytest

Windows/Mac

docker compose run aidhs pytest

Errors

If you run into errors during the downloading of the AID-HS docker, contact us by email with information about the package you are trying to install, your OS system and a screenshot of the error you encountered. How best to reach us.

If the installation seems to have worked but you are running into errors during the test you can re-run the test above by changing the last line of the command by the command below to save the terminal outputs in a txt file. Please send pytest_errors.log to us so we can work with you to solve any problems. How best to reach us.

Linux

DOCKER_USER="$(id -u):$(id -g)" docker compose run aidhs pytest -s | tee pytest_errors.log

Windows/Mac

docker compose run aidhs pytest -s | tee pytest_errors.log

You will find pytest_errors.log in the folder where you launched the command.

Test GPU

If you have GPU available, you can test that the pipeline is working well with your GPU by changing count to all in the compose.yml file. The deploy section should look like this to enable gpus:

deploy:
  resources:
    reservations:
      devices:
        - capabilities: [gpu]
          count: all

To disable gpus, change it back to 0.

Note: if you don’t have GPUs on your computer you should remove the lines aboves from the compose.yml file

FAQs

Please see our FAQs for common installation problems.

Contact

If you encounter any errors, please contact meld.study@gmail.com for support