{ "cells": [ { "cell_type": "markdown", "id": "7fd96ba4", "metadata": {}, "source": [ "# BabyAFQ : tractometry for infant dMRI data\n", "\n", "The following is an example of tractometry for infant bundles. This example and\n", "resulting pyAFQ support for pediatric bundles was inspired by and largely due\n", "to the work of Grotheer et al. [^Grotheer2021], as implemented in\n", "[^Grotheer2023].\n", "\n", ":::{note}\n", "Because it is time and disk-space consuming, this example\n", "is not run when the pyAFQ documentation is built. To run this example\n", "yourself, you can download the contents of this file as an\n", "executable `.py` file or as a Jupyter notebook from the links at the bottom\n", "of the page.\n", ":::" ] }, { "cell_type": "code", "execution_count": null, "id": "3c72a4da", "metadata": {}, "outputs": [], "source": [ "import os.path as op\n", "import plotly\n", "import wget\n", "import zipfile\n", "\n", "from AFQ.api.participant import ParticipantAFQ\n", "import AFQ.api.bundle_dict as abd\n", "import AFQ.data.fetch as afd\n", "from AFQ.definitions.image import BabyBrainMask" ] }, { "cell_type": "markdown", "id": "c3e58297", "metadata": {}, "source": [ "## Baby dMRI data\n", "\n", "Infant MRI data are quite different from data acquired in grownup\n", "participants, and even from children that are just a few years older.\n", "First, there is the rather obvious difference in size. Baby brains are\n", "approximately 25% the size of grownup brains at birth. But there are also\n", "often less known differences in brain tissue properties. For example, the\n", "myelin content of white matter is much lower in infants than in grownups.\n", "This is important because the diffusion signal that we measure with dMRI is\n", "sensitive to the myelin content, and it means that the dMRI signal differs\n", "quite a bit in newborn infants. For the purpose of delineating the major\n", "white matter pathways, it is also important to know that their shape,\n", "location and curvature is different in infants than in grownups. For example,\n", "the arcuate fasciculus is much more curved in infants than in grownups.\n", "Because of this, we use a different set of templates for infant brains than\n", "for grownup brains. These templates were created and validated by\n", "Mareike Grotheer and colleagues in [^Grotheer2021]. They are available for\n", "download as part of the pyAFQ software, as we will show below.\n", "\n", "In this example, we will demonstrate the use of pyAFQ on data from one\n", "infant. The data, provided by Kalanit Grill Spector's\n", "[Stanford Vision and Perception Neuroscience Lab](http://vpnl.stanford.edu/),\n", "and was previously published in [^Grotheer2021].\n", "The data is available to download on\n", "[Figshare](https://figshare.com/articles/dataset/Example_babyAFQ_BIDS_subject/21440739).\n", "You can download it from there and unzip it into ~/AFQ_Data/baby_example/\n", "(Note that this is 2.69GB of data, so it can take a while to download). Or\n", "you can download it and unzip it using the following block of code." ] }, { "cell_type": "code", "execution_count": null, "id": "13dfb09f", "metadata": {}, "outputs": [], "source": [ "data_folder = op.join(op.expanduser('~'), \"AFQ_data/\")\n", "baby_zip = op.join(data_folder, \"baby_example.zip\")\n", "if not op.exists(baby_zip):\n", " print(\"Downloading processed pediatric data; this could take a while...\")\n", " wget.download(\n", " \"https://figshare.com/ndownloader/files/38053692\",\n", " baby_zip)\n", "\n", "with zipfile.ZipFile(baby_zip, 'r') as zip_ref:\n", " zip_ref.extractall(op.join(data_folder, \"baby_example\"))" ] }, { "cell_type": "markdown", "id": "7e8b3c4a", "metadata": {}, "source": [ "## Initialize a GroupAFQ object:\n", "\n", "Now that the data is downloaded and organized in a BIDS-compliant structure,\n", "we can start running pyAFQ on it. We start by initializing a GroupAFQ object.\n", "This object manages all of the data transformations and computations\n", "conducted by the software, based on its initial configuration, which we set\n", "up below.\n", "\n", "A few special things to note here:\n", "\n", "1. We can pass in the T2w file into the `t1_file` argument. The babyAFQ\n", " pipeline needs at least one structural MRI, but it can be T2w or T1w.\n", "2. We use the UNC neonatal template, which can be read on a call to the\n", " `read_pediatric_templates` function in `AFQ.data.fetch`.\n", "3. We use the `baby_bd` to define the bundles that we want to\n", " segment. This dictionary is different from the default behavior in that it\n", " uses the waypoint ROIs from [^Grotheer2021].\n", "4. We set `pve` and `brain_mask_definition` to use BabySeg [^Hoffmann2025].\n", "5. We (optionally) set the ODF model to be CSD instead of the default\n", " asymmetrically filtered CSD." ] }, { "cell_type": "code", "execution_count": null, "id": "b8b52d07", "metadata": {}, "outputs": [], "source": [ "subject_path = op.join(op.expanduser('~'),\n", " \"AFQ_data/baby_example/example_bids_subject\")\n", "dwi_prefix = subject_path + \"/derivatives/vistasoft/sub-01/ses-01/dwi/sub-01_ses-01_dwi\"\n", "\n", "myafq = ParticipantAFQ(\n", " dwi_data_file=dwi_prefix + \".nii.gz\",\n", " bval_file=dwi_prefix + \".bval\",\n", " bvec_file=dwi_prefix + \".bvec\",\n", " t1_file=op.join(\n", " subject_path, \"derivatives/mrtrix/sub-01/ses-01/anat/sub-01_ses-01_desc-t2BiascorrAcpc_dwi.nii.gz\"),\n", " output_dir=op.join(subject_path, \"derivatives/afq\"),\n", " reg_template_spec=afd.read_pediatric_templates()[\"UNCNeo-withCerebellum-for-babyAFQ\"],\n", " bundle_info=abd.baby_bd(),\n", " pve=\"babyseg\",\n", " brain_mask_definition=BabyBrainMask(),\n", " tracking_params=dict(odf_model=\"csd\"),\n", ")" ] }, { "cell_type": "markdown", "id": "bd33ccfb", "metadata": {}, "source": [ "## Running the pipeline\n", "\n", "A call to the `export` function will trigger the pyAFQ pipeline. This will\n", "run tractography, bundle segmentation, and bundle cleaning. The results will\n", "be saved in the `~/AFQ_data/baby_example/derivatives/afq` folder. This can\n", "take a while to run, depending on your computer.\n", "In this case, we call `export` with the `all_bundles_figure` option. This is\n", "because visualizations are created after most other parts of the pipeline\n", "have been run. This means that when this call is done, you should have many\n", "of the derivative results in the output folder, including the tractography,\n", "segmentation, and tract profile results, as well as the visualizations." ] }, { "cell_type": "code", "execution_count": null, "id": "b5b819f5", "metadata": {}, "outputs": [], "source": [ "viz = myafq.export(\"all_bundles_figure\")" ] }, { "cell_type": "markdown", "id": "9add26fb", "metadata": {}, "source": [ "## Viewing the results\n", "One way to view the results is to open the file named\n", "`sub-01_ses-01_dwi_space-RASMM_model-probCSD_algo-AFQ_desc-viz_dwi.html`\n", "in your browser. This is a visualization of the tractography and segmentation\n", "results for all of the bundles. You can navigate this visualization by\n", "clicking on the different bundles in the legend on the right side of the\n", "screen. You can also zoom in and out using the mouse wheel, and rotate the\n", "view by clicking and dragging with the mouse. You can also view the FA tract\n", "profiles in a plot on the left side of the page.\n", "\n", "If the baby bundles appear dark in the html visualization due to low FA values, you\n", "can reduce the upper limit of the range in the `sbv_lims_bundles` option when\n", "building your GroupAFQ object (e.g. `GroupAFQ(..., sbv_lims_bundles=[0, 0.5])`)." ] }, { "cell_type": "code", "execution_count": null, "id": "f38520db", "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "markdown", "id": "35926b9a", "metadata": {}, "source": [ "## References\n", "\n", "[^Grotheer2021]: Grotheer, Mareike, Mona Rosenke, Hua Wu, Holly Kular,\n", " Francesca R. Querdasi, Vaidehi S. Natu, Jason D. Yeatman,\n", " and Kalanit Grill-Spector. \"White matter myelination during\n", " early infancy is linked to spatial gradients and myelin\n", " content at birth.\" Nature communications 13: 997.\n", "\n", "[^Grotheer2023]: Grotheer, Mareike, David Bloom, John Kruper,\n", " Adam Richie-Halford, Stephanie Zika,\n", " Vicente A. Aguilera González, Jason D. Yeatman,\n", " Kalanit Grill-Spector, and Ariel Rokem. \"Human white matter\n", " myelinates faster in utero than ex utero.\" Proceedings\n", " of the National Academy of Sciences 120: e2303491120.\n", "\n", "[^Hoffmann2025]: Hoffmann, Malte, Lilla Zöllei, and Adrian V. Dalca.\n", " \"Deep infant brain segmentation from multi-contrast MRI.\"\n", " Asilomar Conference on Signals, Systems, and Computers,\n", " pp. 974–981. IEEE, 2025.\n", "\n", ":::{only} html\n", "{download}`Download as Jupyter Notebook `\n", ":::" ] } ], "metadata": { "file_format": "mystnb", "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python", "pygments_lexer": "ipython3" }, "mystnb": { "execution_mode": "off" } }, "nbformat": 4, "nbformat_minor": 5 }