Using ggAtlasTrack
Overview
ggAtlasTrack provides ggplot2-based
visualisation tools for AtlasTrack white-matter tract polygons, inspired
by the ggseg ecosystem (Mowinckel & Vidal-Piñeiro,
2020). ggAtlasTrack follows a similar plotting philosophy
for AtlasTrack white-matter tract visualisation, while providing
package-specific view sets and tract-level data mapping. The package can
be used to visualise the AtlasTrack tract atlas or to map tract-level
continuous values, such as coefficients, association statistics, or
significance scores.
Available view sets
The available plotting views can be listed using
atlastrack_views_available().
atlastrack_views_available()
#> view_set display_view view slice_mm view_order
#> 1 axial superior_axial axial 17 1
#> 2 axial mid_axial axial 2 2
#> 3 axial inferior_axial axial -11 3
#> 4 orthogonal axial axial 2 1
#> 5 orthogonal coronal coronal -17 2
#> 6 orthogonal sagittal sagittal -7 3
#> 7 split upper_axial axial 17 1
#> 8 split coronal coronal -17 2
#> 9 split lower_axial axial 2 3Plotting the default view
By default, atlastrack_plot() displays the orthogonal
view set.
This is equivalent to:
Plotting the split-style view
The "split" view displays a split axial/coronal layout
inspired by the visual style of ggseg.
Plotting the axial view
The "axial" view displays inferior, middle, and superior
axial slices. This can be useful for visualising inferior/anterior
tracts, such as the uncinate fasciculus, which cannot be seen in the
default orthogonal or ggseg views.
Listing available tract names
The available tract abbreviations and full tract names can be listed
using atlastrack_tract_names().
atlastrack_tract_names()
#> # A tibble: 35 × 2
#> tract_name tract_full_name
#> <chr> <chr>
#> 1 CC Corpus callosum
#> 2 Fmaj Forceps major
#> 3 Fmin Forceps minor
#> 4 L_ATR Left anterior thalamic radiation
#> 5 L_CgC Left cingulate cingulum
#> 6 L_CgH Left parahippocampal cingulum
#> 7 L_CST Left corticospinal tract
#> 8 L_fSCS Left frontal superior corticostriate tract
#> 9 L_Fx Left fornix
#> 10 L_IFO Left inferior fronto-occipital fasciculus
#> # ℹ 25 more rowsShowing full tract names in the legend
By default, atlastrack_plot() uses abbreviated
AtlasTrack tract names in the legend. Full tract names can be shown
using tract_labels = "full".
This option is useful when preparing explanatory figures or tutorials. For compact manuscript figures, the abbreviated tract labels may be easier to read.
The same option can be used with other view sets:
Plotting tract-level values
Users can provide a data frame containing one row per tract and a continuous value to map onto the atlas.
In this example, we create random tract-level values called
feature_importance.
set.seed(1)
tract_values <- tibble::tibble(
tract_name = unique(atlastrack_tracts$tract_name),
feature_importance = runif(
length(unique(atlastrack_tracts$tract_name)),
0,
0.4
)
)
head(tract_values)
#> # A tibble: 6 × 2
#> tract_name feature_importance
#> <chr> <dbl>
#> 1 R_Fx 0.106
#> 2 L_Fx 0.149
#> 3 R_CgC 0.229
#> 4 L_CgC 0.363
#> 5 R_CgH 0.0807
#> 6 L_CgH 0.359The value argument specifies which column should be
mapped to tract fill.
atlastrack_plot(
data = tract_values,
value = feature_importance,
view_set = "orthogonal",
legend_title = "Feature\nimportance"
)
Setting colour scale limits
By default, the colour scale is based on the range of values in the
supplied data. Setting limits manually can be useful when
comparing plots across models, groups, or datasets.
In the example below, the same values are plotted on a fixed 0–1 scale. Because the simulated values only range from 0 to 0.4, the colours appear less saturated than in the previous plot.
atlastrack_plot(
data = tract_values,
value = feature_importance,
view_set = "orthogonal",
legend_title = "Feature\nimportance",
limits = c(0, 1)
)
Customising colours
The low and high colours can be changed using the low
and high arguments.
atlastrack_plot(
data = tract_values,
value = feature_importance,
view_set = "axial",
low = "orange",
high = "purple",
limits = c(0, max(tract_values$feature_importance, na.rm = TRUE)),
legend_title = "Feature\nimportance"
)
Hiding ventricles
Ventricles are displayed by default. They can be hidden using
show_ventricles = FALSE.
Saving figures
Because atlastrack_plot() returns a ggplot
object, figures can be saved using ggplot2::ggsave().
Notes on interpretation
These plots are two-dimensional visualisations of preprocessed AtlasTrack tract polygons. The view sets are designed to balance anatomical readability and tract coverage.
Some tracts may be more clearly visible in one view set than another. For example, inferior/anterior tracts may be better visualised in the axial view than in the default orthogonal view.
Working with ABCD DTI variables
ABCD DTI data are usually stored in wide format, with one row per participant or participant/time point and one column per tract-specific DTI variable.
For example, an ABCD 6.0 DTI data frame might look like this:
participant_id | session_id | mr_y_dti__fs__fa__at__atr__lh_wmean | mr_y_dti__fs__fa__at__atr__rh_wmean | ...
---------------|-----------|-------------------------------------|-------------------------------------|----
sub-001 | ses-00A | 0.42 | 0.39 | ...
sub-002 | ses-00A | 0.45 | 0.41 | ...ggAtlasTrack includes helper functions for matching ABCD
DTI variable names to the tract names used by
atlastrack_plot().
Looking up ABCD DTI variable names
The atlastrack_abcd_lookup() function returns a lookup
table linking ABCD DTI variable names to AtlasTrack tract names.
By default, it returns ABCD 6.0 full-shell FA variables:
atlastrack_abcd_lookup()
#> tract_name tract_label
#> 1 CC corpus callosum
#> 2 Fmaj forceps major
#> 3 Fmin forceps minor
#> 4 L_ATR L anterior thalamic radiations
#> 5 L_CST L corticospinal tract or pyramidal tract
#> 6 L_CgC L cingulum (cingulate)
#> 7 L_CgH L cingulum (parahippocampal)
#> 8 L_Fx L fornix
#> 9 L_IFO L inferior fronto-occipital fasciculus
#> 10 L_IFSFC L inferior frontal superior frontal cortex
#> 11 L_ILF L inferior longitudinal fasciculus
#> 12 L_SCS L superior corticostriate
#> 13 L_SIFC L striatal inferior frontal cortex
#> 14 L_SLF L superior longitudinal fasciculus
#> 15 L_Unc L uncinate fasciculus
#> 16 L_fSCS L superior corticostriate (frontal)
#> 17 L_pSCS L superior corticostriate (parietal)
#> 18 L_pSLF L parietal superior longitudinal fasciculus
#> 19 L_tSLF L temporal superior longitudinal fasciculus
#> 20 R_ATR R anterior thalamic radiations
#> 21 R_CST R corticospinal tract or pyramidal tract
#> 22 R_CgC R cingulum (cingulate)
#> 23 R_CgH R cingulum (parahippocampal)
#> 24 R_Fx R fornix
#> 25 R_IFO R inferior fronto-occipital fasciculus
#> 26 R_IFSFC R inferior frontal superior frontal cortex
#> 27 R_ILF R inferior longitudinal fasciculus
#> 28 R_SCS R superior corticostriate
#> 29 R_SIFC R striatal inferior frontal cortex
#> 30 R_SLF R superior longitudinal fasciculus
#> 31 R_Unc R uncinate fasciculus
#> 32 R_fSCS R superior corticostriate (frontal)
#> 33 R_pSCS R superior corticostriate (parietal)
#> 34 R_pSLF R parietal superior longitudinal fasciculus
#> 35 R_tSLF R temporal superior longitudinal fasciculus
#> ABCD6_var_name metric shell in_atlastrack_plot
#> 1 mr_y_dti__fs__fa__at__cc_wmean fa fs TRUE
#> 2 mr_y_dti__fs__fa__at__fmaj_wmean fa fs TRUE
#> 3 mr_y_dti__fs__fa__at__fmin_wmean fa fs TRUE
#> 4 mr_y_dti__fs__fa__at__atr__lh_wmean fa fs TRUE
#> 5 mr_y_dti__fs__fa__at__cst__lh_wmean fa fs TRUE
#> 6 mr_y_dti__fs__fa__at__cgc__lh_wmean fa fs TRUE
#> 7 mr_y_dti__fs__fa__at__cgh__lh_wmean fa fs TRUE
#> 8 mr_y_dti__fs__fa__at__fx__lh_wmean fa fs TRUE
#> 9 mr_y_dti__fs__fa__at__ifo__lh_wmean fa fs TRUE
#> 10 mr_y_dti__fs__fa__at__ifsfc__lh_wmean fa fs TRUE
#> 11 mr_y_dti__fs__fa__at__ilf__lh_wmean fa fs TRUE
#> 12 mr_y_dti__fs__fa__at__scs__lh_wmean fa fs TRUE
#> 13 mr_y_dti__fs__fa__at__sifc__lh_wmean fa fs TRUE
#> 14 mr_y_dti__fs__fa__at__slf__lh_wmean fa fs TRUE
#> 15 mr_y_dti__fs__fa__at__unc__lh_wmean fa fs TRUE
#> 16 mr_y_dti__fs__fa__at__fscs__lh_wmean fa fs TRUE
#> 17 mr_y_dti__fs__fa__at__pscs__lh_wmean fa fs TRUE
#> 18 mr_y_dti__fs__fa__at__pslf__lh_wmean fa fs TRUE
#> 19 mr_y_dti__fs__fa__at__tslf__lh_wmean fa fs TRUE
#> 20 mr_y_dti__fs__fa__at__atr__rh_wmean fa fs TRUE
#> 21 mr_y_dti__fs__fa__at__cst__rh_wmean fa fs TRUE
#> 22 mr_y_dti__fs__fa__at__cgc__rh_wmean fa fs TRUE
#> 23 mr_y_dti__fs__fa__at__cgh__rh_wmean fa fs TRUE
#> 24 mr_y_dti__fs__fa__at__fx__rh_wmean fa fs TRUE
#> 25 mr_y_dti__fs__fa__at__ifo__rh_wmean fa fs TRUE
#> 26 mr_y_dti__fs__fa__at__ifsfc__rh_wmean fa fs TRUE
#> 27 mr_y_dti__fs__fa__at__ilf__rh_wmean fa fs TRUE
#> 28 mr_y_dti__fs__fa__at__scs__rh_wmean fa fs TRUE
#> 29 mr_y_dti__fs__fa__at__sifc__rh_wmean fa fs TRUE
#> 30 mr_y_dti__fs__fa__at__slf__rh_wmean fa fs TRUE
#> 31 mr_y_dti__fs__fa__at__unc__rh_wmean fa fs TRUE
#> 32 mr_y_dti__fs__fa__at__fscs__rh_wmean fa fs TRUE
#> 33 mr_y_dti__fs__fa__at__pscs__rh_wmean fa fs TRUE
#> 34 mr_y_dti__fs__fa__at__pslf__rh_wmean fa fs TRUE
#> 35 mr_y_dti__fs__fa__at__tslf__rh_wmean fa fs TRUEThis is equivalent to:
atlastrack_abcd_lookup(
version = "6.0",
metric = "fa",
shell = "fs"
)
#> tract_name tract_label
#> 1 CC corpus callosum
#> 2 Fmaj forceps major
#> 3 Fmin forceps minor
#> 4 L_ATR L anterior thalamic radiations
#> 5 L_CST L corticospinal tract or pyramidal tract
#> 6 L_CgC L cingulum (cingulate)
#> 7 L_CgH L cingulum (parahippocampal)
#> 8 L_Fx L fornix
#> 9 L_IFO L inferior fronto-occipital fasciculus
#> 10 L_IFSFC L inferior frontal superior frontal cortex
#> 11 L_ILF L inferior longitudinal fasciculus
#> 12 L_SCS L superior corticostriate
#> 13 L_SIFC L striatal inferior frontal cortex
#> 14 L_SLF L superior longitudinal fasciculus
#> 15 L_Unc L uncinate fasciculus
#> 16 L_fSCS L superior corticostriate (frontal)
#> 17 L_pSCS L superior corticostriate (parietal)
#> 18 L_pSLF L parietal superior longitudinal fasciculus
#> 19 L_tSLF L temporal superior longitudinal fasciculus
#> 20 R_ATR R anterior thalamic radiations
#> 21 R_CST R corticospinal tract or pyramidal tract
#> 22 R_CgC R cingulum (cingulate)
#> 23 R_CgH R cingulum (parahippocampal)
#> 24 R_Fx R fornix
#> 25 R_IFO R inferior fronto-occipital fasciculus
#> 26 R_IFSFC R inferior frontal superior frontal cortex
#> 27 R_ILF R inferior longitudinal fasciculus
#> 28 R_SCS R superior corticostriate
#> 29 R_SIFC R striatal inferior frontal cortex
#> 30 R_SLF R superior longitudinal fasciculus
#> 31 R_Unc R uncinate fasciculus
#> 32 R_fSCS R superior corticostriate (frontal)
#> 33 R_pSCS R superior corticostriate (parietal)
#> 34 R_pSLF R parietal superior longitudinal fasciculus
#> 35 R_tSLF R temporal superior longitudinal fasciculus
#> ABCD6_var_name metric shell in_atlastrack_plot
#> 1 mr_y_dti__fs__fa__at__cc_wmean fa fs TRUE
#> 2 mr_y_dti__fs__fa__at__fmaj_wmean fa fs TRUE
#> 3 mr_y_dti__fs__fa__at__fmin_wmean fa fs TRUE
#> 4 mr_y_dti__fs__fa__at__atr__lh_wmean fa fs TRUE
#> 5 mr_y_dti__fs__fa__at__cst__lh_wmean fa fs TRUE
#> 6 mr_y_dti__fs__fa__at__cgc__lh_wmean fa fs TRUE
#> 7 mr_y_dti__fs__fa__at__cgh__lh_wmean fa fs TRUE
#> 8 mr_y_dti__fs__fa__at__fx__lh_wmean fa fs TRUE
#> 9 mr_y_dti__fs__fa__at__ifo__lh_wmean fa fs TRUE
#> 10 mr_y_dti__fs__fa__at__ifsfc__lh_wmean fa fs TRUE
#> 11 mr_y_dti__fs__fa__at__ilf__lh_wmean fa fs TRUE
#> 12 mr_y_dti__fs__fa__at__scs__lh_wmean fa fs TRUE
#> 13 mr_y_dti__fs__fa__at__sifc__lh_wmean fa fs TRUE
#> 14 mr_y_dti__fs__fa__at__slf__lh_wmean fa fs TRUE
#> 15 mr_y_dti__fs__fa__at__unc__lh_wmean fa fs TRUE
#> 16 mr_y_dti__fs__fa__at__fscs__lh_wmean fa fs TRUE
#> 17 mr_y_dti__fs__fa__at__pscs__lh_wmean fa fs TRUE
#> 18 mr_y_dti__fs__fa__at__pslf__lh_wmean fa fs TRUE
#> 19 mr_y_dti__fs__fa__at__tslf__lh_wmean fa fs TRUE
#> 20 mr_y_dti__fs__fa__at__atr__rh_wmean fa fs TRUE
#> 21 mr_y_dti__fs__fa__at__cst__rh_wmean fa fs TRUE
#> 22 mr_y_dti__fs__fa__at__cgc__rh_wmean fa fs TRUE
#> 23 mr_y_dti__fs__fa__at__cgh__rh_wmean fa fs TRUE
#> 24 mr_y_dti__fs__fa__at__fx__rh_wmean fa fs TRUE
#> 25 mr_y_dti__fs__fa__at__ifo__rh_wmean fa fs TRUE
#> 26 mr_y_dti__fs__fa__at__ifsfc__rh_wmean fa fs TRUE
#> 27 mr_y_dti__fs__fa__at__ilf__rh_wmean fa fs TRUE
#> 28 mr_y_dti__fs__fa__at__scs__rh_wmean fa fs TRUE
#> 29 mr_y_dti__fs__fa__at__sifc__rh_wmean fa fs TRUE
#> 30 mr_y_dti__fs__fa__at__slf__rh_wmean fa fs TRUE
#> 31 mr_y_dti__fs__fa__at__unc__rh_wmean fa fs TRUE
#> 32 mr_y_dti__fs__fa__at__fscs__rh_wmean fa fs TRUE
#> 33 mr_y_dti__fs__fa__at__pscs__rh_wmean fa fs TRUE
#> 34 mr_y_dti__fs__fa__at__pslf__rh_wmean fa fs TRUE
#> 35 mr_y_dti__fs__fa__at__tslf__rh_wmean fa fs TRUEThe returned table includes the ABCD variable name, the corresponding
ggAtlasTrack tract name, and a descriptive tract label.
Looking up other DTI metrics
To look up other DTI metrics, change the metric
argument.
For mean diffusivity:
atlastrack_abcd_lookup(
version = "6.0",
metric = "md",
shell = "fs"
)
#> tract_name tract_label
#> 1 CC corpus callosum
#> 2 Fmaj forceps major
#> 3 Fmin forceps minor
#> 4 L_ATR L anterior thalamic radiations
#> 5 L_CST L corticospinal tract or pyramidal tract
#> 6 L_CgC L cingulum (cingulate)
#> 7 L_CgH L cingulum (parahippocampal)
#> 8 L_Fx L fornix
#> 9 L_IFO L inferior fronto-occipital fasciculus
#> 10 L_IFSFC L inferior frontal superior frontal cortex
#> 11 L_ILF L inferior longitudinal fasciculus
#> 12 L_SCS L superior corticostriate
#> 13 L_SIFC L striatal inferior frontal cortex
#> 14 L_SLF L superior longitudinal fasciculus
#> 15 L_Unc L uncinate fasciculus
#> 16 L_fSCS L superior corticostriate (frontal)
#> 17 L_pSCS L superior corticostriate (parietal)
#> 18 L_pSLF L parietal superior longitudinal fasciculus
#> 19 L_tSLF L temporal superior longitudinal fasciculus
#> 20 R_ATR R anterior thalamic radiations
#> 21 R_CST R corticospinal tract or pyramidal tract
#> 22 R_CgC R cingulum (cingulate)
#> 23 R_CgH R cingulum (parahippocampal)
#> 24 R_Fx R fornix
#> 25 R_IFO R inferior fronto-occipital fasciculus
#> 26 R_IFSFC R inferior frontal superior frontal cortex
#> 27 R_ILF R inferior longitudinal fasciculus
#> 28 R_SCS R superior corticostriate
#> 29 R_SIFC R striatal inferior frontal cortex
#> 30 R_SLF R superior longitudinal fasciculus
#> 31 R_Unc R uncinate fasciculus
#> 32 R_fSCS R superior corticostriate (frontal)
#> 33 R_pSCS R superior corticostriate (parietal)
#> 34 R_pSLF R parietal superior longitudinal fasciculus
#> 35 R_tSLF R temporal superior longitudinal fasciculus
#> ABCD6_var_name metric shell in_atlastrack_plot
#> 1 mr_y_dti__fs__md__at__cc_wmean md fs TRUE
#> 2 mr_y_dti__fs__md__at__fmaj_wmean md fs TRUE
#> 3 mr_y_dti__fs__md__at__fmin_wmean md fs TRUE
#> 4 mr_y_dti__fs__md__at__atr__lh_wmean md fs TRUE
#> 5 mr_y_dti__fs__md__at__cst__lh_wmean md fs TRUE
#> 6 mr_y_dti__fs__md__at__cgc__lh_wmean md fs TRUE
#> 7 mr_y_dti__fs__md__at__cgh__lh_wmean md fs TRUE
#> 8 mr_y_dti__fs__md__at__fx__lh_wmean md fs TRUE
#> 9 mr_y_dti__fs__md__at__ifo__lh_wmean md fs TRUE
#> 10 mr_y_dti__fs__md__at__ifsfc__lh_wmean md fs TRUE
#> 11 mr_y_dti__fs__md__at__ilf__lh_wmean md fs TRUE
#> 12 mr_y_dti__fs__md__at__scs__lh_wmean md fs TRUE
#> 13 mr_y_dti__fs__md__at__sifc__lh_wmean md fs TRUE
#> 14 mr_y_dti__fs__md__at__slf__lh_wmean md fs TRUE
#> 15 mr_y_dti__fs__md__at__unc__lh_wmean md fs TRUE
#> 16 mr_y_dti__fs__md__at__fscs__lh_wmean md fs TRUE
#> 17 mr_y_dti__fs__md__at__pscs__lh_wmean md fs TRUE
#> 18 mr_y_dti__fs__md__at__pslf__lh_wmean md fs TRUE
#> 19 mr_y_dti__fs__md__at__tslf__lh_wmean md fs TRUE
#> 20 mr_y_dti__fs__md__at__atr__rh_wmean md fs TRUE
#> 21 mr_y_dti__fs__md__at__cst__rh_wmean md fs TRUE
#> 22 mr_y_dti__fs__md__at__cgc__rh_wmean md fs TRUE
#> 23 mr_y_dti__fs__md__at__cgh__rh_wmean md fs TRUE
#> 24 mr_y_dti__fs__md__at__fx__rh_wmean md fs TRUE
#> 25 mr_y_dti__fs__md__at__ifo__rh_wmean md fs TRUE
#> 26 mr_y_dti__fs__md__at__ifsfc__rh_wmean md fs TRUE
#> 27 mr_y_dti__fs__md__at__ilf__rh_wmean md fs TRUE
#> 28 mr_y_dti__fs__md__at__scs__rh_wmean md fs TRUE
#> 29 mr_y_dti__fs__md__at__sifc__rh_wmean md fs TRUE
#> 30 mr_y_dti__fs__md__at__slf__rh_wmean md fs TRUE
#> 31 mr_y_dti__fs__md__at__unc__rh_wmean md fs TRUE
#> 32 mr_y_dti__fs__md__at__fscs__rh_wmean md fs TRUE
#> 33 mr_y_dti__fs__md__at__pscs__rh_wmean md fs TRUE
#> 34 mr_y_dti__fs__md__at__pslf__rh_wmean md fs TRUE
#> 35 mr_y_dti__fs__md__at__tslf__rh_wmean md fs TRUEFor longitudinal diffusivity:
atlastrack_abcd_lookup(
version = "6.0",
metric = "ld",
shell = "fs"
)
#> tract_name tract_label
#> 1 CC corpus callosum
#> 2 Fmaj forceps major
#> 3 Fmin forceps minor
#> 4 L_ATR L anterior thalamic radiations
#> 5 L_CST L corticospinal tract or pyramidal tract
#> 6 L_CgC L cingulum (cingulate)
#> 7 L_CgH L cingulum (parahippocampal)
#> 8 L_Fx L fornix
#> 9 L_IFO L inferior fronto-occipital fasciculus
#> 10 L_IFSFC L inferior frontal superior frontal cortex
#> 11 L_ILF L inferior longitudinal fasciculus
#> 12 L_SCS L superior corticostriate
#> 13 L_SIFC L striatal inferior frontal cortex
#> 14 L_SLF L superior longitudinal fasciculus
#> 15 L_Unc L uncinate fasciculus
#> 16 L_fSCS L superior corticostriate (frontal)
#> 17 L_pSCS L superior corticostriate (parietal)
#> 18 L_pSLF L parietal superior longitudinal fasciculus
#> 19 L_tSLF L temporal superior longitudinal fasciculus
#> 20 R_ATR R anterior thalamic radiations
#> 21 R_CST R corticospinal tract or pyramidal tract
#> 22 R_CgC R cingulum (cingulate)
#> 23 R_CgH R cingulum (parahippocampal)
#> 24 R_Fx R fornix
#> 25 R_IFO R inferior fronto-occipital fasciculus
#> 26 R_IFSFC R inferior frontal superior frontal cortex
#> 27 R_ILF R inferior longitudinal fasciculus
#> 28 R_SCS R superior corticostriate
#> 29 R_SIFC R striatal inferior frontal cortex
#> 30 R_SLF R superior longitudinal fasciculus
#> 31 R_Unc R uncinate fasciculus
#> 32 R_fSCS R superior corticostriate (frontal)
#> 33 R_pSCS R superior corticostriate (parietal)
#> 34 R_pSLF R parietal superior longitudinal fasciculus
#> 35 R_tSLF R temporal superior longitudinal fasciculus
#> ABCD6_var_name metric shell in_atlastrack_plot
#> 1 mr_y_dti__fs__ld__at__cc_wmean ld fs TRUE
#> 2 mr_y_dti__fs__ld__at__fmaj_wmean ld fs TRUE
#> 3 mr_y_dti__fs__ld__at__fmin_wmean ld fs TRUE
#> 4 mr_y_dti__fs__ld__at__atr__lh_wmean ld fs TRUE
#> 5 mr_y_dti__fs__ld__at__cst__lh_wmean ld fs TRUE
#> 6 mr_y_dti__fs__ld__at__cgc__lh_wmean ld fs TRUE
#> 7 mr_y_dti__fs__ld__at__cgh__lh_wmean ld fs TRUE
#> 8 mr_y_dti__fs__ld__at__fx__lh_wmean ld fs TRUE
#> 9 mr_y_dti__fs__ld__at__ifo__lh_wmean ld fs TRUE
#> 10 mr_y_dti__fs__ld__at__ifsfc__lh_wmean ld fs TRUE
#> 11 mr_y_dti__fs__ld__at__ilf__lh_wmean ld fs TRUE
#> 12 mr_y_dti__fs__ld__at__scs__lh_wmean ld fs TRUE
#> 13 mr_y_dti__fs__ld__at__sifc__lh_wmean ld fs TRUE
#> 14 mr_y_dti__fs__ld__at__slf__lh_wmean ld fs TRUE
#> 15 mr_y_dti__fs__ld__at__unc__lh_wmean ld fs TRUE
#> 16 mr_y_dti__fs__ld__at__fscs__lh_wmean ld fs TRUE
#> 17 mr_y_dti__fs__ld__at__pscs__lh_wmean ld fs TRUE
#> 18 mr_y_dti__fs__ld__at__pslf__lh_wmean ld fs TRUE
#> 19 mr_y_dti__fs__ld__at__tslf__lh_wmean ld fs TRUE
#> 20 mr_y_dti__fs__ld__at__atr__rh_wmean ld fs TRUE
#> 21 mr_y_dti__fs__ld__at__cst__rh_wmean ld fs TRUE
#> 22 mr_y_dti__fs__ld__at__cgc__rh_wmean ld fs TRUE
#> 23 mr_y_dti__fs__ld__at__cgh__rh_wmean ld fs TRUE
#> 24 mr_y_dti__fs__ld__at__fx__rh_wmean ld fs TRUE
#> 25 mr_y_dti__fs__ld__at__ifo__rh_wmean ld fs TRUE
#> 26 mr_y_dti__fs__ld__at__ifsfc__rh_wmean ld fs TRUE
#> 27 mr_y_dti__fs__ld__at__ilf__rh_wmean ld fs TRUE
#> 28 mr_y_dti__fs__ld__at__scs__rh_wmean ld fs TRUE
#> 29 mr_y_dti__fs__ld__at__sifc__rh_wmean ld fs TRUE
#> 30 mr_y_dti__fs__ld__at__slf__rh_wmean ld fs TRUE
#> 31 mr_y_dti__fs__ld__at__unc__rh_wmean ld fs TRUE
#> 32 mr_y_dti__fs__ld__at__fscs__rh_wmean ld fs TRUE
#> 33 mr_y_dti__fs__ld__at__pscs__rh_wmean ld fs TRUE
#> 34 mr_y_dti__fs__ld__at__pslf__rh_wmean ld fs TRUE
#> 35 mr_y_dti__fs__ld__at__tslf__rh_wmean ld fs TRUEFor transverse diffusivity:
atlastrack_abcd_lookup(
version = "6.0",
metric = "td",
shell = "fs"
)
#> tract_name tract_label
#> 1 CC corpus callosum
#> 2 Fmaj forceps major
#> 3 Fmin forceps minor
#> 4 L_ATR L anterior thalamic radiations
#> 5 L_CST L corticospinal tract or pyramidal tract
#> 6 L_CgC L cingulum (cingulate)
#> 7 L_CgH L cingulum (parahippocampal)
#> 8 L_Fx L fornix
#> 9 L_IFO L inferior fronto-occipital fasciculus
#> 10 L_IFSFC L inferior frontal superior frontal cortex
#> 11 L_ILF L inferior longitudinal fasciculus
#> 12 L_SCS L superior corticostriate
#> 13 L_SIFC L striatal inferior frontal cortex
#> 14 L_SLF L superior longitudinal fasciculus
#> 15 L_Unc L uncinate fasciculus
#> 16 L_fSCS L superior corticostriate (frontal)
#> 17 L_pSCS L superior corticostriate (parietal)
#> 18 L_pSLF L parietal superior longitudinal fasciculus
#> 19 L_tSLF L temporal superior longitudinal fasciculus
#> 20 R_ATR R anterior thalamic radiations
#> 21 R_CST R corticospinal tract or pyramidal tract
#> 22 R_CgC R cingulum (cingulate)
#> 23 R_CgH R cingulum (parahippocampal)
#> 24 R_Fx R fornix
#> 25 R_IFO R inferior fronto-occipital fasciculus
#> 26 R_IFSFC R inferior frontal superior frontal cortex
#> 27 R_ILF R inferior longitudinal fasciculus
#> 28 R_SCS R superior corticostriate
#> 29 R_SIFC R striatal inferior frontal cortex
#> 30 R_SLF R superior longitudinal fasciculus
#> 31 R_Unc R uncinate fasciculus
#> 32 R_fSCS R superior corticostriate (frontal)
#> 33 R_pSCS R superior corticostriate (parietal)
#> 34 R_pSLF R parietal superior longitudinal fasciculus
#> 35 R_tSLF R temporal superior longitudinal fasciculus
#> ABCD6_var_name metric shell in_atlastrack_plot
#> 1 mr_y_dti__fs__td__at__cc_wmean td fs TRUE
#> 2 mr_y_dti__fs__td__at__fmaj_wmean td fs TRUE
#> 3 mr_y_dti__fs__td__at__fmin_wmean td fs TRUE
#> 4 mr_y_dti__fs__td__at__atr__lh_wmean td fs TRUE
#> 5 mr_y_dti__fs__td__at__cst__lh_wmean td fs TRUE
#> 6 mr_y_dti__fs__td__at__cgc__lh_wmean td fs TRUE
#> 7 mr_y_dti__fs__td__at__cgh__lh_wmean td fs TRUE
#> 8 mr_y_dti__fs__td__at__fx__lh_wmean td fs TRUE
#> 9 mr_y_dti__fs__td__at__ifo__lh_wmean td fs TRUE
#> 10 mr_y_dti__fs__td__at__ifsfc__lh_wmean td fs TRUE
#> 11 mr_y_dti__fs__td__at__ilf__lh_wmean td fs TRUE
#> 12 mr_y_dti__fs__td__at__scs__lh_wmean td fs TRUE
#> 13 mr_y_dti__fs__td__at__sifc__lh_wmean td fs TRUE
#> 14 mr_y_dti__fs__td__at__slf__lh_wmean td fs TRUE
#> 15 mr_y_dti__fs__td__at__unc__lh_wmean td fs TRUE
#> 16 mr_y_dti__fs__td__at__fscs__lh_wmean td fs TRUE
#> 17 mr_y_dti__fs__td__at__pscs__lh_wmean td fs TRUE
#> 18 mr_y_dti__fs__td__at__pslf__lh_wmean td fs TRUE
#> 19 mr_y_dti__fs__td__at__tslf__lh_wmean td fs TRUE
#> 20 mr_y_dti__fs__td__at__atr__rh_wmean td fs TRUE
#> 21 mr_y_dti__fs__td__at__cst__rh_wmean td fs TRUE
#> 22 mr_y_dti__fs__td__at__cgc__rh_wmean td fs TRUE
#> 23 mr_y_dti__fs__td__at__cgh__rh_wmean td fs TRUE
#> 24 mr_y_dti__fs__td__at__fx__rh_wmean td fs TRUE
#> 25 mr_y_dti__fs__td__at__ifo__rh_wmean td fs TRUE
#> 26 mr_y_dti__fs__td__at__ifsfc__rh_wmean td fs TRUE
#> 27 mr_y_dti__fs__td__at__ilf__rh_wmean td fs TRUE
#> 28 mr_y_dti__fs__td__at__scs__rh_wmean td fs TRUE
#> 29 mr_y_dti__fs__td__at__sifc__rh_wmean td fs TRUE
#> 30 mr_y_dti__fs__td__at__slf__rh_wmean td fs TRUE
#> 31 mr_y_dti__fs__td__at__unc__rh_wmean td fs TRUE
#> 32 mr_y_dti__fs__td__at__fscs__rh_wmean td fs TRUE
#> 33 mr_y_dti__fs__td__at__pscs__rh_wmean td fs TRUE
#> 34 mr_y_dti__fs__td__at__pslf__rh_wmean td fs TRUE
#> 35 mr_y_dti__fs__td__at__tslf__rh_wmean td fs TRUEFor ABCD 6.0, shell = "fs" uses full-shell variables and
is the default. Inner-shell variables can be returned using
shell = "is":
atlastrack_abcd_lookup(
version = "6.0",
metric = "fa",
shell = "is"
)
#> tract_name tract_label
#> 1 CC corpus callosum
#> 2 Fmaj forceps major
#> 3 Fmin forceps minor
#> 4 L_ATR L anterior thalamic radiations
#> 5 L_CST L corticospinal tract or pyramidal tract
#> 6 L_CgC L cingulum (cingulate)
#> 7 L_CgH L cingulum (parahippocampal)
#> 8 L_Fx L fornix
#> 9 L_IFO L inferior fronto-occipital fasciculus
#> 10 L_IFSFC L inferior frontal superior frontal cortex
#> 11 L_ILF L inferior longitudinal fasciculus
#> 12 L_SCS L superior corticostriate
#> 13 L_SIFC L striatal inferior frontal cortex
#> 14 L_SLF L superior longitudinal fasciculus
#> 15 L_Unc L uncinate fasciculus
#> 16 L_fSCS L superior corticostriate (frontal)
#> 17 L_pSCS L superior corticostriate (parietal)
#> 18 L_pSLF L parietal superior longitudinal fasciculus
#> 19 L_tSLF L temporal superior longitudinal fasciculus
#> 20 R_ATR R anterior thalamic radiations
#> 21 R_CST R corticospinal tract or pyramidal tract
#> 22 R_CgC R cingulum (cingulate)
#> 23 R_CgH R cingulum (parahippocampal)
#> 24 R_Fx R fornix
#> 25 R_IFO R inferior fronto-occipital fasciculus
#> 26 R_IFSFC R inferior frontal superior frontal cortex
#> 27 R_ILF R inferior longitudinal fasciculus
#> 28 R_SCS R superior corticostriate
#> 29 R_SIFC R striatal inferior frontal cortex
#> 30 R_SLF R superior longitudinal fasciculus
#> 31 R_Unc R uncinate fasciculus
#> 32 R_fSCS R superior corticostriate (frontal)
#> 33 R_pSCS R superior corticostriate (parietal)
#> 34 R_pSLF R parietal superior longitudinal fasciculus
#> 35 R_tSLF R temporal superior longitudinal fasciculus
#> ABCD6_var_name metric shell in_atlastrack_plot
#> 1 mr_y_dti__is__fa__at__cc_wmean fa is TRUE
#> 2 mr_y_dti__is__fa__at__fmaj_wmean fa is TRUE
#> 3 mr_y_dti__is__fa__at__fmin_wmean fa is TRUE
#> 4 mr_y_dti__is__fa__at__atr__lh_wmean fa is TRUE
#> 5 mr_y_dti__is__fa__at__cst__lh_wmean fa is TRUE
#> 6 mr_y_dti__is__fa__at__cgc__lh_wmean fa is TRUE
#> 7 mr_y_dti__is__fa__at__cgh__lh_wmean fa is TRUE
#> 8 mr_y_dti__is__fa__at__fx__lh_wmean fa is TRUE
#> 9 mr_y_dti__is__fa__at__ifo__lh_wmean fa is TRUE
#> 10 mr_y_dti__is__fa__at__ifsfc__lh_wmean fa is TRUE
#> 11 mr_y_dti__is__fa__at__ilf__lh_wmean fa is TRUE
#> 12 mr_y_dti__is__fa__at__scs__lh_wmean fa is TRUE
#> 13 mr_y_dti__is__fa__at__sifc__lh_wmean fa is TRUE
#> 14 mr_y_dti__is__fa__at__slf__lh_wmean fa is TRUE
#> 15 mr_y_dti__is__fa__at__unc__lh_wmean fa is TRUE
#> 16 mr_y_dti__is__fa__at__fscs__lh_wmean fa is TRUE
#> 17 mr_y_dti__is__fa__at__pscs__lh_wmean fa is TRUE
#> 18 mr_y_dti__is__fa__at__pslf__lh_wmean fa is TRUE
#> 19 mr_y_dti__is__fa__at__tslf__lh_wmean fa is TRUE
#> 20 mr_y_dti__is__fa__at__atr__rh_wmean fa is TRUE
#> 21 mr_y_dti__is__fa__at__cst__rh_wmean fa is TRUE
#> 22 mr_y_dti__is__fa__at__cgc__rh_wmean fa is TRUE
#> 23 mr_y_dti__is__fa__at__cgh__rh_wmean fa is TRUE
#> 24 mr_y_dti__is__fa__at__fx__rh_wmean fa is TRUE
#> 25 mr_y_dti__is__fa__at__ifo__rh_wmean fa is TRUE
#> 26 mr_y_dti__is__fa__at__ifsfc__rh_wmean fa is TRUE
#> 27 mr_y_dti__is__fa__at__ilf__rh_wmean fa is TRUE
#> 28 mr_y_dti__is__fa__at__scs__rh_wmean fa is TRUE
#> 29 mr_y_dti__is__fa__at__sifc__rh_wmean fa is TRUE
#> 30 mr_y_dti__is__fa__at__slf__rh_wmean fa is TRUE
#> 31 mr_y_dti__is__fa__at__unc__rh_wmean fa is TRUE
#> 32 mr_y_dti__is__fa__at__fscs__rh_wmean fa is TRUE
#> 33 mr_y_dti__is__fa__at__pscs__rh_wmean fa is TRUE
#> 34 mr_y_dti__is__fa__at__pslf__rh_wmean fa is TRUE
#> 35 mr_y_dti__is__fa__at__tslf__rh_wmean fa is TRUEChecking ABCD variable names by tract
The lookup table can be used to check which ABCD variable names correspond to each AtlasTrack tract.
For example, to return all ABCD 6.0 full-shell FA variable names:
abcd_lookup <- atlastrack_abcd_lookup(
version = "6.0",
metric = "fa",
shell = "fs"
)
abcd_lookup$ABCD6_var_name
#> [1] "mr_y_dti__fs__fa__at__cc_wmean"
#> [2] "mr_y_dti__fs__fa__at__fmaj_wmean"
#> [3] "mr_y_dti__fs__fa__at__fmin_wmean"
#> [4] "mr_y_dti__fs__fa__at__atr__lh_wmean"
#> [5] "mr_y_dti__fs__fa__at__cst__lh_wmean"
#> [6] "mr_y_dti__fs__fa__at__cgc__lh_wmean"
#> [7] "mr_y_dti__fs__fa__at__cgh__lh_wmean"
#> [8] "mr_y_dti__fs__fa__at__fx__lh_wmean"
#> [9] "mr_y_dti__fs__fa__at__ifo__lh_wmean"
#> [10] "mr_y_dti__fs__fa__at__ifsfc__lh_wmean"
#> [11] "mr_y_dti__fs__fa__at__ilf__lh_wmean"
#> [12] "mr_y_dti__fs__fa__at__scs__lh_wmean"
#> [13] "mr_y_dti__fs__fa__at__sifc__lh_wmean"
#> [14] "mr_y_dti__fs__fa__at__slf__lh_wmean"
#> [15] "mr_y_dti__fs__fa__at__unc__lh_wmean"
#> [16] "mr_y_dti__fs__fa__at__fscs__lh_wmean"
#> [17] "mr_y_dti__fs__fa__at__pscs__lh_wmean"
#> [18] "mr_y_dti__fs__fa__at__pslf__lh_wmean"
#> [19] "mr_y_dti__fs__fa__at__tslf__lh_wmean"
#> [20] "mr_y_dti__fs__fa__at__atr__rh_wmean"
#> [21] "mr_y_dti__fs__fa__at__cst__rh_wmean"
#> [22] "mr_y_dti__fs__fa__at__cgc__rh_wmean"
#> [23] "mr_y_dti__fs__fa__at__cgh__rh_wmean"
#> [24] "mr_y_dti__fs__fa__at__fx__rh_wmean"
#> [25] "mr_y_dti__fs__fa__at__ifo__rh_wmean"
#> [26] "mr_y_dti__fs__fa__at__ifsfc__rh_wmean"
#> [27] "mr_y_dti__fs__fa__at__ilf__rh_wmean"
#> [28] "mr_y_dti__fs__fa__at__scs__rh_wmean"
#> [29] "mr_y_dti__fs__fa__at__sifc__rh_wmean"
#> [30] "mr_y_dti__fs__fa__at__slf__rh_wmean"
#> [31] "mr_y_dti__fs__fa__at__unc__rh_wmean"
#> [32] "mr_y_dti__fs__fa__at__fscs__rh_wmean"
#> [33] "mr_y_dti__fs__fa__at__pscs__rh_wmean"
#> [34] "mr_y_dti__fs__fa__at__pslf__rh_wmean"
#> [35] "mr_y_dti__fs__fa__at__tslf__rh_wmean"The lookup table can also be filtered to a specific tract. For example, to find the ABCD 6.0 full-shell FA variable corresponding to the left anterior thalamic radiation:
dplyr::filter(
atlastrack_abcd_lookup(
version = "6.0",
metric = "fa",
shell = "fs"
),
tract_name == "L_ATR"
)
#> tract_name tract_label ABCD6_var_name
#> 1 L_ATR L anterior thalamic radiations mr_y_dti__fs__fa__at__atr__lh_wmean
#> metric shell in_atlastrack_plot
#> 1 fa fs TRUETo look up the corresponding MD variable for the same tract:
dplyr::filter(
atlastrack_abcd_lookup(
version = "6.0",
metric = "md",
shell = "fs"
),
tract_name == "L_ATR"
)
#> tract_name tract_label ABCD6_var_name
#> 1 L_ATR L anterior thalamic radiations mr_y_dti__fs__md__at__atr__lh_wmean
#> metric shell in_atlastrack_plot
#> 1 md fs TRUEThis can be useful when checking that the expected ABCD DTI columns are present before converting a wide ABCD data frame into long tract-wise format.
Converting wide ABCD data to long format
The atlastrack_abcd_to_long() function converts wide
ABCD DTI data into long tract-wise format.
For example, to convert ABCD 6.0 full-shell FA variables:
abcd_fa_long <- atlastrack_abcd_to_long(
data = abcd_data,
version = "6.0",
metric = "fa",
shell = "fs",
id_cols = c("participant_id", "session_id")
)The resulting data frame contains one row per participant, time point, and tract:
participant_id | session_id | tract_name | tract_label | ABCD6_var_name | fa
---------------|-----------|------------|-----------------------------------|-------------------------------------|-----
sub-001 | ses-00A | L_ATR | Left anterior thalamic radiation | mr_y_dti__fs__fa__at__atr__lh_wmean | 0.42
sub-001 | ses-02A | R_ATR | Right anterior thalamic radiation | mr_y_dti__fs__fa__at__atr__rh_wmean | 0.39
sub-002 | ses-00A | L_ATR | Left anterior thalamic radiation | mr_y_dti__fs__fa__at__atr__lh_wmean | 0.45
sub-002 | ses-02A | R_ATR | Right anterior thalamic radiation | mr_y_dti__fs__fa__at__atr__rh_wmean | 0.41To convert MD variables instead, change
metric = "md":
abcd_md_long <- atlastrack_abcd_to_long(
data = abcd_data,
version = "6.0",
metric = "md",
shell = "fs",
id_cols = c("participant_id", "session_id")
)When the input data frame contains multiple DTI metrics, such as FA,
MD, LD, and TD, it is recommended to provide id_cols
explicitly.
Plotting summarised ABCD DTI values
After converting ABCD data to long format, values can be summarised
by tract and passed to atlastrack_plot().
For example, to plot mean FA by tract:
tract_values <- abcd_fa_long |>
dplyr::group_by(tract_name) |>
dplyr::summarise(
mean_fa = mean(fa, na.rm = TRUE),
.groups = "drop"
)
atlastrack_plot(
data = tract_values,
value = mean_fa,
view_set = "orthogonal",
legend_title = "Mean FA"
)The same workflow can be used for other tract-level DTI metrics,
model coefficients, feature-importance scores, or other summary values,
provided the data frame contains a tract_name column
matching the names used by ggAtlasTrack.
References
Hagler, D. J., Jr., Ahmadi, M. E., Kuperman, J., Holland, D., McDonald, C. R., Halgren, E., & Dale, A. M. (2009). Automated white-matter tractography using a probabilistic diffusion tensor atlas: Application to temporal lobe epilepsy. Human Brain Mapping, 30(5), 1535–1547. https://doi.org/10.1002/hbm.20619
Mowinckel, A. M., & Vidal-Piñeiro, D. (2020). Visualization of brain statistics with R packages ggseg and ggseg3d. Advances in Methods and Practices in Psychological Science, 3(4), 466–483. https://doi.org/10.1177/2515245920928009
- Overview
- Available view sets
- Plotting the default view
- Plotting the split-style view
- Plotting the axial view
- Listing available tract names
- Showing full tract names in the legend
- Plotting tract-level values
- Setting colour scale limits
- Customising colours
- Hiding ventricles
- Saving figures
- Notes on interpretation
- Working with ABCD DTI variables
- Looking up ABCD DTI variable names
- Looking up other DTI metrics
- Checking ABCD variable names by tract
- Converting wide ABCD data to long format
- Plotting summarised ABCD DTI values
- References