{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n# BabyAFQ : tractometry for infant dMRI data\n\nThe following is an example of tractometry for infant bundles. This example and\nresulting pyAFQ support for pediatric bundles was inspired by and largely due\nto the work of Grotheer et al. [Grotheer2021]_, as implemented in\n[Grotheer2023]_.\n\n

Note

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, "metadata": { "collapsed": false }, "outputs": [], "source": [ "import os.path as op\nimport plotly\nimport wget\nimport zipfile\n\nfrom AFQ.api.group import GroupAFQ\nimport AFQ.api.bundle_dict as abd\nimport AFQ.data.fetch as afd" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Baby dMRI data\n\nInfant MRI data are quite different from data acquired in grownup\nparticipants, and even from children that are just a few years older.\nFirst, there is the rather obvious difference in size. Baby brains are\napproximately 25% the size of grownup brains at birth. But there are also\noften less known differences in brain tissue properties. For example, the\nmyelin content of white matter is much lower in infants than in grownups.\nThis is important because the diffusion signal that we measure with dMRI is\nsensitive to the myelin content, and it means that the dMRI signal differs\nquite a bit in newborn infants. For the purpose of delineating the major\nwhite matter pathways, it is also important to know that their shape,\nlocation and curvature is different in infants than in grownups. For example,\nthe arcuate fasciculus is much more curved in infants than in grownups.\nBecause of this, we use a different set of templates for infant brains than\nfor grownup brains. These templates were created and validated by\nMareike Grotheer and colleagues in [Grotheer2021]_. They are available for\ndownload as part of the pyAFQ software, as we will show below.\n\nIn this example, we will demonstrate the use of pyAFQ on data from one\ninfant. The data, provided by Kalanit Grill Spector's\n`Stanford Vision and Perception Neuroscience Lab `,\nand was previously published in [Grotheer2021]_.\nThe data is available to download on\n`Figshare `.\nYou 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\nyou can download it and unzip it using the following block of code.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "data_folder = op.join(op.expanduser('~'), \"AFQ_data/\")\nbaby_zip = op.join(data_folder, \"baby_example.zip\")\nif 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\nwith zipfile.ZipFile(baby_zip, 'r') as zip_ref:\n zip_ref.extractall(op.join(data_folder, \"baby_example\"))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Initialize a GroupAFQ object:\n\nNow that the data is downloaded and organized in a BIDS-compliant structure,\nwe can start running pyAFQ on it. We start by initializing a GroupAFQ object.\nThis object manages all of the data transformations and computations\nconducted by the software, based on its initial configuration, which we set\nup below.\n\nA few special things to note here:\n\n1. The data were preprocessed using the `vistasoft` pipeline, so we set\n `dwi_preproc_pipeline = \"vistasoft\"`.\n2. We use the UNC neonatal template, which can be read on a call to the\n `read_pediatric_templates` function in `AFQ.data.fetch`.\n3. 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]_.\n4. In this case, tractography has already been run using\n `MRTRIX `, and is accessed using the\n `import_tract` key-word argument.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "myafq = GroupAFQ(\n bids_path=op.join(op.expanduser('~'),\n \"AFQ_data/baby_example/example_bids_subject\"),\n dwi_preproc_pipeline=\"vistasoft\",\n reg_template_spec=afd.read_pediatric_templates(\n )[\"UNCNeo-withCerebellum-for-babyAFQ\"],\n reg_subject_spec=\"b0\",\n bundle_info=abd.baby_bd(),\n import_tract={\n \"suffix\": \"tractography\", \"scope\": \"mrtrix\"},\n)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Running the pipeline\n\nA call to the `export` function will trigger the pyAFQ pipeline. This will\nrun tractography, bundle segmentation, and bundle cleaning. The results will\nbe saved in the `~/AFQ_data/baby_example/derivatives/afq` folder. This can\ntake a while to run, depending on your computer.\nIn this case, we call `export` with the `all_bundles_figure` option. This is\nbecause visualizations are created after most other parts of the pipeline\nhave been run. This means that when this call is done, you should have many\nof the derivative results in the output folder, including the tractography,\nsegmentation, and tract profile results, as well as the visualizations.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "viz = myafq.export(\"all_bundles_figure\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Viewing the results\nOne 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`\nin your browser. This is a visualization of the tractography and segmentation\nresults for all of the bundles. You can navigate this visualization by\nclicking on the different bundles in the legend on the right side of the\nscreen. You can also zoom in and out using the mouse wheel, and rotate the\nview by clicking and dragging with the mouse. You can also view the FA tract\nprofiles in a plot on the left side of the page.\n\nIf the baby bundles appear dark in the html visualization due to low FA values, you\ncan reduce the upper limit of the range in the `sbv_lims_bundles` option when\nbuilding your GroupAFQ object (e.g. `GroupAFQ(..., sbv_lims_bundles=[0, 0.5])`).\n\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## References:\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\u00e1lez, 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" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.13.13" } }, "nbformat": 4, "nbformat_minor": 0 }