---
title: "Getting started with ggseg"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with ggseg}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| label: setup
#| include: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6
)
```

If you work with neuroimaging data, you've probably spent time wrestling
region-level results into brain plots. ggseg handles that plumbing for you.
It stores brain atlas geometries as simple features and plots them as ggplot2
layers, so you get brain figures with the same code you'd use for any other
ggplot.

```{r}
#| label: load-packages
library(ggseg)
library(ggplot2)
```

## What's in a brain atlas

A `brain_atlas` object bundles four things: a name, a type (cortical,
subcortical, or tract), region geometry stored as simple features, and an
optional colour palette.

```{r}
#| label: dk-atlas
dk
```

The `dk` atlas (Desikan-Killiany) ships with the package. Call `plot()` for a
quick look:

```{r}
#| label: fig-dk-plot
#| fig-cap: "Quick overview of the Desikan-Killiany cortical atlas."
plot(dk())
```

Two helpers pull out the names you'll need for matching data:

```{r}
#| label: dk-names
ggseg.formats::atlas_regions(dk())
ggseg.formats::atlas_labels(dk())
```

## Your first brain plot

`geom_brain()` works like any ggplot2 geom. Pass it an atlas and it draws
the regions:

```{r}
#| label: fig-basic-brain
#| fig-cap: "Default brain plot using geom_brain() with the dk atlas."
ggplot() +
  geom_brain(atlas = dk())
```

## Arranging views

Brain atlases have multiple views (lateral, medial) and hemispheres.
`position_brain()` controls how they're laid out, using formula syntax
borrowed from `facet_grid()`:

```{r}
#| label: fig-position-formula
#| fig-cap: "Brain views arranged using formula syntax in position_brain()."
ggplot() +
  geom_brain(atlas = dk(), position = position_brain(hemi ~ view))
```

Or reorder views with a character vector:

```{r}
#| label: fig-position-character
#| fig-cap: "Brain views arranged using a character vector to specify order."
ggplot() +
  geom_brain(
    atlas = dk(),
    position = position_brain(c(
      "right lateral", "right medial",
      "left lateral", "left medial"
    ))
  )
```

See `vignette("positioning-views")` for the full set of layout options,
including grid layouts for subcortical and tract atlases.

## Showing only certain hemispheres or views

```{r}
#| label: fig-filter-lateral
#| fig-cap: "Brain plot showing only lateral views."
ggplot() +
  geom_brain(atlas = dk(), view = "lateral")
```

```{r}
#| label: fig-filter-left
#| fig-cap: "Brain plot showing only the left hemisphere."
ggplot() +
  geom_brain(atlas = dk(), hemi = "left")
```

For subcortical atlases, views are slice identifiers. Check what's available
with `ggseg.formats::atlas_views()`:

```{r}
#| label: aseg-views
ggseg.formats::atlas_views(aseg())
```

## Plotting your own data

Create a data frame with at least one column that matches the atlas
(typically `region` or `label`). `geom_brain()` joins your data to the atlas
automatically:

```{r}
#| label: fig-external-data
#| fig-cap: "Brain plot coloured by external p-values using a viridis scale."
library(dplyr)

some_data <- tibble(
  region = c(
    "transverse temporal", "insula", "precentral", "superior parietal"
  ),
  p = sample(seq(0, .5, .001), 4)
)

ggplot(some_data) +
  geom_brain(
    atlas = dk(),
    position = position_brain(hemi ~ view),
    aes(fill = p)
  ) +
  scale_fill_viridis_c(option = "cividis", direction = -1) +
  theme_void()
```

See `vignette("external-data")` for more on data preparation and matching.

## Faceting

ggplot2 faceting works as you'd expect. `geom_brain()` detects faceting
variables and replicates the full atlas in each panel:

```{r}
#| label: fig-faceting
#| fig-cap: "Brain plots faceted by group, each panel showing the full atlas."
some_data <- tibble(
  region = rep(c(
    "transverse temporal", "insula", "precentral", "superior parietal"
  ), 2),
  p = sample(seq(0, .5, .001), 8),
  group = c(rep("A", 4), rep("B", 4))
)

ggplot(some_data) +
  geom_brain(
    atlas = dk(),
    position = position_brain(hemi ~ view),
    aes(fill = p)
  ) +
  facet_wrap(~group)
```

No `group_by()` needed -- the geom handles it.

## Highlighting specific regions

To colour a few regions with their atlas colours, use two columns: one for
the join (`region`) and one for the fill aesthetic:

```{r}
#| label: fig-highlighting
#| fig-cap: "Highlighting selected regions using the atlas colour palette."
data <- data.frame(
  region = ggseg.formats::atlas_regions(dk())[1:3],
  reg_col = ggseg.formats::atlas_regions(dk())[1:3]
)

ggplot(data) +
  geom_brain(atlas = dk(), aes(fill = reg_col)) +
  scale_fill_brain_manual(dk()$palette[data$region])
```

## Scales and themes

Atlas colour palettes are applied automatically by `geom_brain()`. For
custom palettes, use `scale_fill_brain_manual()`.

Built-in themes strip axes and grids for cleaner figures:

```{r}
#| label: themes-example
#| eval: false
ggplot() +
  geom_brain(atlas = dk()) +
  theme_brain()
```

## Finding more atlases

ggseg ships with `dk` (cortical), `aseg` (subcortical), and `tracula`
(white matter tracts). Many more are available through the
[ggsegverse r-universe](https://ggsegverse.r-universe.dev):

```{r}
#| label: install-extra
#| eval: false
install.packages("ggsegYeo2011", repos = "https://ggsegverse.r-universe.dev")
```