Package 'ggseg'

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)

p <- ggplot() +
  geom_brain(atlas = dk)

p +
  theme_brain()

p +
  theme_darkbrain()

---