### circle_discrete Example

Source: https://yunuuuu.github.io/ggalign/reference/circle_switch.html

An example demonstrating the use of circle_discrete with ggalign, geom_tile, and align_dendro.

```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")
```

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

### List available example files

Source: https://yunuuuu.github.io/ggalign/reference/read_example.html

Calling read_example without arguments returns a character vector of available example file names.

```R
read_example()
#> [1] "gene_expression.rds"   "measles.rds"           "ref_cytoband_hg19.rds"
#> [4] "ref_cytoband_hg38.rds"
```

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

### read_example(file = NULL)

Source: https://yunuuuu.github.io/ggalign/reference/read_example.html

Reads example data from a file. If no file is specified, returns a list of available example file names.

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

### Description
Reads example data from a file. If no file is specified, returns a list of available example file names.

### 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()
#> [1] "gene_expression.rds"   "measles.rds"           "ref_cytoband_hg19.rds"
#> [4] "ref_cytoband_hg38.rds"
```
```

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

### Heatmap Layout Examples

Source: https://yunuuuu.github.io/ggalign/reference/heatmap_layout.html

Basic examples demonstrating the creation of heatmaps using the ggheatmap alias with different input types.

```R
ggheatmap(1:10)
#> → heatmap built with `geom_tile()`

ggheatmap(letters)
#> → heatmap built with `geom_tile()`

ggheatmap(matrix(rnorm(81), nrow = 9L))
#> → heatmap built with `geom_tile()`
```

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

### Install ggalign from GitHub

Source: https://yunuuuu.github.io/ggalign-book/introduction.html

Use the remotes package to install the latest version directly from the GitHub repository.

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

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

### Stack Layout Examples

Source: https://yunuuuu.github.io/ggalign/reference/stack_layout.html

Examples demonstrating horizontal and vertical plot stacking using stack_horizontal, stack_discrete, and stack_vertical.

```R
set.seed(123)
small_mat <- matrix(rnorm(56), nrow = 7L)

stack_horizontal(small_mat) + align_dendro()


# this is the same with:
stack_discrete("h", small_mat) + align_dendro()


stack_discreteh(small_mat) + align_dendro()


# For vertical layout:
stack_vertical(small_mat) + align_dendro()
```

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

### Install ggalign development version from r-universe

Source: https://yunuuuu.github.io/ggalign-book/introduction.html

Use this command to install the development version from the yunuuuu r-universe repository.

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

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

### Circular layout examples

Source: https://yunuuuu.github.io/ggalign/reference/circle_layout.html

Examples demonstrating the use of circle_layout, circle_discrete, and circle_continuous with various datasets and configurations.

```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_layout
# same for circle_discrete()
circle_layout(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")


# same for circle_continuous()
circle_layout(mpg, limits = continuous_limits(c(3, 5))) +
    ggalign(mapping = aes(displ, hwy, colour = class)) +
    geom_point(size = 2) +
    ggalign(mapping = aes(displ, hwy, colour = class)) +
    geom_point(size = 2) &
    scale_color_brewer(palette = "Dark2") &
    theme_bw()


# circle_discrete()
# direction outward
circle_discrete(small_mat) +
    align_dendro(aes(color = branch), k = 3L) +
    scale_color_brewer(palette = "Dark2") +
    ggalign() +
    geom_tile(aes(y = .column_index, fill = value)) +
    scale_fill_viridis_c()


# direction inward
circle_discrete(small_mat, direction = "inward") +
    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")


# circle_continuous()
circle_continuous(mpg, limits = continuous_limits(c(3, 5))) +
    ggalign(mapping = aes(displ, hwy, colour = class)) +
    geom_point(size = 2) +
    ggalign(mapping = aes(displ, hwy, colour = class)) +
    geom_point(size = 2) &
    scale_color_brewer(palette = "Dark2") &
    theme_bw()
```

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

### Set guides for dendrogram in top annotation

Source: https://yunuuuu.github.io/ggalign-book/schemes.html

Demonstrates setting guides for a dendrogram within a top annotation, noting that annotation stacks collect their own guides before passing them to the top-level layout.

```R
heatmap_collect_all_guides -
    # we set global `guides` argument for `the heatmap layout`
    # we only collect guides in the top side in the heatmap layout
    quad_scope(scheme_align(guides = "t"), NULL) +
    # `+` apply it to the active plot
    # for the dendrogram in the top annotation, we collect guide in the left side
    quad_scope(scheme_align(guides = "l"), "t")
#> → heatmap built with `geom_tile()`
```

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

### Define example plots

Source: https://yunuuuu.github.io/ggalign-book/plot-composer.html

Creates five basic ggplot objects for use in subsequent layout examples.

```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))
```

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

### Install ggalign from CRAN

Source: https://yunuuuu.github.io/ggalign-book/introduction.html

Use this command to install the stable version of the package from CRAN.

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

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

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

Source: https://yunuuuu.github.io/ggalign/reference/free.html

Specifies which side of guide legends should be collected for the plot.

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

### Description
Specifies which side of guide legends should be collected for the plot.

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

### Arguments
- **plot** - Any object that can be aligned with alignpatches(). In practice, this means the object must implement the patch() method.
- **guides** - 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.
```

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

### raster_magick usage and examples

Source: https://yunuuuu.github.io/ggalign/reference/raster_magick.html

The usage section shows the function signature. The example requires R >= 4.1.0 and the magick package. It creates a heatmap with rasterized tiles at a resolution of 20, and a second example applies a Lanczos filter to resize the image by 50%.

```R
raster_magick(x, ...)
```

```R
# Currently, `magick` package require R >= 4.1.0
if (requireNamespace("magick")) {
    # data generated code was copied from `ComplexHeatmap`
    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)))
    ggheatmap(small_mat, aes(.x, .y), filling = NULL) +
        raster_magick(geom_tile(aes(fill = value)), res = 20)

    ggheatmap(small_mat, aes(.x, .y), filling = NULL) +
        # Use `magick::filter_types()` to check available `filter` arguments
        raster_magick(
            geom_tile(aes(fill = value)),
            magick = function(image) {
                magick::image_resize(image,
                    geometry = "50%x", filter = "Lanczos"
                )
            }
        )
}
```

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

### free_guide()

Source: https://yunuuuu.github.io/ggalign-book/free.html

Overrides guides collection behavior in align_plots().

```APIDOC
## free_guide()

### Description
Overrides guides collection behavior in align_plots().

### Usage
free_guide(...)

### Arguments
- ... - Guide collection behavior overrides.
```

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

### Collect guide legends on the top side

Source: https://yunuuuu.github.io/ggalign-book/schemes.html

Use the guides argument in scheme_align to specify which side of guide legends should be gathered. This example collects legends only on the top (t) side.

```R
heatmap_collect_all_guides -
    # we set global `guides` argument for `the heatmap layout`
    # we only collect guides in the top side
    quad_scope(scheme_align(guides = "t"), NULL)
#> → heatmap built with `geom_tile()`
```

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

### Read GISTIC data and create oncoplot with ggoncoplot

Source: https://yunuuuu.github.io/ggalign-book/oncoplot.html

Loads example GISTIC files from the maftools package, reads them with maftools::readGistic, and creates an oncoplot with ggoncoplot. The output shows processing messages from readGistic. Requires the maftools package to be installed.

```R
# Ensure the maftools package is installed and load the example GISTIC data
all.lesions <- system.file("extdata", "all_lesions.conf_99.txt", package = "maftools")
amp.genes <- system.file("extdata", "amp_genes.conf_99.txt", package = "maftools")
del.genes <- system.file("extdata", "del_genes.conf_99.txt", package = "maftools")
scores.gistic <- system.file("extdata", "scores.gistic", package = "maftools")
laml.gistic <- maftools::readGistic(
    gisticAllLesionsFile = all.lesions, gisticAmpGenesFile = amp.genes,
    gisticDelGenesFile = del.genes, gisticScoresFile = scores.gistic
)
#> -Processing Gistic files..
#> --Processing amp_genes.conf_99.txt
#> --Processing del_genes.conf_99.txt
#> --Processing scores.gistic
#> --Summarizing by samples
ggoncoplot(laml.gistic) +
    scale_fill_brewer("CNV", palette = "Dark2", na.translate = FALSE) +
    theme_no_axes("x")
```

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

### free_guide(plot, guides)

Source: https://yunuuuu.github.io/ggalign-book/free.html

Overrides the guides argument for a single plot. The first argument is the plot, and the second argument specifies the guide positions to collect (or NULL to disable guides).

```APIDOC
## free_guide(plot, guides)

### Description
Overrides the `guides` argument for a single plot. This allows you to control which guide positions are collected for that plot when used in an alignment.

### Usage
`free_guide(plot, guides)`

### Arguments
- **plot** (ggplot object) - Required - The plot for which to override the guides.
- **guides** (character or NULL) - Required - The guide positions to collect. Use NULL to disable guides, or a character vector of positions (e.g., "r", "b", "t", "l").

### Example
```r
p_right <- ggplot(mtcars) +
    geom_point(aes(hp, wt, colour = mpg)) +
    patch_titles("right") +
    labs(color = "right")

align_plots(
    free_guide(p_right, NULL),
    free_guide(p_bottom, NULL),
    free_guide(p_top, NULL),
    free_guide(p_left, NULL),
    guides = "tlbr"
)
```

### Example with specific positions
```r
align_plots(
    free_guide(p_right, "r"),
    free_guide(p_bottom, "b"),
    free_guide(p_top, "t"),
    free_guide(p_left, "l")
)
```
```

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

### Usage of read_example

Source: https://yunuuuu.github.io/ggalign/reference/read_example.html

The basic syntax for calling the read_example function.

```R
read_example(file = NULL)
```

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

### align_kmeans Example

Source: https://yunuuuu.github.io/ggalign/reference/align_kmeans.html

Example of using align_kmeans with a heatmap.

```R
ggheatmap(matrix(rnorm(81), nrow = 9)) +
    anno_top() +
    align_kmeans(3L)
#> → heatmap built with `geom_tile()`
```

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

### Create example plots for align_plots

Source: https://yunuuuu.github.io/ggalign/reference/alignpatches.html

This example creates five ggplot objects (p1 through p5) using the mtcars dataset. These plots are used in the subsequent align_plots() examples.

```R
# directly copied from patchwork
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))
```

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

### Examples of layout verification

Source: https://yunuuuu.github.io/ggalign/reference/is_layout.html

Demonstrates checking various layout objects using is_layout, is_quad_layout, is_stack_layout, is_heatmap_layout, and is_ggheatmap.

```R
is_layout(ggheatmap(1:10))
#> [1] TRUE

# for quad_layout()
is_quad_layout(quad_alignb(1:10))
#> [1] TRUE
is_quad_layout(quad_alignh(1:10))
#> [1] TRUE
is_quad_layout(quad_alignv(1:10))
#> [1] TRUE
is_quad_layout(quad_free(mtcars))
#> [1] TRUE

# for stack_layout()
is_stack_layout(stack_discrete("h", 1:10))
#> [1] TRUE
is_stack_layout(stack_continuous("h", 1:10))
#> [1] TRUE

# for heatmap_layout()
is_heatmap_layout(ggheatmap(1:10))
#> [1] TRUE
is_ggheatmap(ggheatmap(1:10))
#> [1] TRUE
```

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

### Patch$setup

Source: https://yunuuuu.github.io/ggalign/reference/Patch-ggproto.html

Sets up the options and data for the plot. This is an optional method.

```APIDOC
## Patch$setup

### Description
(Optional method) Sets up the `options` and `data` for the plot.

### Arguments
- `options` : A `patch_options` object that contains various layout options.

### Returns
No explicit return value documented.
```

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

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

Source: https://yunuuuu.github.io/ggalign/reference/quad_active.html

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"`. Sets the active context to the top annotation stack.

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

### Arguments
- **size** (numeric or unit) - Optional - A numeric value or an `unit` object to set the total `height` of the annotation stack.
- **free_guides** - Optional - Override the `guides` collection behavior specified in the `quad_layout()`/`ggheatmap()` for the annotation stack.
- **initialize** (boolean) - Optional - A boolean indicating whether the annotation stack should be initialized if it is not already.
- **what** - Optional - What should get activated in the annotation stack? A single number or string of the plot elements in the layout. If `NULL`, will remove any active context.

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

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

### align_group example

Source: https://yunuuuu.github.io/ggalign/reference/align_group.html

Example demonstrating the use of align_group within a ggheatmap layout.

```R
set.seed(1L)
small_mat <- matrix(rnorm(81), nrow = 9)
ggheatmap(small_mat) +
    anno_top() +
    align_group(sample(letters[1:4], ncol(small_mat), replace = TRUE))
#> → heatmap built with `geom_tile()`
```

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

### geom_tile3d Usage Example

Source: https://yunuuuu.github.io/ggalign/reference/geom_rect3d.html

Example of using geom_tile3d with ggheatmap to create a 3D heatmap.

```APIDOC
## geom_tile3d Usage Example

### Description
Example of using geom_tile3d with ggheatmap to create a 3D heatmap.

### Example Code
```r
set.seed(123)
small_mat <- matrix(rnorm(81), nrow = 9)
rownames(small_mat) <- paste0("row", seq_len(nrow(small_mat)))
colnames(small_mat) <- paste0("column", seq_len(ncol(small_mat)))
ggheatmap(small_mat,
    filling = FALSE,
    theme = theme(
        legend.box.spacing = unit(10, "mm"),
        plot.margin = margin(t = 15, unit = "mm")
    )
) +
    geom_tile3d(
        aes(fill = value, z = value, width = 0.8, height = 0.8),
        color = "black"
    ) +
    scale_fill_viridis_c(
        option = "plasma",
        breaks = scales::breaks_pretty(3L)
    ) +
    coord_cartesian(clip = "off")
```
```

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

### Collect all guide legends by default

Source: https://yunuuuu.github.io/ggalign-book/schemes.html

By default, ggheatmap collects all guide legends on the side from which they originate.

```R
heatmap_collect_all_guides <- ggheatmap(small_mat, width = 2, height = 2L) +
    # we set the legend to the left side
    scale_fill_gradient2(
        low = "blue", high = "red",
        name = "I'm from heatmap body",
        guide = guide_legend(position = "left")
    ) +
    theme(axis.text.x = element_text(angle = -60, hjust = 0)) +
    # we add a top annotation
    anno_top() +
    # in the top annotation, we add a dendrogram
    align_dendro(aes(color = branch), k = 3L) +
    # we set the legends of the dendrogram to the left side
    scale_color_brewer(
        name = "I'm from top annotation", palette = "Dark2",
        guide = guide_legend(position = "left")
    ) +
    # we add a left annotation
    anno_left() +
    align_dendro(aes(color = branch), k = 3L) +
    # we set the legends of the dendrogram to the top side
    scale_color_brewer(
        name = "I'm from left annotation", palette = "Dark2",
        guide = guide_legend(position = "top", direction = "vertical")
    ) &
    # we remove all margins for all plots
    theme(plot.margin = margin())
heatmap_collect_all_guides
#> → heatmap built with `geom_tile()`
```

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

### Example of order2 with hclust

Source: https://yunuuuu.github.io/ggalign/reference/order2.html

Demonstrates using order2 on an hclust object created from a random normal matrix.

```R
order2(hclust2(matrix(rnorm(100L), nrow = 10L)))
#>  [1]  1  7  8 10  4  6  9  3  2  5
```

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

### Initialize small_mat for nested layouts

Source: https://yunuuuu.github.io/ggalign-book/multiple-quad-layouts.html

Sets up a small matrix for demonstration purposes.

```R
library(ggalign)
#> Loading required package: ggplot2
#> ========================================
#> ggalign version 1.2.0.9000
#> 
#> If you use it in published research, please cite: 
#> Peng, Y.; Jiang, S.; Song, Y.; et al. ggalign: Bridging the Grammar of Graphics and Biological Multilayered Complexity. Advanced Science. 2025. doi:10.1002/advs.202507799
#> ========================================
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)))
```

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

### Align plots with default guides

Source: https://yunuuuu.github.io/ggalign-book/plot-composer.html

Aligns plots without consolidating guides, keeping them separate.

```R
align_plots(p_right, p_left)
```

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

### Load ggalign library

Source: https://yunuuuu.github.io/ggalign-book/free.html

Initializes the ggalign package and displays version information and citation details.

```R
library(ggalign)
#> Loading required package: ggplot2
#> ========================================
#> ggalign version 1.2.0.9000
#> 
#> If you use it in published research, please cite: 
#> Peng, Y.; Jiang, S.; Song, Y.; et al. ggalign: Bridging the Grammar of Graphics and Biological Multilayered Complexity. Advanced Science. 2025. doi:10.1002/advs.202507799
#> ========================================
```

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

### hclust2 Example with USArrests

Source: https://yunuuuu.github.io/ggalign/reference/hclust2.html

An example of using hclust2 on the USArrests dataset with the ward.D agglomeration method.

```R
hclust2(dist(USArrests), method = "ward.D")
#> 
#> Call:
#> stats::hclust(d = d, method = method)
#> 
#> Cluster method   : ward.D 
#> Distance         : euclidean 
#> Number of objects: 50 
#>
```

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

### Using free_spaces to position guide legends next to annotations

Source: https://yunuuuu.github.io/ggalign-book/schemes.html

Shows how to use free_spaces to position guide legends next to annotations. It uses quad_active(), scheme_align(guides = "t"), scheme_align(guides = "l"), and quad_scope(scheme_align(free_spaces = "l"), "t"). The output is '→ heatmap built with `geom_tile()`'.

```r
heatmap_collect_all_guides +
    # reset the active context to the heatmap layout
    quad_active() -
    # we set global `guides` argument for the heatmap layout
    # we only collect guides in the top side
    scheme_align(guides = "t") +
    # `+` apply it to the current active plot
    # for the heatmap body, we collect guide in the left side
    scheme_align(guides = "l") -
    quad_scope(scheme_align(free_spaces = "l"), "t")
#> → heatmap built with `geom_tile()`
```

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

### Load ggalign library

Source: https://yunuuuu.github.io/ggalign-book/stack-layout.html

Initializes the ggalign library for use.

```R
library(ggalign)
```

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

### free_guide

Source: https://yunuuuu.github.io/ggalign/reference/free.html

Overrides the behaviour of the overall guides behaviour. Wrap the plot with free_guide to override guide behavior.

```APIDOC
## free_guide

### Description
Overrides the behaviour of the overall guides behaviour. Wrap the plot with free_guide to override guide behavior.

### Usage
free_guide(plot)

### Arguments
- **plot** (ggplot) - Required - The plot to wrap.

### Value
A modified version of `plot` with a `ggalign_free_guide` class.
```

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

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

Source: https://yunuuuu.github.io/ggalign/reference/quad_active.html

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"`. Sets the active context to the right annotation stack.

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

### Arguments
- **size** (numeric or unit) - Optional - A numeric value or an `unit` object to set the total `width` of the annotation stack.
- **free_guides** - Optional - Override the `guides` collection behavior specified in the `quad_layout()`/`ggheatmap()` for the annotation stack.
- **initialize** (boolean) - Optional - A boolean indicating whether the annotation stack should be initialized if it is not already.
- **what** - Optional - What should get activated in the annotation stack? A single number or string of the plot elements in the layout. If `NULL`, will remove any active context.

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

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

### Align plots with consolidated guides

Source: https://yunuuuu.github.io/ggalign-book/plot-composer.html

Uses the guides argument to collect legends to the left and right sides.

```R
align_plots(p_right, p_left, guides = "lr")
```

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

### align_order2 Example

Source: https://yunuuuu.github.io/ggalign/reference/align_order2.html

Demonstrates applying align_order2 with hclust2 to a heatmap layout.

```R
ggheatmap(matrix(rnorm(81), nrow = 9)) +
    anno_left() +
    align_order2(hclust2)
#> → heatmap built with `geom_tile()`
```

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

### Define plots with specific guides

Source: https://yunuuuu.github.io/ggalign-book/plot-composer.html

Creates two plots with custom guide positions for legend consolidation.

```R
p_right <- ggplot(mtcars) +
    geom_point(aes(hp, wt, colour = mpg)) +
    scale_color_continuous(guide = guide_colorbar(position = "right")) +
    labs(color = "From\nP1") +
    ggtitle("P1")

p_left <- ggplot(mtcars) +
    geom_point(aes(hp, wt, colour = factor(cyl))) +
    scale_color_brewer(
        palette = "Dark2",
        guide = guide_legend(position = "left")
    ) +
    labs(color = "From\nP2") +
    ggtitle("P2")
```

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

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

Source: https://yunuuuu.github.io/ggalign/reference/quad_active.html

Sets the active context to the specified annotation stack based on the position argument. Allows customization of the annotation stack size, guide collection behavior, initialization, and the plot element to activate.

```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
```r
quad_anno(
  position,
  size = NULL,
  free_guides = waiver(),
  initialize = NULL,
  what = waiver()
)
```

### Arguments
- **position** (string) - Required - A string of `"top"`, `"left"`, `"bottom"`, or `"right"` indicating which annotation stack should be activated.
- **size** (numeric or unit) - Optional - A numeric value or an `unit` object to set the total `height`/`width` of the annotation stack. If `position` is `"top"` or `"bottom"`, `size` sets the total height of the annotation. If `position` is `"left"` or `"right"`, `size` sets the total width of the annotation.
- **free_guides** - Optional - Override the `guides` collection behavior specified in the `quad_layout()`/`ggheatmap()` for the annotation stack.
- **initialize** (boolean) - Optional - A boolean indicating whether the annotation stack should be initialized if it is not already. By default, the annotation stack layout will attempt to initialize when the data is compatible. If set to `TRUE`, and the data in `quad_layout()`/`ggheatmap()` is incompatible with the annotation stack, no data will be used in the stack.
- **what** - Optional - What should get activated in the annotation stack? A single number or string of the plot elements in the layout. If `NULL`, will remove any active context.

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

### Details
By default, `quad_anno()` attempts to initialize the annotation stack layout using data from `quad_layout()`/`ggheatmap()`. However, in situations where you want to use different data for the annotation stack, you can set `initialize = FALSE` and then provide a custom `stack_layout()`.
```

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

### Wrapping Graphics with ggwrap

Source: https://yunuuuu.github.io/ggalign/reference/ggwrap.html

Examples demonstrating how to wrap grid grobs and base R plots for use within an alignment layout.

```R
library(grid)
ggwrap(rectGrob(gp = gpar(fill = "goldenrod")), align = "full") +
    inset(rectGrob(gp = gpar(fill = "steelblue")), align = "panel") +
    inset(textGrob("Here are some text", gp = gpar(color = "black")), 
        align = "panel"
    )

p1 <- ggplot(mtcars) +
    geom_point(aes(mpg, disp)) +
    ggtitle("Plot 1")
align_plots(p1, ggwrap(
    ~ plot(mtcars$mpg, mtcars$disp),
    mar = c(0, 2, 0, 0), bg = NA
))
```

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

### align_hclust example

Source: https://yunuuuu.github.io/ggalign/reference/align_hclust.html

An example of using align_hclust within a ggheatmap layout to group observations into 3 clusters.

```R
# align_hclust won't add a dendrogram
ggheatmap(matrix(rnorm(81), nrow = 9)) +
    anno_top() +
    align_hclust(k = 3L)
#> → heatmap built with `geom_tile()`
```

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

### quad_anno() with initialize = TRUE

Source: https://yunuuuu.github.io/ggalign-book/quad-layout.html

Initializes the annotation stack layout with no data, requiring data to be provided in each plot within the annotation.

```APIDOC
## quad_anno() with initialize = TRUE

### Description
Initializes the annotation stack layout with no data, requiring data to be provided in each plot within the annotation.

### Usage
quad_layout(small_mat, xlim = NULL) +
    geom_boxplot(aes(value, .discrete_y, fill = .row_names)) +
    scale_fill_brewer(palette = "Dark2") +
    anno_top(initialize = TRUE) +
    ggalign(data = mpg, aes(displ, hwy, colour = class)) +
    geom_point(aes(displ, hwy, colour = class)) +
    layout_title("quad_alignh()")

quad_layout(small_mat, ylim = NULL) +
    geom_boxplot(aes(.discrete_x, value, fill = .column_names)) +
    scale_fill_brewer(palette = "Dark2") +
    anno_left(initialize = TRUE) +
    ggalign(data = mpg, aes(displ, hwy, colour = class)) +
    geom_point(aes(displ, hwy, colour = class)) +
    layout_title("quad_alignv()")

### Parameters
- **initialize** (logical) - Optional - Set to TRUE to initialize the annotation stack layout with no data.
```

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

### Create example data for phylogenetic tree

Source: https://yunuuuu.github.io/ggalign-gallery/advanced/phylogenetic-trees.html

Generates a random coalescent tree with 100 tips and a matrix of 100 rows and 3 columns for demonstration.

```r
n <- 100
p <- 3
set.seed(3)
tr <- ape::rcoal(n)
x <- matrix(runif(p * n), n, p)
```

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

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

Source: https://yunuuuu.github.io/ggalign/reference/quad_active.html

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"`. Sets the active context to the bottom annotation stack.

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

### Arguments
- **size** (numeric or unit) - Optional - A numeric value or an `unit` object to set the total `height` of the annotation stack.
- **free_guides** - Optional - Override the `guides` collection behavior specified in the `quad_layout()`/`ggheatmap()` for the annotation stack.
- **initialize** (boolean) - Optional - A boolean indicating whether the annotation stack should be initialized if it is not already.
- **what** - Optional - What should get activated in the annotation stack? A single number or string of the plot elements in the layout. If `NULL`, will remove any active context.

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

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

### Apply basic layout tags

Source: https://yunuuuu.github.io/ggalign-gallery/basics/plot-composer-tagging.html

Demonstrates applying uppercase Latin letter tags to a nested layout.

```R
align_plots(p1, align_plots(p2, p3), ncol = 1) + layout_tags("A")
```