dipy logo

Site Navigation

NIPY Community

Tractography Clustering with QuickBundlesΒΆ

This example explains how we can use QuickBundles [Garyfallidis12] to simplify/cluster streamlines.

First import the necessary modules.

import numpy as np
from nibabel import trackvis as tv
from dipy.tracking.streamline import set_number_of_points
from dipy.segment.clustering import QuickBundles
from dipy.io.pickles import save_pickle
from dipy.data import get_data
from dipy.viz import fvtk

For educational purposes we will try to cluster a small streamline bundle known from neuroanatomy as the fornix.

fname = get_data('fornix')

Load fornix streamlines.

streams, hdr = tv.read(fname)

streamlines = [i[0] for i in streams]

Perform QuickBundles clustering using the MDF metric and a 10mm distance threshold. Since the MDF metric requires streamlines to have the same number of points, we first downsample them so they have only 18 points and then run the clustering algorithm.

qb = QuickBundles(threshold=10.)
streamlines = set_number_of_points(streamlines, nb_points=18)
clusters = qb.cluster(streamlines)

clusters is a ClusterMap object which contains attributes that provide information about the clustering result.

print("Nb. clusters:", len(clusters))
print("Cluster sizes:", map(len, clusters))
print("Small clusters:", clusters < 10)
print("Streamlines indices of the first cluster:\n", clusters[0].indices)
print("Centroid of the last cluster:\n", clusters[-1].centroid)
Nb. clusters: 4

Cluster sizes: [64, 191, 44, 1]

Small clusters: array([False, False, False, True], dtype=bool)

Streamlines indices of the first cluster:
[0, 7, 8, 10, 11, 12, 13, 14, 15, 18, 26, 30, 33, 35, 41, 42, 45, 65, 66, 75,
 85, 100, 101, 105, 115, 116, 119, 122, 123, 124, 125, 126, 128, 129, 135, 139,
 142, 143, 144, 148, 151, 159, 167, 175, 180, 181, 185, 200, 208, 210, 224, 237,
 246, 249, 251, 256, 267, 270, 280, 284, 293, 296, 297, 299]

Centroid of the last cluster:
array([[  84.83773804,  117.92590332,   77.32278442],
       [  85.89845276,  116.67261505,   80.27609253],
       [  86.2130661 ,  114.88985443,   83.13295746],
       [  86.40007019,  112.50982666,   85.55088043],
       [  86.54071045,  109.60722351,   87.31826019],
       [  86.39044189,  106.43745422,   88.54563904],
       [  86.29808807,  103.12637329,   89.29672241],
       [  85.72164154,   99.78807068,   89.04328918],
       [  84.6943512 ,   96.6314621 ,   88.31369781],
       [  83.09349823,   93.83686066,   87.22660065],
       [  81.00836945,   91.42190552,   86.07907867],
       [  78.49610138,   89.20231628,   85.63204193],
       [  75.75254822,   87.23584747,   85.22332001],
       [  72.96138   ,   85.69472504,   84.09647369],
       [  70.16287231,   85.14102173,   82.26060486],
       [  67.67449188,   85.57660675,   79.98880005],
       [  65.69326782,   86.66771698,   77.44818115],
       [  64.02451324,   88.43942261,   75.0697403 ]], dtype=float32)
`clusters` has also attributes like `centroids` (cluster representatives), and

methods like add, remove, and clear to modify the clustering result.

Lets first show the initial dataset.

ren = fvtk.ren()
ren.SetBackground(1, 1, 1)
fvtk.add(ren, fvtk.streamtube(streamlines, fvtk.colors.white))
fvtk.record(ren, n_frames=1, out_path='fornix_initial.png', size=(600, 600))
../_images/fornix_initial.png

Initial Fornix dataset.

Show the centroids of the fornix after clustering (with random colors):

colormap = np.random.rand(len(clusters), 3)

fvtk.clear(ren)
ren.SetBackground(1, 1, 1)
fvtk.add(ren, fvtk.streamtube(streamlines, fvtk.colors.white, opacity=0.05))
fvtk.add(ren, fvtk.streamtube(clusters.centroids, colormap, linewidth=0.4))
fvtk.record(ren, n_frames=1, out_path='fornix_centroids.png', size=(600, 600))
../_images/fornix_centroids.png

Showing the different QuickBundles centroids with random colors.

Show the labeled fornix (colors from centroids).

colormap_full = np.ones((len(streamlines), 3))
for cluster, color in zip(clusters, colormap):
    colormap_full[cluster.indices] = color

fvtk.clear(ren)
ren.SetBackground(1, 1, 1)
fvtk.add(ren, fvtk.streamtube(streamlines, colormap_full))
fvtk.record(ren, n_frames=1, out_path='fornix_clusters.png', size=(600, 600))
../_images/fornix_clusters.png

Showing the different clusters.

It is also possible to save the complete ClusterMap object with pickling.

save_pickle('QB.pkl', clusters)

Finally, here is a video of QuickBundles applied on a larger dataset.

[Garyfallidis12]Garyfallidis E. et al., QuickBundles a method for tractography simplification, Frontiers in Neuroscience, vol 6, no 175, 2012.

Example source code

You can download the full source code of this example. This same script is also included in the dipy source distribution under the doc/examples/ directory.