Package 'ggAtlasTrack'

Title: ggplot2 Visualisation Tools for AtlasTrack White Matter Tracts
Description: Provides ggplot2-based two-dimensional visualisations of AtlasTrack white-matter tract polygons in three view sets - orthogonal, ggseg, and axial. Supports categorical tract plots and tract-level continuous values.
Authors: Hollie Byrne [aut, cre], Rachel Visontay [aut], Emma Devine [aut], Lindsay Squeglia [aut], Louise Mewton [aut]
Maintainer: Hollie Byrne <[email protected]>
License: MIT + file LICENSE
Version: 0.1.3
Built: 2026-10-11 15:00:02 UTC
Source: https://github.com/hbyrne07/ggAtlasTrack

Help Index

Show ABCD DTI variable names matched to AtlasTrack tracts

Description

Show ABCD DTI variable names matched to AtlasTrack tracts

Usage

atlastrack_abcd_lookup(
  version = c("6.0", "5.0", "all"),
  metric = "fa",
  shell = "fs",
  only_plotted = TRUE
)

Arguments

version

ABCD data release version. One of "6.0", "5.0", or "all".
metric

DTI metric suffix to use. Defaults to "fa". Other common ABCD DTI metrics include "md", "ld", and "td".
shell

ABCD 6.0 DTI shell to use. Defaults to "fs" for full shell. Use "is" for inner shell.
only_plotted

Logical. If TRUE, return only tracts available in the ggAtlasTrack plotting atlas.

Value

A data frame mapping ABCD DTI variable names to AtlasTrack tract names.

Examples

atlastrack_abcd_lookup(metric = "fa")
atlastrack_abcd_lookup(metric = "md")
atlastrack_abcd_lookup(metric = "fa", shell = "is")

Convert ABCD DTI columns to AtlasTrack long format

Description

Convert ABCD DTI columns to AtlasTrack long format

Usage

atlastrack_abcd_to_long(
  data,
  version = c("6.0", "5.0"),
  metric = "fa",
  shell = "fs",
  id_cols = NULL,
  value_name = NULL,
  only_plotted = TRUE
)

Arguments

data

A data frame containing ABCD DTI variables.
version

ABCD data release version. One of "6.0" or "5.0".
metric

DTI metric suffix to use. Defaults to "fa". Other common ABCD DTI metrics include "md", "ld", and "td".
shell

ABCD 6.0 DTI shell to use. Defaults to "fs" for full shell. Use "is" for inner shell. This argument is ignored for ABCD 5.0.
id_cols

Optional character vector of identifier columns to keep, such as "src_subject_id" or "eventname". Supplying id_cols is recommended, especially when the input data contains multiple DTI metrics.
value_name

Name of the output value column. If NULL, this defaults to the value of metric.
only_plotted

Logical. If TRUE, use only tracts available in the ggAtlasTrack plotting atlas.

Value

A long-format data frame containing identifier columns, tract_name, tract_label, the ABCD variable name, and the DTI value.

Examples

## Not run: 
abcd_fa_long <- atlastrack_abcd_to_long(
  abcd_data,
  version = "6.0",
  metric = "fa",
  shell = "fs",
  id_cols = c("src_subject_id", "eventname")
)

abcd_md_long <- atlastrack_abcd_to_long(
  abcd_data,
  version = "6.0",
  metric = "md",
  shell = "fs",
  id_cols = c("src_subject_id", "eventname")
)

## End(Not run)

ABCD DTI variable lookup for AtlasTrack tracts

Description

A lookup table mapping ABCD 5.0 and ABCD 6.0 DTI variable names to the tract_name values used by ggAtlasTrack.

Usage

atlastrack_abcd_tract_lookup

Format

A data frame with columns:

ABCD5_fa_var_name

ABCD 5.0 FA variable name.

ABCD6_fa_var_name

ABCD 6.0 FA variable name.

tract_name

AtlasTrack tract name used by ggAtlasTrack.

tract_label

Descriptive AtlasTrack tract label.

in_atlastrack_plot

Logical indicator for whether the tract is available in the plotting atlas.

Details

The stored variable names are based on fractional anisotropy (fa) columns. Helper functions such as atlastrack_abcd_lookup() and atlastrack_abcd_to_long() can generate equivalent names for other DTI metrics, such as mean diffusivity (md), longitudinal diffusivity (ld), and transverse diffusivity (td), by replacing the metric suffix.

Source

ABCD DTI variable names were matched to AtlasTrack tract labels.

Examples

atlastrack_abcd_tract_lookup

Convert ABCD 6.0 DTI columns to AtlasTrack long format

Description

Convert ABCD 6.0 DTI columns to AtlasTrack long format

Usage

atlastrack_abcd6_to_long(
  data,
  metric = "fa",
  shell = "fs",
  id_cols = NULL,
  value_name = NULL,
  only_plotted = TRUE
)

Arguments

data

A data frame containing ABCD 6.0 DTI variables.
metric

DTI metric suffix to use. Defaults to "fa".
shell

ABCD 6.0 DTI shell to use. Defaults to "fs" for full shell. Use "is" for inner shell.
id_cols

Optional character vector of identifier columns to keep.
value_name

Name of the output value column. If NULL, this defaults to the value of metric.
only_plotted

Logical. If TRUE, use only tracts available in the ggAtlasTrack plotting atlas.

Value

A long-format data frame.

Examples

## Not run: 
abcd_fa_long <- atlastrack_abcd6_to_long(
  abcd_data,
  metric = "fa",
  shell = "fs",
  id_cols = c("src_subject_id", "eventname")
)

## End(Not run)

AtlasTrack 2D background polygons

Description

A list containing ggseg-style background layers for plotting AtlasTrack.

Usage

atlastrack_background

Format

A list with three sf objects:

gm

Grey matter / cortical background polygons.

wm

White matter cut-out polygons.

vent

Ventricle polygons.

Plot AtlasTrack white-matter tracts

Description

Plot AtlasTrack white-matter tracts

Usage

atlastrack_plot(
  data = NULL,
  value = NULL,
  tract_name = "tract_name",
  view_set = c("orthogonal", "split", "axial"),
  show_ventricles = TRUE,
  tract_labels = c("abbrev", "full"),
  low = "#E8EEF7",
  high = "#2166AC",
  limits = NULL,
  legend_title = NULL
)

Arguments

data

Optional data frame containing tract-level values.
value

Optional unquoted column name in data to map to tract fill.
tract_name

Name of the tract-name column in data.
view_set

View set to plot. One of "orthogonal", "split", or "axial".
show_ventricles

Logical. Whether to show ventricles.
tract_labels

Label style for the categorical tract legend. One of "abbrev" or "full".
low

Low colour for continuous values.
high

High colour for continuous values.
limits

Optional numeric limits for continuous scale.
legend_title

Optional legend title.

Value

A ggplot object.

List available AtlasTrack tract names

Description

List available AtlasTrack tract names

Usage

atlastrack_tract_names()

Value

A data frame containing AtlasTrack tract abbreviations and full names.

AtlasTrack 2D tract polygons

Description

A preprocessed sf object containing two-dimensional AtlasTrack white-matter tract polygons for ggseg-style plotting.

Usage

atlastrack_tracts

Format

An sf object with columns including:

tract_id

Numeric AtlasTrack tract identifier.

tract_name

AtlasTrack tract name.

view_set

View set, either "ggseg" or "orthogonal".

display_view

Displayed panel name.

view

Original anatomical view.

slice_mm

Slice coordinate in MNI space.

view_order

Panel order within view set.

atlas

Atlas name.

type

Atlas type.

hemi

Hemisphere label.

side

Panel side/view label.

region

Region label used for plotting.

label

Region label.

geometry

Polygon geometry.

AtlasTrack available views

Description

Metadata describing the available AtlasTrack 2D plotting views.

Usage

atlastrack_views

Format

A data frame with columns:

view_set

View set, either "ggseg" or "orthogonal".

display_view

Displayed panel name.

view

Original anatomical view.

slice_mm

Slice coordinate in MNI space.

view_order

Panel order within view set.

Show available AtlasTrack views

Description

Show available AtlasTrack views

Usage

atlastrack_views_available()

Value

A data frame of available view sets and display views.