How to add new bundles into pyAFQ (Optic Radiations Example)¶
pyAFQ is designed to be customizable and extensible. This example shows how you can customize it to define a new bundle based on a definition of waypoint and endpoint ROIs of your design.
In this case, we add the optic radiations, based on work by Caffara et al. The optic radiations (OR) are the primary projection of visual information from the lateral geniculate nucleus of the thalamus to the primary visual cortex. Studying the optic radiations with dMRI provides a linkage between white matter tissue properties, visual perception and behavior, and physiological responses of the visual cortex to visual stimulation.
In [1]:
import os.path as op
import plotly
import numpy as np
from IPython.display import Image
from AFQ.api.group import GroupAFQ
import AFQ.api.bundle_dict as abd
import AFQ.data.fetch as afd
from AFQ.definitions.image import ImageFile, RoiImage
import AFQ.utils.streamlines as aus
np.random.seed(1234)
Get dMRI data¶
We will analyze one subject from the Healthy Brain Network Processed Open Diffusion Derivatives dataset (HBN-POD2). We'll use a fetcher to get preprocessed dMRI data for one of the >2,000 subjects in that study.
In [2]:
study_dir = afd.fetch_hbn_preproc(["NDARAA948VFH"])[1]
Define custom BundleDict object¶
The BundleDict object holds information about "include" and "exclude" ROIs,
as well as endpoint ROIs, and whether the bundle crosses the midline.
In [3]:
or_rois = afd.read_or_templates()
bundles = abd.OR_bd()
Define GroupAFQ object¶
For tractography, we use CSD-based probabilistic tractography seeding
extensively (n_seeds=4 means 81 seeds per voxel!), but only within the ROIs.
In [4]:
brain_mask_definition = ImageFile(
suffix="mask",
filters={'desc': 'brain',
'space': 'T1w',
'scope': 'qsiprep'})
my_afq = GroupAFQ(
bids_path=study_dir,
preproc_pipeline="qsiprep",
participant_labels=["NDARAA948VFH"],
output_dir=op.join(study_dir, "derivatives", "afq_or"),
brain_mask_definition=brain_mask_definition,
tracking_params={"n_seeds": 4,
"directions": "prob",
"odf_model": "CSD",
"seed_mask": RoiImage()},
bundle_info=bundles)
my_afq.export("profiles")
INFO:AFQ:No stop mask given, using FA (or first scalar if none are FA)thresholded to 0.2
Out[4]:
{'NDARAA948VFH': '/Users/john/AFQ_data/HBN/derivatives/afq_or/sub-NDARAA948VFH/ses-HBNsiteRU/dwi/sub-NDARAA948VFH_ses-HBNsiteRU_acq-64dir_desc-profiles_tractography.csv'}
Visualize a montage¶
One way to examine the output of the pyAFQ pipeline is by creating a montage of images of a particular bundle across a group of participants.
In [5]:
my_afq.combine_bundle("Left Optic Radiation")
montage = my_afq.group_montage(
"Left Optic Radiation",
(1, 1), "Axial", "left")
Image(filename=montage[0])
INFO:AFQ:Combining Bundles... 0%| | 0/1 [00:00<?, ?it/s]/Users/john/pyAFQ/AFQ/utils/streamlines.py:93: UserWarning: Pass ['to_space'] as keyword args. From version 2.0.0 passing these as positional arguments will result in an error. sft = load_tractogram(trk_or_trx_file, reference, Space.RASMM) 100%|████████████████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 18.90it/s] INFO:AFQ:Generating Montage... 0%| | 0/1 [00:00<?, ?it/s]INFO:AFQ:Loading Volume... INFO:AFQ:Loading Stateful Tractogram... /Users/john/pyAFQ/AFQ/utils/streamlines.py:93: UserWarning: Pass ['to_space'] as keyword args. From version 2.0.0 passing these as positional arguments will result in an error. INFO:AFQ:Generating colorful lines from tractography... 100%|████████████████████████████████████████████████████████████████████████████████| 1/1 [00:01<00:00, 1.89s/it]
Out[5]:
Interactive bundle visualization¶
Another way to examine the outputs is to export the individual bundle figures, which show the streamlines, as well as the ROIs used to define the bundle.
In [6]:
bundle_html = my_afq.export("indiv_bundles_figures")
plotly.io.show(bundle_html["NDARAA948VFH"]["Left Optic Radiation"])
/Users/john/pyAFQ/AFQ/utils/streamlines.py:93: UserWarning: Pass ['to_space'] as keyword args. From version 2.0.0 passing these as positional arguments will result in an error. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Generating Left Optic Radiation visualization... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Stateful Tractogram... INFO:AFQ:Generating colorful lines from tractography... INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Stateful Tractogram... INFO:AFQ:Generating colorful lines from tractography... INFO:AFQ:Loading Stateful Tractogram... INFO:AFQ:Generating colorful lines from tractography... INFO:AFQ:Generating Right Optic Radiation visualization... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Stateful Tractogram... INFO:AFQ:Generating colorful lines from tractography... INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Resampling skipped as affines already match. INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Preparing ROI... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Stateful Tractogram... INFO:AFQ:Generating colorful lines from tractography... INFO:AFQ:Loading Stateful Tractogram... INFO:AFQ:Generating colorful lines from tractography...
References¶
- Caffarra S, Joo SJ, Bloom D, Kruper J, Rokem A, Yeatman JD. Development of the visual white matter pathways mediates development of electrophysiological responses in visual cortex. Hum Brain Mapp. 2021.
- Caffarra S, Kanopka K, Kruper J, Richie-Halford A, Roy E, Rokem A, Yeatman JD. Development of the alpha rhythm is linked to visual white matter pathways and visual detection performance. bioRxiv.
- Alexander LM, Escalera J, Ai L, et al. An open resource for transdiagnostic research in pediatric mental health and learning disorders. Sci Data. 2017.
- Richie-Halford A, Cieslak M, Ai L, et al. An analysis-ready and quality controlled resource for pediatric brain white-matter research. Scientific Data. 2022.
- Cieslak M, Cook PA, He X, et al. QSIPrep: an integrative platform for preprocessing and reconstructing diffusion MRI data. Nat Methods. 2021.
In [ ]: