Enigma-PD-WML

Segment White Matter Lesions (WML) in T1-weighted and FLAIR MRI images using FSL and U-Net

What does the pipeline do?

This pipeline allows white matter lesions (WMLs) to be segmented from a subject's T1-weighted and FLAIR MRI images from the same scanning session. The analysis steps (including pre- and post- processing) make use of the following tools:

• FSL (FMRIB Software Library) : a library of analysis tools for FMRI, MRI and diffusion brain imaging data.

• UNet-pgs : A segmentation pipeline for white matter hyperintensities (WMHs) using U-Net.

• Nipoppy : A Python package to structure DICOM and NIFTI images in BIDS format

For details of the processing steps, see the pipeline documentation.

The pipeline is available as a Docker or Apptainer container, allowing it to be run on many different systems.

How to run the pipeline?

Setting up and running the pipeline requires the following steps, which are explained in detail in the sections below:

%%{init: {"flowchart": {"htmlLabels": false}} }%%
flowchart TD
    installation("`Install prerequisites`")
    convert("`Ensure data is in BIDS format`")
    subjects("`Create a subjects.txt input file`")
    run("`Run the container with Docker / Apptainer`")
    installation --> convert
    convert --> subjects
    subjects --> run

Loading

1. Install prerequisites

If your MRI data isn't in BIDS format, it is recommended to install Nipoppy.

If you want to run the container via Docker, install Docker Desktop. They have installation instructions for Mac, Windows and Linux systems.

If you want to use Apptainer instead, then follow the installation instructions on their website.

2. Convert data to BIDS format (if required)

If your data isn't structured in BIDS format, we recommend you use Nipoppy to restructure your into the required format.

For detailed instructions on the BIDSification process, please see the excellent guide written by the ENIGMA-PD core team for the FS7 pipeline.

Once you have converted your data to BIDS format, your data directory should have the following structure:

data
├───sub-1
│   └───ses-1
│       └───anat
│           ├───sub-1_ses-1_T1w.nii.gz
│           └───sub-1_ses-1_FLAIR.nii.gz
│
├───sub-2
│   └───ses-1
│       └───anat
│           ├───sub-1_ses-1_T1w.nii.gz
│           └───sub-1_ses-1_FLAIR.nii.gz

3. Create subjects.txt file

Inside your top-level BIDS directory (e.g. data in the above example structure), create a subjects.txt file that contains subject identifiers (one per line).

The subject identifies must match the names of the corresponding subject folders, e.g. sub-1, sub-2.

Your final file structure should look like below (for two example subject ids):

data
├── sub-1
│   └── ses-1
│       └── anat
│           ├── sub-1_ses-1_T1w.nii.gz
│           └── sub-1_ses-1_FLAIR.nii.gz
│
├── sub-2
│   └── ses-1
│       └── anat
│           ├── sub-1_ses-1_T1w.nii.gz
│           └── sub-1_ses-1_FLAIR.nii.gz
└── subjects.txt

4. Run the container

Important

When running the container, make sure you run the command from the top-level directory of your BIDS-structured data, e.g. the data directory in this example folder structure

Note

There are some optional arguments you can add to the end of the Docker / Apptainer command.

Tip

If you encounter issues when running the pipeline, check the output logs for any errors.

Using Docker

The image is available on Docker Hub in the enigma-pd-wml repository.

To run the analysis using Docker:

docker run -v "${PWD}":/data hamiedaharoon24/enigma-pd-wml:<tag>

where <tag> is the version of the image you would like to pull.

Note, the image will be downloaded from Docker Hub the first time you run a particular version of the image.

Using Apptainer

The image is available on Sylabs Cloud in the hh-enigmapd-2025/enigma-pd-wml/enigma-pd-wml repository.

To run the analysis using Apptainer:

apptainer run --bind "${PWD}":/data library://hh-enigmapd-2025/enigma-pd-wml/enigma-pd-wml:<tag>

where <tag> is the version of the image you would like to pull.

It can sometime be slow to pull the image from Sylabs Cloud. If you would prefer to pull the Docker image from Docker Hub and build and run a local Apptainer image, you can run the following command:

apptainer run --bind "${PWD}":/data docker://hamiedaharoon24/enigma-pd-wml:<tag>

Note, the image will be downloaded from Sylabs Cloud (or Docker Hub) the first time you run a particular version of the image.

Options

• -n : the number of jobs to run in parallel.

  By default (without -n), the pipeline will process your subjects sequentially on 1 core. With -n they will be processed in parallel with n jobs. For example:

  # Run with 5 jobs
  -n 5

  A good default value is the number of cores on your system, but be wary of increased memory usage.

• -o : whether to overwrite existing output files

  By default (without -o), the pipeline will try to re-use any existing output files, skipping steps that are already complete. This is useful if, for example, the pipeline fails at a late stage and you want to run it again, without having to re-run time-consuming earlier steps. With -o the pipeline will run all steps again and ensure any previous output is overwritten.

Pipeline output

Output images

After running your analysis, your data directory should have the following structure:

bids-data
├── dataset_description.json
├── derivatives
│   └── enigma-pd-wml
│       ├── enigma-pd-wml.log
│       └── sub-1
│           ├── ses-1
│           │   ├── input/
│           │   ├── output/
│           │   ├── sub-1_ses-1.log
│           │   └── sub-1_ses-1_results.zip
│           └── ses-2
│               ├── input/
│               ├── output/
│               ├── sub-1_ses-2.log
│               └── sub-1_ses-2_results.zip
├── sub-1
│   ├── ses-1
│   │   └── anat
│   │       ├── sub-1_ses-1_FLAIR.nii.gz
│   │       └── sub-1_ses-1_T1w.nii.gz
│   └── ses-2
│       └── anat
│           ├── sub-1_ses-2_FLAIR.nii.gz
│           └── sub-1_ses-2_T1w.nii.gz
└── subjects.txt

Session-level zip files

The pipeline will generate multiple .zip files - one per session, stored within the corresponding session sub-folder, e.g. derivatives/enigma-pd-wml/sub-1/ses-1/sub-1_ses-1_results.zip.

These zip files should contain six files:

• results2mni_lin.nii.gz: WML segmentations linearly transformed to MNI space.

• results2mni_lin_deep.nii.gz: WML segmentations (deep white matter) linearly transformed to MNI space.

• results2min_lin_perivent.nii.gz: WML segmentations (periventricular) linearly transformed to MNI space.

• results2mni_nonlin.nii.gz: WML segmentations non-linearly warped to MNI space.

• results2min_nonlin_deep.nii.gz: WML segmentations (deep white matter) non-linearly warped to MNI space.

• results2mni_nonlin_perivent.nii.gz: WML segmentations (periventricular) non-linearly warped to MNI space.

• T1_biascorr_brain_to_MNI_lin.nii.gz: T1 bias-corrected brain linearly transformed to MNI space.

• FLAIR_biascorr_brain_to_MNI_lin.nii.gz: FLAIR bias-corrected brain linearly transformed to MNI space.

• T1_biascorr_brain_to_MNI_nonlin.nii.gz: T1 bias-corrected brain non-linearly warped to MNI space.

• FLAIR_biascorr_brain_to_MNI_nonlin.nii.gz: FLAIR bias-corrected brain non-linearly warped to MNI space.

Top-level zip file

A top-level zip file will also be created (derivatives/enigma-pd-wml/enigma-pd-wml-results.zip). This will contain all zip files for each session.

Please send this top-level zip file to the ENIGMA-PD Vasc team.

Intermediate files

The pipeline generates several intermediate files. These are stored in the derivatives/enigma-pd-wml/<subject>/<session>/input and derivatives/enigma-pd-wml/<subject>/<session>/output folders.

Output logs

Pipeline logs can be found at:

• derivatives/enigma-pd-wml/enigma-pd-wml.log: contains minimal information about the initial pipeline setup.

• derivatives/enigma-pd-wml/<subject>/<session>/<subject>_<session>.log: one log per session; contains information about the various processing steps.

Common issues

Tensorflow memory usage

A common issue is UNets-pgs failing due to high memory usage. You may see warnings / errors in your subject logs similar to:

• tensorflow/core/framework/allocator.cc:124] Allocation of 675840000 exceeds 10% of system memory.

• /WMHs_segmentation_PGS.sh: line 14: 69443 Killed

You may want to try:

• Running the pipeline on a system with more memory

• Reducing the number of jobs passed to the -n option (if you're using it). This will slow down the pipeline, but also reduce overall memory usage.

For developers

Some brief notes on the development setup for this repository are provided in a separate developer docs file.