Title: Plotting Tool for Brain Atlases
Version: 1.6.5
Description: Contains 'ggplot2' geom for plotting brain atlases using simple features. The largest component of the package is the data for the two built-in atlases. Mowinckel & Vidal-Piñeiro (2020) <doi:10.1177/2515245920928009>.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.1.2
Depends: R (≥ 3.3)
LazyData: true
LazyDataCompression: xz
Imports: ggplot2 (≥ 3.3), dplyr (≥ 1.0.0), tidyr (≥ 1.0.0), sf (≥ 0.9-2), stats, grid, utils, vctrs
Suggests: knitr, here, rmarkdown, covr, vdiffr, devtools, testthat (≥ 2.1.0), spelling
VignetteBuilder: knitr
URL: https://github.com/ggseg/ggseg
BugReports: https://github.com/ggseg/ggseg/issues
Language: en-US
SystemRequirements: C++11, GDAL (>= 2.0.1), GEOS (>= 3.4.0), PROJ (>= 4.8.0)
NeedsCompilation: no
Packaged: 2022-06-13 10:19:42 UTC; athanasm
Author: Athanasia Mo Mowinckel ORCID iD [aut, cre], Didac Vidal-Piñeiro ORCID iD [aut]
Maintainer: Athanasia Mo Mowinckel <a.m.mowinckel@psykologi.uio.no>
Repository: CRAN
Date/Publication: 2022-06-13 11:10:02 UTC

ggseg: Plot brain segmentations with ggplot

Description

Plotting results from analyses done on data derived from brain segmentations is a common need, but may be quite laborious. Results from such analyses are usually easier to interpret if the plot can mimic the shape and position in the brain it represents.

ggseg plots and returns a ggplot object of plotted aparc regions. Is superseded by the new geom_brain.

Usage

ggseg(
  .data = NULL,
  atlas = "dk",
  position = "dispersed",
  view = NULL,
  hemisphere = NULL,
  adapt_scales = TRUE,
  ...
)

Arguments

.data

A .data.frame to use for plot aesthetics. Should include a column called "region" corresponding to aparc regions.

atlas

Either a string with the name of atlas to use, or a .data.frame containing atlas information (i.e. pre-loaded atlas).

position

String choosing how to view the .data. Either "dispersed"[default] or "stacked".

view

String to choose view of the .data. Any of c("lateral","medial")[default].

hemisphere

String to choose hemisphere to plot. Any of c("left","right")[default].

adapt_scales

if TRUE, then the axes will be hemisphere without ticks. If FALSE, then will be latitude longitude values. Also affected by position argument

...

other options sent to geom_polygon for plotting, including mapping aes (cannot include x, y, and group aesthetics).

Details

This package contains data from various brain parcellations, with convenient functions to inspect the results directly on a brain-plot wither with ggplot (2D polygons).

'dk'

The Desikan-Killiany Cortical Atlas [default], FreeSurfer cortical segmentations.

'aseg'

FreeSurfer automatic subcortical segmentation of a brain volume

Value

a ggplot object

Author(s)

Maintainer: Athanasia Mo Mowinckel a.m.mowinckel@psykologi.uio.no (ORCID)

Authors:

Athanasia Mo Mowinckel and Didac Vidal-Piñeiro

See Also

Useful links:

[ggplot2][ggplot], [aes][aes], [geom_polygon][geom_polygon], [coord_fixed][coord_fixed]

Examples

library(ggplot2)
ggseg()
ggseg(mapping=aes(fill=region))
ggseg(colour="black", size=.7, mapping=aes(fill=region)) + theme_void()
ggseg(position = "stacked")
ggseg(adapt_scales = FALSE)

Scale ggseg plot axes.

Description

adapt_scales returns a list of coordinate breaks and labels for axes or axes label manipulation of the ggseg brain atlases.

Usage

adapt_scales(geobrain, position = "dispersed", aesthetics = "labs")

Arguments

geobrain

a data.frame containing atlas information.

position

String choosing how to view the data. Either "dispersed"[default] or "stacked".

aesthetics

String of which aesthetics to adapt scale of, either "x","y", or "labs".

Value

nested list with coordinates for labels

Create brain atlas

Description

Coerce object into an object of class 'brain_atlas'.

Usage

as_brain_atlas(x)

Arguments

x

object to make into a brain_atlas

Value

an object of class 'brain_atlas'.

Create ggseg atlas

Description

Create ggseg atlas

Usage

as_ggseg_atlas(x)

## Default S3 method:
as_ggseg_atlas(x)

## S3 method for class 'data.frame'
as_ggseg_atlas(x)

## S3 method for class 'ggseg_atlas'
as_ggseg_atlas(x)

## S3 method for class 'brain_atlas'
as_ggseg_atlas(x)

Arguments

x

object to make into a ggseg_atlas

Value

Object of class 'ggseg_atlas'

Freesurfer automatic subcortical segmentation of a brain volume

Description

Coordinate data for the subcortical parcellations implemented in Freesurfer.

Usage

data(aseg)

Format

An object of class brain_atlas of length 4.

Value

An object of class 'brain_atlas' for plotting with ggseg

References

Fischl et al., (2002). Neuron, 33:341-355 (PubMed)

See Also

Other ggseg_atlases: dk

Examples

data(aseg)

Constructor for brain atlas

Description

Creates an object of class 'brain_atlas' that is compatible for plotting using the ggseg-package plot functions

Usage

brain_atlas(atlas, type, data, palette = NULL)

Arguments

atlas

atlas short name, length one

type

atlas type, cortical or subcortical, length one

data

data.frame with atlas data

palette

named character vector of colours

Value

an object of class 'brain_atlas' containing information on atlas name, type, data and palette. To be used in plotting with geom_brain.

Join atlas and data

Description

Joins data frame with a brain-atlas object.

Usage

brain_join(data, atlas, by = NULL)

Arguments

data

data.frame

atlas

atlas data

by

optional character vector of column to join by

Value

either an sf-object (if brain atlas) or a tibble (if ggseg-atlas) with merged atlas and data

Examples

someData = data.frame(
    region = c("transverse temporal", "insula",
                "precentral","superior parietal"),
    p = sample(seq(0,.5,.001), 4),
    stringsAsFactors = FALSE)

brain_join(someData, dk)
brain_join(someData, dk, "region")

Extract unique labels of brain regions

Description

Convenience function to extract names of brain labels from a brain_atlas. Brain labels are usually default naming obtained from the original atlas data.

Usage

brain_labels(x)

## S3 method for class 'ggseg_atlas'
brain_labels(x)

## S3 method for class 'brain_atlas'
brain_labels(x)

Arguments

x

brain atlas

Value

Character vector of atlas region labels

Generate palettes from the ggseg atlases

Description

brain_pal return HEX colours for the different ggseg atlases.

Usage

brain_pal(name, n = "all", direction = 1, unname = FALSE, package = "ggseg")

Arguments

name

String name of atlas

n

Number of colours to return (or "all" [default])

direction

Direction of HEX, -1 reverses order Necessary if applying palette to other data than the brain atlas it comes from.

unname

return unnamed vector (default = FALSE)

package

package to get brain_pals data from (ggseg or ggsegExtra)

Value

vector of colours

Examples

brain_pal("dk")
brain_pal("aseg")

Get info on brain palettes

Description

Get info on brain palettes

Usage

brain_pals_info(package = "ggseg")

Arguments

package

package to get brain_pals data from (ggseg or ggsegExtra)

Value

data.frame with palette information

Examples

brain_pals_info()

Extract unique names of brain regions

Description

Convenience function to extract names of brain regions from a brain_atlas

Usage

brain_regions(x)

## S3 method for class 'ggseg_atlas'
brain_regions(x)

## S3 method for class 'brain_atlas'
brain_regions(x)

## S3 method for class 'data.frame'
brain_regions(x)

Arguments

x

brain atlas

Value

Character vector of brain region names

Desikan-Killiany Cortical Atlas

Description

Coordinate data for the Desikan-Killiany Cortical atlas, with 40 regions in on the cortical surface of the brain.

Usage

data(dk)

Format

An object of class brain_atlas of length 4.

Value

An object of class 'brain_atlas' for plotting with ggseg

References

Fischl et al. (2004) Cerebral Cortex 14:11-22 (PubMed)

See Also

Other ggseg_atlases: aseg

Examples

data(dk)

Brain geom

Description

call to geom_sf

Usage

geom_brain(
  mapping = aes(),
  data = NULL,
  atlas,
  hemi = NULL,
  side = NULL,
  position = position_brain(),
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

mapping

argument to pass to aes to map variables from the supplied data to the plot

data

data.frame with data to plot

atlas

object of type brain_atlas to plot

hemi

hemisphere to plot. Defaults to everything in the atlas.

side

slice to plot, as recorded in the "side" column in the atlas data. Defaults to all.

position

position of the data. Default is "identity" but can be changed by position_brain.

show.legend

logical. Should legend be added or not.

inherit.aes

logical. if aes should be inherited from the main ggplot call or not

...

arguments to geom_sf

Value

ggplot object

Examples

library(ggplot2)

ggplot() +
 geom_brain(atlas = dk)

'ggseg_atlas' class

Description

The 'ggseg_atlas' class is a subclass of ['data.frame'][data.frame()], created in order to have different default behaviour. It heavily relies on the "tibble" ['tbl_df'][tibble()]. [tidyverse](https://www.tidyverse.org/packages/), including [dplyr](http://dplyr.tidyverse.org/), [ggplot2](http://ggplot2.tidyverse.org/), [tidyr](http://tidyr.tidyverse.org/), and [readr](http://readr.tidyverse.org/).

Usage

ggseg_atlas(x)

Arguments

x

data.frame to be made a ggseg-atlas

Value

a tibble with polygon coordinates for plotting brain regions

Properties of 'ggseg_atlas'

Objects of class 'ggseg_atlas' have: * A 'class' attribute of 'c("ggseg_atlas", "tbl_df", "tbl", "data.frame")'. * A base type of '"list"', where each element of the list has the same [NROW()]. * A lot of this script and its functions are taken from the ['tibble'][tibble()]-package

Validate brain atlas

Description

Validate brain atlas

Usage

is_brain_atlas(x)

Arguments

x

an object

Value

logical if object is of class 'brain_atlas'

Validate ggseg_atlas

Description

Validate ggseg_atlas

Usage

is_ggseg_atlas(x)

Arguments

x

an object

Value

logical if object is of class 'ggseg_atlas'

Alter brain atlas position

Description

Function to be used in the position argument in geom_brain to alter the position of the brain slice/views.

Usage

position_brain(position = "horizontal")

Arguments

position

formula describing the rows ~ columns organisation.

Value

a ggproto object

Examples

library(ggplot2)
ggplot() +
  geom_brain(atlas = dk, aes(fill = region),
             position = position_brain(. ~ side + hemi ),
             show.legend = FALSE)

ggplot() +
  geom_brain(atlas = dk, aes(fill = region),
             position = position_brain(side ~ hemi ),
             show.legend = FALSE)

Read in atlas data from all subjects

Description

Recursively reads in all stats files for an atlas (given a unique character string), for all subjects in the subjects directory. Will add hemisphere and subject id to the data.

Usage

read_atlas_files(subjects_dir, atlas)

Arguments

subjects_dir

FreeSurfer subject directory

atlas

unique character combination identifying the atlas

Value

tibble with stats information for subjects from FreeSurfer

Examples

## Not run: 
subj_dir <- "/path/to/freesurfer/7.2.0/subjects/"
read_atlas_files(subj_dir, "aseg.stats")

read_atlas_files(subj_dir, "lh.aparc.stats")

## End(Not run)

Read in raw FreeSurfer stats file

Description

FreeSurfer atlas stats files have a format that can be difficult to easily read in to R. This function takes a raw stats-file from the subjects directory and reads it in as a data.frame.

Usage

read_freesurfer_stats(path, rename = TRUE)

Arguments

path

path to stats file

rename

logical. rename headers for ggseg compatibility

Value

tibble with stats information for subjects from FreeSurfer

Examples

## Not run: 
subj_dir <- "/path/to/freesurfer/7.2.0/subjects/"
aseg_stats <- file.path(subj_dir, "bert/stats/aseg.stats")
read_freesurfer_stats(aseg_stats)

## End(Not run)

Read in stats table from FreeSurfer

Description

FreeSurfer has functions to create tables from raw stats files. If you have data already merged using the aparcstats2table or asegstats2table from FreeSurfer, this function will read in the data and prepare it for ggseg.

Usage

read_freesurfer_table(path, measure = NULL, ...)

Arguments

path

path to the table file

measure

which measure is the table of

...

additional arguments to read.table

Value

tibble with stats information for subjects from FreeSurfer

Examples

## Not run: 
file_path <- "all_subj_aseg.txt"
read_freesurfer_table(file_path)

## End(Not run)

Reposition brain slices

Description

Function for repositioning pre-joined atlas data (i.e. data and atlas already joined to a single data frame). This makes it possible for users to reposition the geometry data for the atlas for control over final plot layout. For even more detailed control over the positioning, the "hemi" and "side" columns should be converted into factors and ordered by wanted order of appearance.

Usage

reposition_brain(data, position = "horizontal")

Arguments

data

sf-data.frame of joined brain atlas and data

position

position formula for slices

Value

sf-data.frame with repositioned slices

Examples

reposition_brain(dk, hemi ~ side)
reposition_brain(dk, side ~ hemi)
reposition_brain(dk, hemi + side ~ .)
reposition_brain(dk, . ~ hemi + side)

Colour and fill scales from the ggseg atlases

Description

The 'brain' palette scales provides scales for the different atlases in the package. Colours are according to the colours used in the papers where the atlases where first introduced.

Usage

scale_brain(
  name = "dk",
  na.value = "grey",
  ...,
  aesthetics = c("fill", "colour", "color")
)

scale_colour_brain(...)

scale_color_brain(...)

scale_fill_brain(...)

Arguments

name

String name of atlas

na.value

String name or hex for the colour of NA entries

...

additional arguments to pass to brain_pal

aesthetics

String vector of which aesthetics to scale c("colour", "color", "fill").

Value

scaling function for altering colour of ggplot aesthetics

Palettes

The following palettes are available for use with these scales:

ggseg -

dk, aseg

ggsegExtra -

tracula, jhu, yeo7, yeo17, glasser, chenAr, chenTh,

Examples

scale_brain()
scale_colour_brain()
scale_fill_brain()

Colour and fill scales from the ggseg atlases

Description

The 'brain' palette scales provides scales for the different atlases in the package. Colours are according to the colours used in the papers where the atlases where first introduced.

Usage

scale_brain2(
  palette,
  na.value = "grey",
  ...,
  aesthetics = c("fill", "colour", "color")
)

scale_colour_brain2(...)

scale_color_brain2(...)

scale_fill_brain2(...)

Arguments

palette

named character vector of regions and colours

na.value

String name or hex for the colour of NA entries

...

additional arguments to pass to brain_pal

aesthetics

String vector of which aesthetics to scale c("colour", "color", "fill").

Value

scaling function for altering colour of ggplot aesthetics

Palettes

The following palettes are available for use with these scales:

ggseg -

dk, aseg

ggsegExtra -

tracula, jhu, yeo7, yeo17, glasser, chenAr, chenTh,

Examples

scale_brain()
scale_colour_brain()
scale_fill_brain()

Axis and label scales from the ggseg atlases

Description

The 'brain' axis and label scales provides scales for the different atlases in the package. These add axis labels and tick labels corresponding to the different atlases.

Usage

scale_continous_brain(
  atlas = dk,
  position = "dispersed",
  aesthetics = c("y", "x")
)

scale_x_brain(...)

scale_y_brain(...)

scale_labs_brain(atlas = dk, position = "dispersed", aesthetics = "labs")

Arguments

atlas

data.frame containing the atlas

position

Character of either "dispersed" or "stacked".

aesthetics

String vector of which aesthetics to scale "x", "y", or "labs".

...

additional arguments to pass to adapt_scales

Value

a scaling function to alter continuous axes labels in ggplot2

Examples

## Not run: 
scale_x_brain()
scale_y_brain()
scale_labs_brain()

## End(Not run)

ggseg plot theme

Description

a set of themes created for the ggseg plots. Use theme() to tweak.

Usage

theme_brain(text.size = 12, text.family = "mono")

theme_darkbrain(text.size = 12, text.family = "mono")

theme_custombrain(
  plot.background = "white",
  text.colour = "darkgrey",
  text.size = 12,
  text.family = "mono"
)

theme_brain2(
  plot.background = "white",
  text.colour = "darkgrey",
  text.size = 12,
  text.family = "mono"
)

Arguments

text.size

Specify size of plot text

text.family

Specify font family

plot.background

Specify fill of plot background ('theme_custombrain' only)

text.colour

Specify colour of plot text

Details

'theme_brain'

Default theme for ggseg. Transparent background, no axis lines, and no grid.

'theme_darkbrain'

Dark equivalent to theme_brain, with black background, and light text.

'theme_custombrain'

Theme for easy customisation of the brain themes.

Value

function that alters the themeing of a ggplot object

Author(s)

Athanasia Mo Mowinckel

See Also

[ggplot()], [aes()], [geom_polygon()], [coord_fixed()] from the ggplot2 package

Examples

library(ggplot2)

ggplot() +
  geom_brain(atlas = dk) +
  theme_brain()

  geom_brain(atlas = dk) +
  theme_darkbrain()