Add a lot more tutorial content.

examples/tutorial_examples/baby_afq.py

@@ -1,13 +1,20 @@
 """
 =============================================
-BabyAFQ : tractometry for pediatric dMRI data
+BabyAFQ : tractometry for infant dMRI data
 =============================================
 
-The following is an example of tractometry for pediatric bundles. This example
-and resulting pyAFQ support for pediatric bundles was inspired by and largely
-due to the work of Grotheer et al. [Grotheer2021]_, as implemented in
+The following is an example of tractometry for infant bundles. This example and
+resulting pyAFQ support for pediatric bundles was inspired by and largely due
+to the work of Grotheer et al. [Grotheer2022]_, as implemented in
 [Grotheer2023]_.
 
+.. note::
+    Because it is time and disk-space consuming, this example
+    is not run when the pyAFQ documentation is built. To run this example
+    yourself, you can download the contents of this file as an
+    executable `.py` file or as a Jupyter notebook from the links at the bottom
+    of the page.
+
 """
 import os.path as op
 import plotly
@@ -18,16 +25,36 @@
 import AFQ.api.bundle_dict as abd
 import AFQ.data.fetch as afd
 
-"""
-
-
-The data for this example, provided by Kalanit Grill Spector's Stanford Vision
-and Perception Neuroscience Lab is available to download on Figshare. You can
-download it from there and unzip it into ~/AFQ_Data/baby_example/ (Note that
-this is 2.69GB of data, so it can take a while to download). This data has
-been previously published in Grotheer et al. (2022).
-
-"""
+##########################################################################
+# Baby dMRI data
+# -------------------------
+#
+# Infant MRI data are quite different from data acquired in grownup
+# participants, and even from children that are just a few years older.
+# First, there is the rather obvious difference in size. Baby brains are
+# approximately 25% the size of grownup brains at birth. But there are also
+# often less known differences in brain tissue properties. For example, the
+# myelin content of white matter is much lower in infants than in grownups.
+# This is important because the diffusion signal that we measure with dMRI is
+# sensitive to the myelin content, and it means that the dMRI signal differs
+# quite a bit in newborn infants. For the purpose of delineating the major
+# white matter pathways, it is also important to know that their shape,
+# location and curviness is different in infants than in grownups. For example,
+# the arcuate fasciculus is much more curved in infants than in grownups.
+# Because of this, we use a different set of templates for infant brains than
+# for grownup brains. These templates were created and validated by
+# Mareike Grotheer and colleagues in [Grotheer2022]_. They are available for
+# download as part of the pyAFQ software, as we will show below.
+#
+# In this example, we will demonstrate the use of pyAFQ on data from one
+# infant. The data, provided by Kalanit Grill Spector's
+# `Stanford Vision and Perception Neuroscience Lab <http://vpnl.stanford.edu/>`,
+# and was previously published in [Grotheer2022]_.
+# The data is available to download on
+# `Figshare <https://figshare.com/articles/dataset/Example_babyAFQ_BIDS_subject/21440739>`.
+# You can download it from there and unzip it into ~/AFQ_Data/baby_example/
+# (Note that this is 2.69GB of data, so it can take a while to download). Or
+# you can download it and unzip it using the following block of code.
 
 print("Downloading processed pediatric data; this could take a while...")
 data_folder = op.join(op.expanduser('~'), "AFQ_data/")
@@ -37,31 +64,38 @@
 with zipfile.ZipFile(op.join(data_folder, "baby_example.zip"), 'r') as zip_ref:
     zip_ref.extractall(op.join(data_folder, "baby_example"))
 
-"""
-
-In this case, a tractography has already been run with the excellent MRtrix
-software. When you first run the following code, it will download the infant
-templates into your ~/AFQ_data/pediatric_templates folder, organizing them
-there in the way that pyAFQ expects to find them.
-
-"""
-
 ##########################################################################
 # Initialize a GroupAFQ object:
-# -------------------------
+# -----------------------------
 #
-# .. note::
+# Now that the data is downloaded and organized in a BIDS-compliant structure,
+# we can start running pyAFQ on it. We start by initializing a GroupAFQ object.
+# This object manages all of the data transformations and computations
+# conducted by the software, based on its initial configuration, which we set
+# up below.
 #
-#   While it is possible to run tractography and segmentation for pediatric
-#   dMRI data with pyAFQ, we recommend using a custom tractography pipeline
-#   and only using pyAFQ for segmentation as shown in:
+# A few special things to note here:
 #
-#   - https://github.com/bloomdt-uw/babyafq/blob/main/mrtrix_pipeline.ipynb
-#   - https://github.com/bloomdt-uw/babyafq/blob/main/pybabyafq.ipynb
-
+# 1. The data were preprocessed using the `vistasoft` pipeline, so we set
+#    `preproc_pipeline = "vistasoft"`.
+# 2. We use the UNC neonatal template, which can be read on a call to the
+#    `read_pediatric_templates` function in `AFQ.data.fetch`.
+# 3. We use the `PediatricBundleDict` to define the bundles that we want to
+#    segment. This dictionary is different from the default behavior in that it
+#    uses the waypoint ROIs from [Grotheer2022]_.
+# 4. In this case, tractography has already been run using
+#    `MRTRIX <https://www.mrtrix.org/>`, and is accessed using the
+#    `import_tract` key-word argument.
+# 5. We set `filter_by_endpoints = False` in the `segmentation_params` because
+#    endpoint ROIs are not defined from newborn bundles.
+# 6. We set `distance_threshold = 4` in the `clean_params` because the bundles
+#    need to be cleaned slightly less aggressively than in grownup brains. This
+#    is something that should be evaluated empirically, and may differ in
+#    different datasets.
 
 myafq = GroupAFQ(
-    bids_path=op.join(op.expanduser('~'), "AFQ_data/baby_example/example_bids_subject"),
+    bids_path=op.join(op.expanduser('~'),
+                      "AFQ_data/baby_example/example_bids_subject"),
     preproc_pipeline="vistasoft",
     reg_template_spec=afd.read_pediatric_templates()["UNCNeo-withCerebellum-for-babyAFQ"],
     reg_subject_spec="b0",
@@ -75,10 +109,33 @@
 )
 
 ##########################################################################
-# Visualizing bundles:
+# Running the pipeline
 # --------------------
+#
+# A call to the `export` function will trigger the pyAFQ pipeline. This will
+# run tractography, bundle segmentation, and bundle cleaning. The results will
+# be saved in the `~/AFQ_data/baby_example/derivatives/afq` folder. This can
+# take a while to run, depending on your computer.
+# In this case, we call `export` with the `all_bundles_figure` option. This is
+# because visualizations are created after most other parts of the pipeline
+# have been run. This means that when this call is done, you should have many
+# of the derivative results in the output folder, including the tractography,
+# segmentation, and tract profile results, as well as the visualizations.
+
 viz = myafq.export("all_bundles_figure")
-plotly.io.show(viz["01"])
+
+##########################################################################
+# Viewing the results
+# -------------------
+# One way to view the results is to open the file named
+# `sub-01_ses-01_dwi_space-RASMM_model-probCSD_algo-AFQ_desc-viz_dwi.html`
+# in your browser. This is a visualization of the tractography and segmentation
+# results for all of the bundles. You can navigate this visualization by
+# clicking on the different bundles in the legend on the right side of the
+# screen. You can also zoom in and out using the mouse wheel, and rotate the
+# view by clicking and dragging with the mouse. You can also view the FA tract
+# profiles in a plot on the left side of the page.
+
 
 ##########################################################################
 # References: