How to add new bundles into pyAFQ (Acoustic 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 acoustic radiations.
We start by importing some of the components that we need for this example and fixing the random seed for reproducibility.
import os.path as op
import plotly
import numpy as np
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
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.
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.
ar_rois = afd.read_ar_templates()
bundles = abd.BundleDict({
"Left Acoustic Radiation": {
"start": ar_rois["AAL_Thal_L"],
"end": ar_rois["AAL_TempSup_L"],
"cross_midline": False,
},
"Right Acoustic Radiation": {
"start": ar_rois["AAL_Thal_R"],
"end": ar_rois["AAL_TempSup_R"],
"cross_midline": False
}
})
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.
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_ar"),
brain_mask_definition=brain_mask_definition,
tracking_params={"n_seeds": 4,
"directions": "prob",
"odf_model": "CSD",
"seed_mask": RoiImage(use_endpoints=True)},
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
{'NDARAA948VFH': '/Users/john/AFQ_data/HBN/derivatives/afq_ar/sub-NDARAA948VFH/ses-HBNsiteRU/dwi/sub-NDARAA948VFH_ses-HBNsiteRU_acq-64dir_desc-profiles_tractography.csv'}
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.
bundle_html = my_afq.export("indiv_bundles_figures")
plotly.io.show(bundle_html["NDARAA948VFH"]["Left Acoustic 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:Generating Left Acoustic Radiation visualization... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Stateful Tractogram... INFO:AFQ:Generating colorful lines from tractography... 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... /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... INFO:AFQ:Loading Stateful Tractogram... INFO:AFQ:Generating colorful lines from tractography... INFO:AFQ:Generating Right Acoustic Radiation visualization... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Volume... INFO:AFQ:Loading Stateful Tractogram... INFO:AFQ:Generating colorful lines from tractography... 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...