Asymmetric orientation distribution functions (aodf)

The usual symmetric orientation distribution function cannot accurately describe complex fiber configurations such as branching, fanning or bending fiber populations. To tackle this issue, we can estimate asymmetric orientation distribution functions AODF [Poirier and Descoteaux, Neuroimage, 2024]. AODF can be estimated from an input symmetric ODF image via the script scil_sh_to_aodf.

Preparing data for this tutorial

To run lines below, you need a symmetric ODF image (e.g. from Q-ball or CSD) and a mask to restrict the computation to relevant voxels. The tutorial data is still in preparation, meanwhile you can use this:

in_dir=where/you/downloaded/tutorial/data

# For now, let's use data in .scilpy
scil_data_download -v ERROR
mkdir $in_dir/aodf_data
in_dir=$in_dir/aodf_data
scil_volume_math convert $HOME/.scilpy/processing/fa_thr.nii.gz \
    $in_dir/brainmask.nii.gz --data_type uint8
cp $HOME/.scilpy/processing/fodf_descoteaux07.nii.gz $in_dir/fodf.nii.gz

Suggestion. For a faster processing of this tutorial data, you could crop the fodf and brainmask volumes (see Cropping volumes). With a normal dataset, this tutorial would takes 3-5 hours to complete. The sample data for this tutorial uses a data of size 57x67x56 voxels, with 15 values per voxel, but let’s reduce that even more for a shorter run. The current bounding box for this data would be:

{
    "minimums": [-20, -30, -20],
    "maximums": [20, 30, 20],
    "voxel_size": [2.5, 2.5, 2.5]
}

Tip

You may download the complete bash script to run the whole tutorial in one step ⭳ here.

1. Creating the aodf

Although there is an automatic way to set the parameters, it is not yet implemented in scilpy. We recommend that you experiment with the parameters to find the best configuration for your data. Here, we use the smallest sphere available in Dipy, for a fast test. You can run the command as follows:

scil_sh_to_aodf $in_dir/fodf.nii.gz afodf.nii.gz -v --sphere repulsion100

The default script runs a pure python implementation, which is slow. To speed up the execution, you should use OpenCL if you have a compatible GPU or CPU. Make sure you have pyopencl installed and a working OpenCL implementation. You can enable OpenCL acceleration by adding the –use_opencl flag to the command. You can also choose the device to use (CPU or GPU) with the –device option. Using a GPU will reduce the execution time to 1-2 minutes (on a Nvidia GeForce RTX 3080). For example, to use a GPU, you can run:

scil_sh_to_aodf $in_dir/fodf.nii.gz afodf.nii.gz --use_opencl --device gpu -v

The script will output the asymmetric ODF image (afodf.nii.gz) in the current directory. At the difference of a symmetric ODF image, which is represented using a symmetric spherical harmonics basis, the asymmetric ODF image is represented using a full spherical harmonics basis. Therefore, the output image will have more SH coefficients than the input image. For instance, for a maximum SH order of 8, the input image will have 45 coefficients per voxel, while the output image will have 81 coefficients per voxel.

2. Computing metrics

From the estimated AODF, we can compute a bunch of metrics using the script scil_aodf_metrics:.

scil_aodf_metrics afodf.nii.gz --mask $in_dir/brainmask.nii.gz -v

This script outputs the following metrics:

  • Asymmetry index map (asi_map.nii.gz)

  • Number of fiber directions (NuFiD) map (nufid.nii.gz)

  • Odd-power map (odd_power_map.nii.gz)

  • Peaks image (asym_peaks.nii.gz)

  • Peak values (asym_peak_values.nii.gz)

  • Peak indices (asym_peaks_indices.nii.gz)

Refer to the script --help for a description of these metrics. Like with the other metrics scripts, the flag --not_all can be used to skip some outputs and only compute the metrics of interest.