{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n# How to add new bundles into pyAFQ(Optic Radiations Example)\n\npyAFQ is designed to be customizable and extensible. This example shows how you\ncan customize it to define a new bundle based on a definition of waypoint and\nendpoint ROIs of your design.\n\nIn this case, we add the optic radiations, based on work by Caffara et al. [1]_,\n[2]_. The optic radiations (OR) are the primary projection of visual information\nfrom the lateral geniculate nucleus of the thalamus to the primary visual\ncortex. Studying the optic radiations with dMRI provides a linkage between white\nmatter tissue properties, visual perception and behavior, and physiological\nresponses of the visual cortex to visual stimulation.\n\nWe start by importing some of the components that we need for this example and\nfixing the random seed for reproducibility\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "import os.path as op\nimport plotly\nimport numpy as np\nimport shutil\n\nfrom AFQ.api.group import GroupAFQ\nimport AFQ.api.bundle_dict as abd\nimport AFQ.data.fetch as afd\nfrom AFQ.definitions.image import ImageFile, RoiImage\nimport AFQ.utils.streamlines as aus\nnp.random.seed(1234)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Get dMRI data\nWe will analyze one subject from the Healthy Brain Network Processed Open\nDiffusion Derivatives dataset (HBN-POD2) [3]_, [4]_. We'll use a fetcher to\nget preprocessed dMRI data for one of the >2,000 subjects in that study. The\ndata gets organized into a BIDS-compatible format in the `~/AFQ_data/HBN`\nfolder:\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "study_dir = afd.fetch_hbn_preproc([\"NDARAA948VFH\"])[1]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Define custom `BundleDict` object\nThe `BundleDict` object holds information about \"include\" and \"exclude\" ROIs,\nas well as endpoint ROIS, and whether the bundle crosses the midline. In this\ncase, the ROIs are all defined in the MNI template space that is used as the\ndefault template space in pyAFQ, but, in principle, other template spaces\ncould be used.\n\nThe ROIs for the case can be downloaded using a custom fetcher which saves\nthe ROIs to a folder and creates a dictionary of paths to the ROIs:\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "or_rois = afd.read_or_templates()\n\nbundles = abd.OR_bd()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Custom bundle definitions such as the OR, and the standard BundleDict can be\ncombined through addition. To get both the OR and the standard bundles, we\nwould execute the following code::\n\n bundles = bundles + abd.default_bd()\n\nIn this case, we will skip this and generate just the OR.\n\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Define GroupAFQ object\nHBN POD2 have been processed with qsiprep [5]_. This means that a brain mask\nhas already been computer for them. As you can see in other examples, these\ndata also have a mapping calculated for them, which can also be incorporated\ninto processing. However, in this case, we will let pyAFQ calculate its own\nSyN-based mapping so that the `combine_bundle` method can be used below to\ncreate a montage visualization.\n\nFor tractography, we use CSD-based probabilistic tractography seeding\nextensively (`n_seeds=4` means 81 seeds per voxel!), but only within the ROIs\nand not throughout the white matter. This is controlled by passing\n`\"seed_mask\": RoiImage()` in the `tracking_params` dict. The custom bundles\nare passed as `bundle_info=bundles`. The call to `my_afq.export_all()`\ninitiates the pipeline.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "my_afq = GroupAFQ(\n bids_path=study_dir,\n dwi_preproc_pipeline=\"qsiprep\",\n participant_labels=[\"NDARAA948VFH\"],\n output_dir=op.join(study_dir, \"derivatives\", \"afq_or\"),\n tracking_params={\"n_seeds\": 4,\n \"directions\": \"prob\",\n \"odf_model\": \"CSD\",\n \"seed_mask\": RoiImage()},\n bundle_info=bundles)\n\nmy_afq.export_all()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Visualize a montage\nOne way to examine the output of the pyAFQ pipeline is by creating a montage\nof images of a particular bundle across a group of participants (or, in this\ncase, the one participant that was analyzed).\n\n

Note

The montage file is copied to the present working directory so that it gets\n properly rendered into the web-page containing this example. It is not\n necessary to do this when running this type of analysis.

\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "my_afq.combine_bundle(\"Left Optic Radiation\")\nmontage = my_afq.group_montage(\n \"Left Optic Radiation\",\n (1, 1), \"Axial\", \"left\")\nshutil.copy(montage[0], op.split(montage[0])[-1])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Interactive bundle visualization\nAnother way to examine the outputs is to export the individual bundle\nfigures, which show the streamlines, as well as the ROIs used to define the\nbundle. This is an html file, which contains an interactive figure that can\nbe navigated, zoomed, rotated, etc.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "bundle_html = my_afq.export(\"indiv_bundles_figures\")\nplotly.io.show(bundle_html[\"NDARAA948VFH\"][\"Left Optic Radiation\"])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## References\n.. [1] Caffarra S, Joo SJ, Bloom D, Kruper J, Rokem A, Yeatman JD. Development\n of the visual white matter pathways mediates development of\n electrophysiological responses in visual cortex. Hum Brain Mapp.\n 2021;42(17):5785-5797.\n\n.. [2] Caffarra S, Kanopka K, Kruper J, Richie-Halford A, Roy E, Rokem A,\n Yeatman JD. Development of the alpha rhythm is linked to visual white\n matter pathways and visual detection performance. bioRxiv.\n doi:10.1101/2022.09.03.506461\n\n.. [3] Alexander LM, Escalera J, Ai L, et al. An open resource for\n transdiagnostic research in pediatric mental health and learning\n disorders. Sci Data. 2017;4:170181.\n\n.. [4] Richie-Halford A, Cieslak M, Ai L, et al. An analysis-ready and quality\n controlled resource for pediatric brain white-matter research. Scientific\n Data. 2022;9(1):1-27.\n\n.. [5] Cieslak M, Cook PA, He X, et al. QSIPrep: an integrative platform for\n preprocessing and reconstructing diffusion MRI data. Nat Methods.\n 2021;18(7):775-778.\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 }