---
title: "Arranging brain views"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Arranging brain views}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

A brain atlas typically has several views -- lateral and medial for cortical
atlases, or axial, coronal, and sagittal slices for subcortical and tract
atlases. `position_brain()` controls how those views are arranged in the
final plot.

The function works differently depending on the atlas type, so this vignette
covers cortical and subcortical/tract atlases separately.

## Cortical atlases

Cortical atlases like `dk` have two layout dimensions: **hemi** (left or
right) and **view** (lateral, medial, etc.). The formula syntax mirrors
`facet_grid()` -- left side is rows, right side is columns:

```{r}
#| label: fig-hemi-by-view
#| fig-cap: "Cortical atlas with hemispheres as rows and views as columns."
ggplot() +
  geom_brain(
    atlas = dk(),
    position = position_brain(hemi ~ view),
    show.legend = FALSE
  ) +
  theme_void()
```

Flip the formula to transpose the layout:

```{r}
#| label: fig-view-by-hemi
#| fig-cap: "Transposed layout with views as rows and hemispheres as columns."
ggplot() +
  geom_brain(
    atlas = dk(),
    position = position_brain(view ~ hemi),
    show.legend = FALSE
  ) +
  theme_void()
```

### Stacking all views

Use `.` with `+` to collapse everything into a single row or column. This
is handy for compact figures:

```{r}
#| label: fig-single-row
#| fig-cap: "All brain views stacked in a single row."
ggplot() +
  geom_brain(
    atlas = dk(),
    position = position_brain(. ~ hemi + view),
    show.legend = FALSE
  ) +
  theme_void()
```

```{r}
#| label: fig-single-column
#| fig-cap: "All brain views stacked in a single column."
ggplot() +
  geom_brain(
    atlas = dk(),
    position = position_brain(hemi + view ~ .),
    show.legend = FALSE
  ) +
  theme_void()
```

## Subcortical and tract atlases

Subcortical atlases like `aseg` and tract atlases like `tracula` don't have
the hemisphere/view pairing that cortical atlases do. Their views are
individual slices (e.g. `"axial_3"`, `"sagittal"`). That opens up a
different set of positioning tools.

### Horizontal and vertical

The simplest options. `"horizontal"` is the default:

```{r}
#| label: fig-aseg-horizontal
#| fig-cap: "Subcortical atlas views arranged horizontally."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain("horizontal"),
    show.legend = FALSE
  ) +
  theme_void()
```

```{r}
#| label: fig-aseg-vertical
#| fig-cap: "Subcortical atlas views arranged vertically."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain("vertical"),
    show.legend = FALSE
  ) +
  theme_void()
```

### Grid layouts

When you have many views, a grid keeps things readable. Specify `nrow`,
`ncol`, or both:

```{r}
#| label: fig-aseg-nrow
#| fig-cap: "Subcortical atlas views in a two-row grid."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(nrow = 2),
    show.legend = FALSE
  ) +
  theme_void()
```

```{r}
#| label: fig-aseg-ncol
#| fig-cap: "Subcortical atlas views in a three-column grid."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(ncol = 3),
    show.legend = FALSE
  ) +
  theme_void()
```

### Picking specific views

The `views` parameter lets you select which views to include and in what
order. Check what's available with `ggseg.formats::atlas_views()`:

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

```{r}
#| label: fig-aseg-select-views
#| fig-cap: "A subset of subcortical views selected by name."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(
      views = c("sagittal", "axial_3", "coronal_3")
    ),
    show.legend = FALSE
  ) +
  theme_void()
```

Combine `views` with `nrow` or `ncol` for a custom grid:

```{r}
#| label: fig-aseg-custom-grid
#| fig-cap: "Custom two-row grid with selected subcortical views."
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(
      views = c("sagittal", "axial_3", "axial_5", "coronal_3"),
      nrow = 2
    ),
    show.legend = FALSE
  ) +
  theme_void()
```

### Grouping by slice type

The `type ~ .` formula groups views by their orientation -- all axial slices
together, all coronal slices together, and so on. The type is extracted from
the view name (everything before the first underscore):

```{r}
#| label: aseg-type-group
#| eval: false
ggplot() +
  geom_brain(
    atlas = aseg(),
    position = position_brain(type ~ .),
    show.legend = FALSE
  ) +
  theme_void()
```

## Pre-processing with reposition_brain()

If you're using the `geom_sf()` workflow instead of `geom_brain()`, use
`reposition_brain()` to rearrange the data before plotting. It takes the
same arguments:

```{r}
#| label: fig-reposition-brain
#| fig-cap: "Repositioned subcortical data plotted with geom_sf()."
atlas_data <- as.data.frame(aseg())

repositioned <- reposition_brain(
  atlas_data,
  views = c("sagittal", "axial_3", "coronal_3"),
  nrow = 1
)

ggplot(repositioned) +
  geom_sf(aes(fill = region), show.legend = FALSE) +
  theme_void()
```

## Adding view labels

Use `annotate_brain()` to label each view with its name. For cortical
atlases the label combines hemisphere and view (e.g. "left lateral"); for
subcortical and tract atlases it uses the view name directly.

Store the `position_brain()` specification in an object so both layers share
the same layout:

```{r}
#| label: fig-dk-view-labels
#| fig-cap: "Cortical atlas with view labels."
pos <- position_brain(hemi ~ view)
ggplot() +
  geom_brain(atlas = dk(), position = pos, show.legend = FALSE) +
  annotate_brain(atlas = dk(), position = pos) +
  theme_void()
```

It works with any positioning — horizontal, vertical, grid, and formula
layouts:

```{r}
#| label: fig-aseg-view-labels
#| fig-cap: "Subcortical atlas with view labels in a two-row grid."
pos <- position_brain(nrow = 2)
ggplot() +
  geom_brain(atlas = aseg(), position = pos, show.legend = FALSE) +
  annotate_brain(atlas = aseg(), position = pos) +
  theme_void()
```

Text appearance is customisable through standard `annotate()` arguments:

```{r}
#| label: fig-styled-labels
#| fig-cap: "View labels with custom styling."
ggplot() +
  geom_brain(atlas = dk(), show.legend = FALSE) +
  annotate_brain(
    atlas = dk(),
    size = 2.5,
    colour = "grey50",
    fontface = "italic"
  ) +
  theme_void()
```

## Quick reference

| Atlas type | Options |
|---|---|
| Cortical | `hemi ~ view`, `view ~ hemi`, `. ~ hemi + view`, `hemi + view ~ .` |
| Subcortical / Tract | `"horizontal"`, `"vertical"`, `nrow`, `ncol`, `views`, `type ~ .` |