---
title: "Using ggAtlasTrack"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using ggAtlasTrack}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 9,
  fig.height = 5.5,
  fig.align = "center",
  out.width = "100%"
)
```

# 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.

```{r setup}
library(ggAtlasTrack)
```

# Available view sets

The available plotting views can be listed using `atlastrack_views_available()`.

```{r available-views}
atlastrack_views_available()
```

# Plotting the default view

By default, `atlastrack_plot()` displays the orthogonal view set.

```{r orthogonal-plot}
atlastrack_plot()
```

This is equivalent to:

```{r orthogonal-code-only, eval = FALSE}
atlastrack_plot(view_set = "orthogonal")
```

# Plotting the split-style view

The `"split"` view displays a split axial/coronal layout inspired by the visual style of ggseg.

```{r split-plot}
atlastrack_plot(view_set = "split")
```

# 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.

```{r axial-plot}
atlastrack_plot(view_set = "axial")
```

# Listing available tract names

The available tract abbreviations and full tract names can be listed using `atlastrack_tract_names()`.

```{r tract-names}
atlastrack_tract_names()
```

# Showing 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"`.

```{r atlas-full-labels}
atlastrack_plot(
  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:

```{r split-full-labels}
atlastrack_plot(
  view_set = "split",
  tract_labels = "full"
)
```

# 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`.

```{r example-data}
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)
```

The `value` argument specifies which column should be mapped to tract fill.

```{r feature-importance-plot}
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.

```{r tract-value-limits}
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.

```{r custom-colours}
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`.

```{r hide-ventricles}
atlastrack_plot(
  view_set = "orthogonal",
  show_ventricles = FALSE
)
```

# Saving figures

Because `atlastrack_plot()` returns a `ggplot` object, figures can be saved using `ggplot2::ggsave()`.

```{r save-figure, eval = FALSE}
p <- atlastrack_plot(view_set = "axial")

ggplot2::ggsave(
  filename = "atlastrack_axial.png",
  plot = p,
  width = 10,
  height = 4,
  dpi = 300
)
```

# 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:

```text
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:

```{r abcd-lookup-default}
atlastrack_abcd_lookup()
```

This is equivalent to:

```{r abcd-lookup-fa}
atlastrack_abcd_lookup(
  version = "6.0",
  metric = "fa",
  shell = "fs"
)
```

The 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:

```{r abcd-lookup-md}
atlastrack_abcd_lookup(
  version = "6.0",
  metric = "md",
  shell = "fs"
)
```

For longitudinal diffusivity:

```{r abcd-lookup-ld}
atlastrack_abcd_lookup(
  version = "6.0",
  metric = "ld",
  shell = "fs"
)
```

For transverse diffusivity:

```{r abcd-lookup-td}
atlastrack_abcd_lookup(
  version = "6.0",
  metric = "td",
  shell = "fs"
)
```

For ABCD 6.0, `shell = "fs"` uses full-shell variables and is the default. Inner-shell variables can be returned using `shell = "is"`:

```{r abcd-lookup-inner-shell}
atlastrack_abcd_lookup(
  version = "6.0",
  metric = "fa",
  shell = "is"
)
```

# Checking 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:

```{r abcd-variable-names}
abcd_lookup <- atlastrack_abcd_lookup(
  version = "6.0",
  metric = "fa",
  shell = "fs"
)

abcd_lookup$ABCD6_var_name
```

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:

```{r abcd-single-tract-fa}
dplyr::filter(
  atlastrack_abcd_lookup(
    version = "6.0",
    metric = "fa",
    shell = "fs"
  ),
  tract_name == "L_ATR"
)
```

To look up the corresponding MD variable for the same tract:

```{r abcd-single-tract-md}
dplyr::filter(
  atlastrack_abcd_lookup(
    version = "6.0",
    metric = "md",
    shell = "fs"
  ),
  tract_name == "L_ATR"
)
```

This 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:

```{r abcd-wide-to-long-fa, eval = FALSE}
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:

```text
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.41
```

To convert MD variables instead, change `metric = "md"`:

```{r abcd-wide-to-long-md, eval = FALSE}
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:

```{r abcd-plot-mean-fa, eval = FALSE}
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