TrUE-Net Practical

In this section, we will use Triplanar U-Net ensemble network (TrUE-Net) to segment white matter lesions, specifically white matter hyperintensities of presumed vascular origin (WMH).

Install the TrUE-Net tool

python fslinstaller.py --extra truenet --cuda 11.2install

To find about the subcommands available in TrUE-Net

truenet -help

Look at your data

For this exercise, we use the same data used for BIANCA.

Before training, let's have a look at the data with FSLeyes

fsleyes sub-010/FLAIR_brain.nii.gz manual_mask.nii.gz -cm red -a 70

The process

digraph G { rankdir=TD node [shape=box]; 1 [label="Input: T1, FLAIR, manualmask"]; 2 [label="prepare"]; 3 [label="Output: Master File, T1, FLAIR, manualmask, ventdistmap, GMdistmap"]; 4 [label="TrUE-Net options"]; 5 [label="train"]; 6 [label="fine_tune"]; 7 [label="evaluate"]; 8 [label="cross_validate"]; 1 -> 2; 2 -> 3; 3 -> 4; 4 -> 5; 4 -> 6; 4 -> 7; 4 -> 8; }

Prepare TrUE-Net data

We use both T1-weighted and FLAIR images as inputs for the model. We reorient the images to the standard MNI space, perform skull-stripping FSL BET and bias field correction using FSL FAST. We register the T1-weighted image to the FLAIR using linear rigid-body registration.

To preprocess images and write the filepaths in the masterfile

prepare_truenet_data --FLAIR=<FLAIR_image_name> --T1=<"T1_image_name> --outname=<output_basename>

where the arguments

--FLAIR     Absolute/relative path of the input unprocessed FLAIR image with the nifti file
--T1        Absolute/relative path of the input unprocessed T1 image with the nifti file
--outname   Absolute/relative path for the processed FLAIR and T1 images; output_basename_FLAIR.nii.gz, output_basename_T1.nii.gz etc. will be saved

To preprocess the data from sub-010

mkdir truenet_data/

prepare_truenet_data --FLAIR=sub-010/FLAIR_brain.nii.gz --T1=sub-010/T1_brain.nii.gz --outname=truenet_data/sub-010

Applying the TrUE-Net

Applying a saved/pretrained TrUE-Net model for testing

truenet evaluate -i <input_directory> -m <model_name> -o <output_directory> [options]

where compulsory arguments are

-i, --inp_directory   Name of the masterfile with the absolute path
-m, --model_name      Model basename with absolute path /pretrained model name (mwsc, mwsc_flair, mwsc_t1, ukbb, ukbb_flair, ukbb_t1)
-o, --output_dir      Path to the directory for saving output predictions'

Here we consider that we apply the pretrained TrUE-Net model on the data in the directory truenet_data with the model pretrained on MWSC dataset (mwsc):

mkdir truenet_results/

truenet evaluate -i truenet_data/sub-010 -m mwsc -o truenet_results/

After running TrUE-Net

TrUE-Net output is a probability map. However, for most of the applications we want a binary lesion mask, so we need to apply a threshold (typically 0.5) and binarise the image.

fslmaths truenet_results/Predicted_probmap_truenet_sub-010.nii.gz -thr 0.5 -bin truenet_results/Predicted_output_truenet_sub-010.nii.gz

To visualize the TrUE-Net predictions on FSLeyes

fsleyes truenet_data/sub-010_FLAIR.nii.gz  truenet_results/Predicted_output_truenet_sub-010.nii.gz -cm red -a 70

Additional options from TrUE-Net

The following are the advanced options available in TrUE-Net. The instructions for fine-tuning a pretrained model, training a model from scratch and cross-validation are provided below.

Kindly note that you would need a GPU for efficiently training/fine-tuning the models (else it might take hours!).

Fine-tuning TrUE-Net

truenet fine_tune -i <input_directory> -m <model_name> -o <output_directory> [options]

where compulsory arguments are

-i, --inp_directory   Name of the directory with the absolute path
-m, --model_name      Model basename with absolute path / pretrained model name (mwsc, mwsc_flair, mwsc_t1, ukbb, ukbb_flair, ukbb_t1)
-o, --output_dir      Output directory for saving fine-tuned models/weights

Training the TrUE-Net

To train the TrUE-Net model from scratch

truenet train -i <input_dir> -m <model_directory> [options]

where compulsory arguments are

-i, --inp_dir     Name of the input directory with the absolute path
-m, --model_dir   Directory for saving model weights

Cross-validation of TrUE-Net model

truenet cross_validate -i <input_directory> -o <output_directory> [options]

where compulsory arguments are

-i, --inp_directory   Name of the masterfile with the absolute path
-o, --output_dir      Output directory for saving predictions (and models)

The End.