TRUENET Practical

In this practical, we will use TRUENET (the Triplanar U-Net ensemble network) to segment white matter lesions, specifically white matter hyperintensities of presumed vascular origin (WMH). TRUENET can work with T1 and/or FLAIR images. We are only going to cover using a pre-trained TRUENET model to segment a couple of datasets, since TRUENET comes bundled with a number of pre-trained models, but you can also train TRUENET on your own data - refer to the TRUENET documentation for more details.

For this exercise, we will use a subset of the data we used for the BIANCA practical (sub-001 and sub-010). We will apply a pre-trained TRUENET model to a subject for which we have a lesion mask available, to compare the segmentation from TRUENET to the manual segmentation. We will then apply the same model to a subject for which we don't have a manual mask, but for which we segmented WMHs automatically with BIANCA, and compare the outputs of BIANCA and TRUENET.

Install TRUENET

TRUENET is an optional part of FSL - if you are attending an FSL Course, TRUENET will already be installed. However, if you are following this practical on your own computer, you will need to install TRUENET if you have not already done so:

update_fsl_release --extra truenet

To find about the subcommands available in TRUENET

truenet -help

Look at your data

cd ~/fsl_course_data/truenet

Let's start by having a look at the datasets with FSLeyes to remind ourselves what we are working with. Like BIANCA, TRUENET needs the different modalities to be brain-extracted and registered to each other for each subject (in this case we used the FLAIR image as reference), which we have already prepared for you. For more information and guidance on how to prepare your own data, go to the optional section at the bottom of this practical.

Note that TRUENET also requires a specific naming convention for the input data so we have renamed the files accordingly. For more information on the naming convention, please refer to the TRUENET documentationfor more details. For the first subject we load the FLAIR image, and the manually-labelled lesion mask on top:

fsleyes sub-001/sub-001_FLAIR.nii.gz sub-001/sub-001_manualmask.nii.gz -cm red -a 70 &

For the second subject, let's look at the FLAIR image, and the BIANCA-derived lesion mask on top:

fsleyes sub-010/sub-010_FLAIR.nii.gz sub-010/sub-010_bianca_output_bin.nii.gz -cm red -a 70 &

Applying TRUENET

You can use the truenet evaluate command to automatically segment a T1 and/or FLAIR image. The truenet evaluate command expects to be given a directory which contains the input file(s), and also expects that those files have been pre-processed and registered to each other.

To save time, we have already done this for you, but in the future you can use the prepare_truenet_data command on your own data - this is described below.

Once the data have been prepared, we can apply TRUENET by running truenet evaluate - the structure of the command to run is as follows:

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

Where the following (compulsory) arguments are:

-i Path to the directory containing the preprocesesd images
-m Pre-trained model name (one of mwsc, mwsc_flair, mwsc_t1, ukbb, ukbb_flair, ukbb_t1), or directory containing your own model.
-o Path to the directory for saving output predictions

We will use the pre-trained mwsc model, trained on T1 and FLAIR data part of the MICCAI WMH Segmentation Challenge (please refer to the TRUENET documentation for more details on all the available pre-trained models). We will save the results to a directory called truenet_results. The command will take a minute or two to run:

mkdir sub-001/truenet_results/
truenet evaluate -i sub-001/ -m mwsc -o sub-001/truenet_results

After running TRUENET

The primary output of TRUENET is a probability map (similar to the output of BIANCA), highlighting brain regions that are likely to be white matter hyperintensities. We often want this in the form of a binary mask, so let's use fslmaths to apply a threshold (in this case we will use 0.2, but you should select it according to what works best on your data) and binarise the probability map:

fslmaths \
  sub-001/truenet_results/Predicted_probmap_truenet_sub-001.nii.gz \
  -thr 0.2 -bin \
  sub-001/truenet_results/Predicted_output_truenet_sub-001_bin.nii.gz

Now let's load it into FSLeyes to see how well TRUENET was able to identify the WMHs:

fsleyes \
  sub-001/sub-001_FLAIR.nii.gz \
  sub-001/truenet_results/Predicted_output_truenet_sub-001_bin.nii.gz -cm blue -a 70 &

Leave fsleyes open.

Compare TRUENET output with manual mask

Now add the manual mask we looked at the beginning (File -> Add from file -> sub-001_manualmask.nii.gz). Adjust colour and opacity, and compare the maps. How would you judge the performance of TRUENET on this image? Are there any lesions that TRUENET missed or vice-versa lesions that TRUENET detected but the manual rater did not label?

Compare TRUENET output with BIANCA output

Now try to apply TRUENET to the second subject, sub-010. If you neeed a hint on the commands, click here.

The command to run TRUENET is:

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

While to threshold and binarise the output we can use:

fslmaths \
  sub-010/truenet_results/Predicted_probmap_truenet_sub-010.nii.gz \
  -thr 0.2 -bin \
  sub-010/truenet_results/Predicted_output_truenet_sub-010_bin.nii.gz

Let's load the results into FSLeyes to see how well TRUENET was able to identify the WMHs:

fsleyes \
  sub-010/sub-010_FLAIR.nii.gz \
  sub-010/truenet_results/Predicted_output_truenet_sub-010_bin.nii.gz -cm blue -a 70 &

Now add on the output of BIANCA that we generated for you following the instructions of the BIANCA practical. Click File -> Add from file -> sub-010_bianca_output_bin.nii.gz

Adjust colour and opacity, and compare the maps. How would you judge the performance of TRUENET on this image? Are there any lesions that TRUENET missed or vice-versa lesions that TRUENET detected but not BIANCA?

Extra

We can also look at the results from BIANCA on the previous subject, comparing TRUENET, BIANCA, and the manual mask:

fsleyes \
  sub-001/sub-001_FLAIR.nii.gz \
  sub-001/truenet_results/Predicted_output_truenet_sub-001_bin.nii.gz -cm blue -a 50 \
  sub-001/sub-001_bianca_output_bin.nii.gz -cm red-yellow -a 50 \
  sub-001/sub-001_manualmask.nii.gz -cm red -a 30 &

As you can see BIANCA and TRUENET successfully detected lesions in both cases. On slice 21 (in the z direction) you can also see how both BIANCA and TRUENET detected small lesions that were missed in the manual mask (e.g. voxel coord 86, 129, 21). The main improvements of TRUENET over BIANCA are the possibility to use a pre-trained model provided with the tool, and the fact that TRUENET was specifically developed to enhance the detection of small deep lesions (see e.g. 153, 122, 18). Also note that in this case we did not need to apply an exclusion mask to the output of TRUENET as there were no evident false positives near the cortex, while the output of BIANCA would have benefitted from an extra cleaning step (again evident in slice 18). (applying the BIANCA exclusion mask to the TRUENET result still remains a valid option for your data).

Optional: how to prepare your data for TRUENET

Before applying TRUENET, we need to perform some pre-processing on our data. If using a pre-trained model, all the modalities need to be skull-stripped, bias-field corrected, and registered to a base image (like for BIANCA). If you also plan to use truenet to train or fine-tune the model to your data you will need your own manual masks and two additional files: a distance map from the ventricles and a distance map from the gray matter.

We provide a script that does all these preprocessing steps for you: prepare_truenet_data command. This command expects to be given your unprocessed T1 and/or FLAIR images. It will reorient the images to the standard MNI space, perform skull-stripping with FSL BET and bias field correction using FSL FAST. The script will also register the T1-weighted image to the FLAIR using linear rigid-body registration. Note that the script uses fairly default options for the different steps, so you may need to optimise options (e.g. for BET) for your own data.

The prepare_truenet_data command can be called like so:

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 to save the processed FLAIR and T1 images; output_basename_FLAIR.nii.gz, output_basename_T1.nii.gz etc.

The prepare_truenet_data command produces the following files:

<output_basename>_FLAIR.nii.gz Processed FLAIR image (brain-extracted and co-registered with the T1)
<output_basename>_T1.nii.gz Processed T1 image (brain-extracted and co-registered with the FLAIR)
<output_basename>_brainmask.nii.gz Binary brain mask
<output_basename>_WMmask.nii.gz Binary white matter mask
<output_basename>_GMdistmap.nii.gz Grey matter distance map (distance from each voxel to the nearest grey-matter)
<output_basename>_ventdistmap.nii.gz Ventricle distance map (distance from each voxel to the nearest ventricle region)

These files can be then used for the different TRUENET options as detailed in the TRUENET documentation. The table below summarises which files are needed for each truenet option:

File name	Naming convention	`truenet evaluate`	`truenet train`	`truenet fine_tune`	`truenet cross_validate`
FLAIR image (preprocessed)	`<subject_name>_FLAIR.nii.gz`	Y	Y	Y	Y
T1 image (preprocessed)	`<subject_name>_T1.nii.gz`	Y	Y	Y	Y
Grey matter distance map	`<subject_name>_GMdistmap.nii.gz`	N	Y	Y	Y
Ventricle distance map	`<subject_name>_ventdistmap.nii.gz`	N	Y	Y	Y
Manual lesion mask	`<subject_name>_manualmask.nii.gz`	N	Y	Y	Y

Conclusion

In this practical we have shown you how to use TRUENET to automatically identify regions of white-matter hyperintensities in FLAIR and/or T1 structural images. TRUENET comes installed with a number of pre-trained models, but you can also train a model on your own data - take a look at the TRUENET documentation for details on how to do this, if you are interested.

The End.