### List available example files with read_example()

Source: https://github.com/yunuuuu/ggalign/blob/main/man/read_example.Rd

Call read_example() without arguments to get a character vector of available example file names. This is useful for discovering what example data is bundled with the package.

```r
read_example()
```

--------------------------------

### read_example(file = NULL)

Source: https://github.com/yunuuuu/ggalign/blob/main/man/read_example.Rd

Documentation for the read_example function, which reads example data from a file or lists available example files.

```APIDOC
## read_example(file = NULL)

### Description
This function reads example data from the file. If no file is specified, it returns a list of available example files.

### Usage
read_example(file = NULL)

### Arguments
- **file** (string) - Optional - A string representing the name of the example file to be read. If `NULL`, the function will return a list of available example file names.

### Value
If `file` is `NULL`, returns a character vector of available example file names. Otherwise, returns the contents of the specified example file, read as an R object.

### Examples
```r
read_example()
```
```

--------------------------------

### Create example plots for layout tagging

Source: https://github.com/yunuuuu/ggalign/blob/main/man/layout_tags.Rd

Creates three ggplot objects (p1, p2, p3) used in the subsequent layout tagging examples. These plots are prerequisites for the examples that follow.

```r
p1 <- ggplot(mtcars) +
    geom_point(aes(mpg, disp))
p2 <- ggplot(mtcars) +
    geom_boxplot(aes(gear, disp, group = gear))
p3 <- ggplot(mtcars) +
    geom_bar(aes(gear)) +
    facet_wrap(~cyl)
```

--------------------------------

### Install ggalign development version from GitHub

Source: https://github.com/yunuuuu/ggalign/blob/main/README.Rmd

Installs the development version of ggalign directly from GitHub using the remotes package. Requires the remotes package to be installed first.

```r
# install.packages("remotes")
remotes::install_github("Yunuuuu/ggalign")
```

--------------------------------

### Install ggalign from CRAN

Source: https://github.com/yunuuuu/ggalign/blob/main/README.Rmd

Installs the stable version of ggalign from CRAN. Use this for the official release.

```r
install.packages("ggalign")
```

--------------------------------

### Create a small matrix for circular layout example

Source: https://github.com/yunuuuu/ggalign/blob/main/man/circle_layout.Rd

Sets a random seed and creates a 7x8 matrix with row and column names, used as the data for the circular layout example.

```r
set.seed(123)

small_mat <- matrix(rnorm(56), nrow = 7)
rownames(small_mat) <- paste0("row", seq_len(nrow(small_mat)))
colnames(small_mat) <- paste0("column", seq_len(ncol(small_mat)))
```

--------------------------------

### Create a ggplot inset example

Source: https://github.com/yunuuuu/ggalign/blob/main/man/inset.Rd

This example demonstrates how to create two ggplot objects and embed the second one as an inset within the first using a viewport.

```R
library(grid)
p1 <- ggplot(mtcars) +
    geom_point(aes(mpg, disp))
p2 <- ggplot(mtcars) +
    geom_boxplot(aes(gear, disp, group = gear))
p1 + inset(p2, vp = viewport(0.6, 0.6,
    just = c(0, 0), width = 0.4, height = 0.4
))
```

--------------------------------

### Install ggalign development version from r-universe

Source: https://github.com/yunuuuu/ggalign/blob/main/README.Rmd

Installs the development version of ggalign from the r-universe repository. This provides the latest features before CRAN release.

```r
install.packages("ggalign",
    repos = c("https://yunuuuu.r-universe.dev", "https://cloud.r-project.org")
)
```

--------------------------------

### order2 example with hclust2

Source: https://github.com/yunuuuu/ggalign/blob/main/man/order2.Rd

Shows a basic call to order2() on an hclust object created by hclust2 from random normal data. Use this to obtain the ordering permutation for hierarchical clustering results.

```r
order2(hclust2(matrix(rnorm(100L), nrow = 10L)))
```

--------------------------------

### Create a new Align object with align_dendro()

Source: https://github.com/yunuuuu/ggalign/blob/main/man/align.Rd

This example calls align_dendro() to create a new Align object. It is the only example on the page and demonstrates the basic usage of the align() function.

```R
align_dendro()
```

--------------------------------

### Create example plots for align_plots

Source: https://github.com/yunuuuu/ggalign/blob/main/man/alignpatches.Rd

Creates five ggplot objects (p1 to p5) used in subsequent align_plots examples. Requires ggplot2. The plots are directly copied from patchwork.

```r
p1 <- ggplot(mtcars) +
    geom_point(aes(mpg, disp))
p2 <- ggplot(mtcars) +
    geom_boxplot(aes(gear, disp, group = gear))
p3 <- ggplot(mtcars) +
    geom_bar(aes(gear)) +
    facet_wrap(~cyl)
p4 <- ggplot(mtcars) +
    geom_bar(aes(carb))
p5 <- ggplot(mtcars) +
    geom_violin(aes(cyl, mpg, group = cyl))
```

--------------------------------

### free_guide

Source: https://github.com/yunuuuu/ggalign/blob/main/man/free.Rd

Free specified guide legends from alignment constraints in a plot object.

```APIDOC
## free_guide(plot, guides = "tlbr")

### Description
Free specified guide legends from alignment constraints in a plot object.

### Usage
free_guide(plot, guides = "tlbr")

### Arguments
- **plot** (object) - Required - Any object that can be aligned with `alignpatches()`. In practice, this means the object must implement the `patch()` method.
- **guides** (string) - Optional - A string containing one or more of `"t"`, `"l"`, `"b"`, `"r"`, and `"i"` indicates which side of guide legends should be collected for the plot. If `NULL`, no guide legends will be collected.
```

--------------------------------

### Example: Using geom_magick() with image URLs

Source: https://github.com/yunuuuu/ggalign/blob/main/man/geom_magick.Rd

Creates a data frame with random x, y, image URL, fill, and alpha values, then plots them with geom_magick(). The alpha values are clamped to [0,1].

```R
set.seed(123)
d <- data.frame(
    x = rnorm(10),
    y = rnorm(10),
    image = "https://jeroenooms.github.io/images/frink.png",
    fill = sample(c("A", "B", "C", "D"), 10, replace = TRUE),
    alpha = rnorm(10, mean = 0.5, sd = 0.1)
)
d$alpha <- pmax(pmin(d$alpha, 1), 0)
ggplot(d, aes(x, y)) +
    geom_magick(aes(image = image, fill = fill, alpha = alpha))
```

--------------------------------

### Get Patch representation for a ggplot object

Source: https://github.com/yunuuuu/ggalign/blob/main/man/patch.Rd

Creates a Patch representation for a ggplot object. The Patch object is the layout manager for a single subplot within a composite plot, providing the interface for aligning the subplot, managing panel sizes, and handling guide legends.

```r
patch(ggplot())
```

--------------------------------

### anno_top(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

Source: https://github.com/yunuuuu/ggalign/blob/main/man/quad_active.Rd

A special case of quad_anno with position = "top". Activates the top annotation stack.

```APIDOC
## anno_top(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Description
A special case of quad_anno with position = "top". Activates the top annotation stack.

### Usage
anno_top(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Parameters
- **size** (numeric or unit object) - Optional - Sets the total height of the annotation stack.
- **free_guides** (waiver) - Optional - Override the guides collection behavior specified in quad_layout()/ggheatmap() for the annotation stack.
- **initialize** (boolean) - Optional - Indicates whether the annotation stack should be initialized if not already. Default attempts initialization when data is compatible. If TRUE, no data will be used if incompatible.
- **what** (number or string) - Optional - What should get activated in the annotation stack. If NULL, removes any active context.

### Value
An object that can be added to quad_layout()/ggheatmap().
```

--------------------------------

### anno_right(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

Source: https://github.com/yunuuuu/ggalign/blob/main/man/quad_active.Rd

A special case of quad_anno with position = "right". Activates the right annotation stack.

```APIDOC
## anno_right(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Description
A special case of quad_anno with position = "right". Activates the right annotation stack.

### Usage
anno_right(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Parameters
- **size** (numeric or unit object) - Optional - Sets the total width of the annotation stack.
- **free_guides** (waiver) - Optional - Override the guides collection behavior specified in quad_layout()/ggheatmap() for the annotation stack.
- **initialize** (boolean) - Optional - Indicates whether the annotation stack should be initialized if not already. Default attempts initialization when data is compatible. If TRUE, no data will be used if incompatible.
- **what** (number or string) - Optional - What should get activated in the annotation stack. If NULL, removes any active context.

### Value
An object that can be added to quad_layout()/ggheatmap().
```

--------------------------------

### Create plots, define layout with area(), and apply to align_plots()

Source: https://github.com/yunuuuu/ggalign/blob/main/man/area.Rd

Example from the area() documentation: creates three ggplot objects, defines a layout with area() calls, plots the layout to verify it, then applies it to align_plots() with the design argument.

```r
p1 <- ggplot(mtcars) +
    geom_point(aes(mpg, disp))
p2 <- ggplot(mtcars) +
    geom_boxplot(aes(gear, disp, group = gear))
p3 <- ggplot(mtcars) +
    geom_bar(aes(gear)) +
    facet_wrap(~cyl)

layout <- c(
    area(1, 1),
    area(1, 3, 3),
    area(3, 1, 3, 2)
)

# Show the layout to make sure it looks as it should
plot(layout)

# Apply it to a alignpatches
align_plots(p1, p2, p3, design = layout)
```

--------------------------------

### anno_bottom(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

Source: https://github.com/yunuuuu/ggalign/blob/main/man/quad_active.Rd

A special case of quad_anno with position = "bottom". Activates the bottom annotation stack.

```APIDOC
## anno_bottom(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Description
A special case of quad_anno with position = "bottom". Activates the bottom annotation stack.

### Usage
anno_bottom(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Parameters
- **size** (numeric or unit object) - Optional - Sets the total height of the annotation stack.
- **free_guides** (waiver) - Optional - Override the guides collection behavior specified in quad_layout()/ggheatmap() for the annotation stack.
- **initialize** (boolean) - Optional - Indicates whether the annotation stack should be initialized if not already. Default attempts initialization when data is compatible. If TRUE, no data will be used if incompatible.
- **what** (number or string) - Optional - What should get activated in the annotation stack. If NULL, removes any active context.

### Value
An object that can be added to quad_layout()/ggheatmap().
```

--------------------------------

### anno_left(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

Source: https://github.com/yunuuuu/ggalign/blob/main/man/quad_active.Rd

A special case of quad_anno with position = "left". Activates the left annotation stack.

```APIDOC
## anno_left(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Description
A special case of quad_anno with position = "left". Activates the left annotation stack.

### Usage
anno_left(size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Parameters
- **size** (numeric or unit object) - Optional - Sets the total width of the annotation stack.
- **free_guides** (waiver) - Optional - Override the guides collection behavior specified in quad_layout()/ggheatmap() for the annotation stack.
- **initialize** (boolean) - Optional - Indicates whether the annotation stack should be initialized if not already. Default attempts initialization when data is compatible. If TRUE, no data will be used if incompatible.
- **what** (number or string) - Optional - What should get activated in the annotation stack. If NULL, removes any active context.

### Value
An object that can be added to quad_layout()/ggheatmap().
```

--------------------------------

### Avoid overlapping legends by aligning right annotation

Source: https://github.com/yunuuuu/ggalign/blob/main/man/scheme_align.Rd

Avoids overlapping legends by also collecting guide legends in the right annotation with an additional scheme_align(guides = "r") after the annotation.

```r
# to avoid overlapping, we can also collect the guide legends in the
# right annotation
ggheatmap(mat) -
    scheme_align(guides = NULL) +
    scheme_align(guides = "r") +
    anno_right() +
    align_dendro(aes(color = branch), k = 3) +
    scheme_align(guides = "r")
```

--------------------------------

### Create pairs of observation groups with pair_links()

Source: https://github.com/yunuuuu/ggalign/blob/main/man/pair_links.Rd

Shows how to build a pair_links() object using formulas, integer/character indices, I() for layout ordering, range_link() for ranges, waiver() for inheritance, and NULL for empty links. The resulting object is printed.

```r
x <- pair_links(
    # group on the left hand only
    c("a", "b"),
    # normally, integer index will be interpreted as the index of the
    # origianl data
    1:2,
    # wrapped with `I()` indicate` the integer index is ordering of the
    # layout
    I(1:2),
    range_link(1, 6),
    range_link("a", "b"),
    # group on the right hand only
    ~ 1:2,
    ~ c("a", "b"),
    ~ range_link(1, 6),
    # group on the both side
    range_link(1, 6) ~ c("a", "b"),
    # waiver() indicates the right hand is the same of the left hand
    range_link(1, 6) ~ waiver(),
    # the same for the left hand
    waiver() ~ 1:2,
    ~NULL # an empty link
)
x
```

--------------------------------

### Add alignment for a single plot

Source: https://github.com/yunuuuu/ggalign/blob/main/man/scheme_align.Rd

Adds scheme_align(guides = "r") to a single plot (the heatmap body) to collect guide legends on the right, noting that this may overlap with legends in the right annotation.

```r
# You can also add it for a single plot
ggheatmap(mat) -
    # for all plots in the layout, we default won't collect any guide legends
    scheme_align(guides = NULL) +
    # for the heatmap body, we collect guide legends in the right
    # note, the guide legends will be collected to the right side of the
    # layout which will overlap the legends in the right annotation
    scheme_align(guides = "r") +
    anno_right() +
    align_dendro(aes(color = branch), k = 3)
```

--------------------------------

### geom_magick()

Source: https://github.com/yunuuuu/ggalign/blob/main/man/geom_magick.Rd

Documentation for the geom_magick() ggplot2 layer, including its aesthetics and a usage example.

```APIDOC
## geom_magick()

### Description
Creates a ggplot2 layer that renders images (via the magick package) at specified positions, sizes, and angles. Useful for replacing point symbols with arbitrary images while retaining full control over placement, size, and interpolation.

### Usage
`geom_magick(mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., na.rm = FALSE, show.legend = NA, inherit.aes = TRUE)`

### Aesthetics
- **x** (numeric) - Required - x position
- **y** (numeric) - Required - y position
- **image** (character) - Required - image path or URL
- **alpha** (numeric) - Optional - default `NA` - opacity
- **angle** (numeric) - Optional - default `0` - rotation angle in degrees
- **fill** (character) - Optional - default `NA` - fill color
- **group** - Optional - inferred - grouping
- **hjust** (numeric) - Optional - default `0.5` - horizontal justification
- **size** (numeric) - Optional - via `theme()` - size of the image
- **vjust** (numeric) - Optional - default `0.5` - vertical justification

### Example
```r
set.seed(123)
d <- data.frame(
    x = rnorm(10),
    y = rnorm(10),
    image = "https://jeroenooms.github.io/images/frink.png",
    fill = sample(c("A", "B", "C", "D"), 10, replace = TRUE),
    alpha = rnorm(10, mean = 0.5, sd = 0.1)
)
d$alpha <- pmax(pmin(d$alpha, 1), 0)
ggplot(d, aes(x, y)) +
    geom_magick(aes(image = image, fill = fill, alpha = alpha))
```
```

--------------------------------

### Build circle layout with circle_discrete() and align_dendro()

Source: https://github.com/yunuuuu/ggalign/blob/main/man/circle_switch.Rd

Example usage for circle_switch() context. Creates a small random matrix and builds a circle_discrete() layout with a tile heatmap and a dendrogram alignment, using ggalign(), geom_tile(), scale_fill_viridis_c(), align_dendro(), and scale_color_brewer().

```r
set.seed(123)
small_mat <- matrix(rnorm(56), nrow = 7)
rownames(small_mat) <- paste0("row", seq_len(nrow(small_mat)))
colnames(small_mat) <- paste0("column", seq_len(ncol(small_mat)))
circle_discrete(small_mat) +
    ggalign() +
    geom_tile(aes(y = .column_index, fill = value)) +
    scale_fill_viridis_c() +
    align_dendro(aes(color = branch), k = 3L) +
    scale_color_brewer(palette = "Dark2")
```

--------------------------------

### theme_no_axes() example

Source: https://github.com/yunuuuu/ggalign/blob/main/man/theme_no_axes.Rd

Creates a ggplot object and applies theme_no_axes() to remove all axes, then removes only the bottom axis and only the left axis.

```r
p <- ggplot() +
    geom_point(aes(x = wt, y = qsec), data = mtcars)
p + theme_no_axes()
p + theme_no_axes("b")
p + theme_no_axes("l")
```

--------------------------------

### Fix layout with free_lab

Source: https://github.com/yunuuuu/ggalign/blob/main/man/free.Rd

This example uses `free_lab` on the second plot to fix the layout in a different way, by freeing the labels.

```R
align_plots(p1, free_lab(p2), ncol = 1L)
```

--------------------------------

### Create heatmap layouts with ggheatmap

Source: https://github.com/yunuuuu/ggalign/blob/main/man/heatmap_layout.Rd

Three minimal examples of creating a heatmap layout with ggheatmap, an alias for heatmap_layout. The first uses a numeric vector, the second a character vector, and the third a 9x9 matrix of random normal values. Each call returns a HeatmapLayout object.

```r
ggheatmap(1:10)
```

```r
ggheatmap(letters)
```

```r
ggheatmap(matrix(rnorm(81), nrow = 9L))
```

--------------------------------

### quad_anno(position, size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

Source: https://github.com/yunuuuu/ggalign/blob/main/man/quad_active.Rd

Sets the active context to the specified annotation stack based on the position argument. This allows customization of the top, left, bottom, or right annotation stacks.

```APIDOC
## quad_anno(position, size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Description
Sets the active context to the specified annotation stack based on the position argument.

### Usage
quad_anno(position, size = NULL, free_guides = waiver(), initialize = NULL, what = waiver())

### Parameters
- **position** (string) - Required - A string of "top", "left", "bottom", or "right" indicating which annotation stack should be activated.
- **size** (numeric or unit object) - Optional - Sets the total height/width of the annotation stack. For "top" or "bottom", sets height; for "left" or "right", sets width.
- **free_guides** (waiver) - Optional - Override the guides collection behavior specified in quad_layout()/ggheatmap() for the annotation stack.
- **initialize** (boolean) - Optional - Indicates whether the annotation stack should be initialized if not already. Default attempts initialization when data is compatible. If TRUE, no data will be used if incompatible.
- **what** (number or string) - Optional - What should get activated in the annotation stack. If NULL, removes any active context.

### Value
An object that can be added to quad_layout()/ggheatmap().
```

--------------------------------

### Apply elements to all plots with & operator

Source: https://github.com/yunuuuu/ggalign/blob/main/man/layout-operator.Rd

Use the `&` operator to apply elements to all plots in the layout. This example applies a theme to all plots in a heatmap layout.

```R
ggheatmap(small_mat) +
    anno_top() +
    align_dendro() &
    theme(panel.border = element_rect(
        colour = "red", fill = NA, linewidth = unit(2, "mm")
    ))
```