Merge pull request #1881 from gabknight/RF_tracking_examples

DOC - RF tracking examples

doc/examples/tracking_bootstrap_peaks.py

@@ -5,52 +5,44 @@
 
 This example shows how choices in direction-getter impact fiber
 tracking results by demonstrating the bootstrap direction getter (a type of
-probabilistic tracking, as described in [Berman2008]_) and the closest peak
-direction getter (a type of deterministic tracking).
+probabilistic tracking, as described in Berman et al. (2008) [Berman2008]_ a
+nd the closest peak direction getter (a type of deterministic tracking).
 (Amirbekian, PhD thesis, 2016)
 
-Let's load the necessary modules for executing this tutorial.
+This example is an extension of the :ref:`example_tracking_introduction_eudx`
+example. Let's start by loading the necessary modules for executing this
+tutorial.
 """
 
+# Enables/disables interactive visualization
+interactive = False
+
 from dipy.data import read_stanford_labels
-from dipy.tracking import utils
-from dipy.tracking.local import (ThresholdTissueClassifier, LocalTracking)
 from dipy.io.streamline import save_trk
-from dipy.viz import window, actor, colormap as cmap
-
-renderer = window.Renderer()
-
-"""
-Now we import the CSD model
-"""
-
 from dipy.reconst.csdeconv import ConstrainedSphericalDeconvModel
-
-"""
-First we load our images and establish seeds. See the Introduction to Basic
-Tracking tutorial for more background on these steps.
-"""
+from dipy.tracking import utils
+from dipy.tracking.local import (ThresholdTissueClassifier, LocalTracking)
+from dipy.viz import window, actor, colormap, has_fury
 
 hardi_img, gtab, labels_img = read_stanford_labels()
 data = hardi_img.get_data()
 labels = labels_img.get_data()
 affine = hardi_img.affine
 
-seed_mask = labels == 2
+seed_mask = (labels == 2)
 white_matter = (labels == 1) | (labels == 2)
 seeds = utils.seeds_from_mask(seed_mask, density=1, affine=affine)
 
 """
-Next, we fit the CSD model
+Next, we fit the CSD model.
 """
 
 csd_model = ConstrainedSphericalDeconvModel(gtab, None, sh_order=6)
 csd_fit = csd_model.fit(data, mask=white_matter)
 
-
 """
 we use the CSA fit to calculate GFA, which will serve as our tissue
-classifier
+classifier.
 """
 
 from dipy.reconst.shm import CsaOdfModel
@@ -64,6 +56,7 @@
 
 """
 Example #1: Bootstrap direction getter with CSD Model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from dipy.direction import BootDirectionGetter
@@ -76,26 +69,29 @@
                                           affine, step_size=.5)
 streamlines = Streamlines(boot_streamline_generator)
 
-renderer.clear()
-renderer.add(actor.line(streamlines, cmap.line_colors(streamlines)))
-window.record(renderer, out_path='bootstrap_dg_CSD.png', size=(600, 600))
+save_trk("tractogram_bootstrap_dg.trk", streamlines, affine, labels.shape)
+
+if has_fury:
+    r = window.Renderer()
+    r.add(actor.line(streamlines, colormap.line_colors(streamlines)))
+    window.record(r, out_path='tractogram_bootstrap_dg.png', size=(800, 800))
+    if interactive:
+        window.show(r)
 
 """
-.. figure:: bootstrap_dg_CSD.png
+.. figure:: tractogram_bootstrap_dg.png
    :align: center
 
    **Corpus Callosum Bootstrap Probabilistic Direction Getter**
 
 We have created a bootstrapped probabilistic set of streamlines. If you repeat
 the fiber tracking (keeping all inputs the same) you will NOT get exactly the
-same set of streamlines. We can save the streamlines as a Trackvis file so it
-can be loaded into other software for visualization or further analysis.
+same set of streamlines.
 """
 
-save_trk("bootstrap_dg_CSD.trk", streamlines, affine, labels.shape)
-
 """
 Example #2: Closest peak direction getter with CSD Model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 """
 
 from dipy.direction import ClosestPeakDirectionGetter
@@ -107,26 +103,31 @@
                                           step_size=.5)
 streamlines = Streamlines(peak_streamline_generator)
 
-renderer.clear()
-renderer.add(actor.line(streamlines, cmap.line_colors(streamlines)))
-window.record(renderer, out_path='closest_peak_dg_CSD.png', size=(600, 600))
+save_trk("closest_peak_dg_CSD.trk", streamlines, affine, labels.shape)
+
+if has_fury:
+    r = window.Renderer()
+    r.add(actor.line(streamlines, colormap.line_colors(streamlines)))
+    window.record(r, out_path='tractogram_closest_peak_dg.png',
+                  size=(800, 800))
+    if interactive:
+        window.show(r)
 
 """
-.. figure:: closest_peak_dg_CSD.png
+.. figure:: tractogram_closest_peak_dg.png
    :align: center
 
    **Corpus Callosum Closest Peak Deterministic Direction Getter**
 
 We have created a set of streamlines using the closest peak direction getter,
 which is a type of deterministic tracking. If you repeat the fiber tracking
 (keeping all inputs the same) you will get exactly the same set of streamlines.
-We can save the streamlines as a Trackvis file so it can be loaded into other
-software for visualization or further analysis.
 """
 
-save_trk("closest_peak_dg_CSD.trk", streamlines, affine, labels.shape)
 
 """
+References
+----------
 .. [Berman2008] Berman, J. et al., Probabilistic streamline q-ball
 tractography using the residual bootstrap, NeuroImage, vol 39, no 1, 2008
 

doc/examples/deterministic_fiber_tracking.py → doc/examples/tracking_deterministic.py

@@ -17,16 +17,22 @@
 tractography and unlike EuDX does not follow the peaks of the local models but
 uses the entire orientation distributions.
 
-This example is an extension of the
-:ref:`example_probabilistic_fiber_tracking` example. We begin by loading the
-data and fitting a Constrained Spherical Deconvolution (CSD) reconstruction
-model.
+This example is an extension of the :ref:`example_tracking_probabilistic`
+example. We begin by loading the data, fitting a Constrained Spherical
+Deconvolution (CSD) reconstruction model for the tractography and fitting
+the constant solid angle (CSA) reconstruction model to define the tracking
+mask (tissue classifier).
 """
 
+# Enables/disables interactive visualization
+interactive = False
+
 from dipy.data import read_stanford_labels
 from dipy.reconst.csdeconv import ConstrainedSphericalDeconvModel
+from dipy.reconst.shm import CsaOdfModel
 from dipy.tracking import utils
 from dipy.tracking.local import (ThresholdTissueClassifier, LocalTracking)
+from dipy.viz import window, actor, colormap, has_fury
 
 hardi_img, gtab, labels_img = read_stanford_labels()
 data = hardi_img.get_data()
@@ -40,19 +46,9 @@
 csd_model = ConstrainedSphericalDeconvModel(gtab, None, sh_order=6)
 csd_fit = csd_model.fit(data, mask=white_matter)
 
-"""
-We use the fractional anisotropy (FA) of the DTI model to build a tissue
-classifier.
-"""
-
-import dipy.reconst.dti as dti
-from dipy.reconst.dti import fractional_anisotropy
-
-tensor_model = dti.TensorModel(gtab)
-tenfit = tensor_model.fit(data, mask=white_matter)
-
-FA = fractional_anisotropy(tenfit.evals)
-classifier = ThresholdTissueClassifier(FA, .2)
+csa_model = CsaOdfModel(gtab, sh_order=6)
+gfa = csa_model.fit(data, mask=white_matter).gfa
+classifier = ThresholdTissueClassifier(gfa, .25)
 
 """
 The Fiber Orientation Distribution (FOD) of the CSD model estimates the
@@ -74,5 +70,24 @@
 streamline_generator = LocalTracking(detmax_dg, classifier, seeds, affine,
                                      step_size=.5)
 streamlines = Streamlines(streamline_generator)
-save_trk("deterministic_maximum_shm_coeff.trk", streamlines, affine,
+save_trk("'tractogram_deterministic_dg.trk", streamlines, affine,
          labels.shape)
+
+if has_fury:
+    r = window.Renderer()
+    r.add(actor.line(streamlines, colormap.line_colors(streamlines)))
+    window.record(r, out_path='tractogram_deterministic_dg.png',
+                  size=(800, 800))
+    if interactive:
+        window.show(r)
+
+"""
+.. figure:: tractogram_deterministic_dg.png
+   :align: center
+
+   **Corpus Callosum using deterministic maximum direction getter**
+"""
+"""
+.. include:: ../links_names.inc
+
+"""