Create ggplot object — align

align_gg() is similar to ggplot in that it initializes a ggplot data and mapping. Same with other align_* functions. align_gg() allowing you to provide data in various formats, including matrices, data frames, or simple vectors. By default, it will inherit from the layout. If a function, it will apply with the layout matrix. ggalign is an alias of align_gg.

Usage

align_gg(
  mapping = aes(),
  size = NULL,
  data = waiver(),
  limits = TRUE,
  facet = TRUE,
  no_axes = NULL,
  active = NULL,
  set_context = deprecated(),
  order = deprecated(),
  name = deprecated(),
  free_guides = deprecated(),
  free_spaces = deprecated(),
  plot_data = deprecated(),
  theme = deprecated(),
  free_labs = deprecated()
)

Arguments

mapping

Default list of aesthetic mappings to use for plot. If not specified, must be supplied in each layer added to the plot.

size

The relative size of the plot, can be specified as a unit.

data

A flexible input that specifies the data to be used

NULL: No data is set.
waiver(): Uses the layout matrix.
A function (including purrr-like lambda syntax) that is applied to the layout matrix, and must return a matrix. If you want to transform the final plot data, please use plot_data().
A matrix, data frame, or atomic vector.

limits

Logical; if TRUE, sets layout limits for the plot.

facet

Logical; if TRUE, applies facets to the layout. If FALSE, limits will also be set to FALSE.

no_axes

Logical; if TRUE, removes axes elements for the alignment axis using theme_no_axes(). By default, will controled by the option- "ggalign.align_no_axes".

active

A active() object that defines the context settings when added to a layout.

set_context

Please use active argument instead.

order

Please use active argument instead.

name

Please use active argument instead.

free_guides

Please use plot_align() function instead.

free_spaces

Please use plot_align() function instead.

plot_data

Please use plot_data() function instead.

theme

Please use plot_theme() function instead.

free_labs

Please use plot_align() function instead.

Value

A "AlignGG" object.

ggplot2 specification

align_gg initializes a ggplot data and mapping.

align_gg() always applies a default mapping for the axis of the data index in the layout. This mapping is aes(y = .data$.y) for horizontal stack layout (including left and right annotation) and aes(x = .data$.x) for vertical stack layout (including top and bottom annotation).

matrix input will be automatically melted into a long foramted data frame.

Atomic vector will be put in the value column of the data frame.

In the case where the input data is already a data frame, 4 additional columns (.x/.y, .names, .index, and .panel) are added to the data frame.

The data in the underlying ggplot object will contain following columns:

.panel: the panel for the aligned axis. It means x-axis for vertical stack layout (including top and bottom annotation), y-axis for horizontal stack layout (including left and right annotation).
.x or .y: the x or y coordinates
.names (vec_names()) and .index (vec_size()/NROW()): A factor of the names (only applicable when names exists) and an integer of index of the original data.
.row_names and .row_index: the row names and an integer of row index of the original matrix (only applicable if data is a matrix).
.column_names and .column_index: the column names and column index of the original matrix (only applicable if data is a matrix).
value: the actual value (only applicable if data is a matrix or atomic vector).

It is recommended to use .x/.y, or .names as the x/y mapping.

If the data inherits from quad_layout()/ggheatmap(), an additional column will be added.

.extra_panel: the panel information for column (left or right annotation) or row (top or bottom annotation).

Axis Alignment for Observations

It is important to note that we consider rows as observations, meaning vec_size(data)/NROW(data) must match the number of observations along the axis used for alignment (x-axis for a vertical stack layout, y-axis for a horizontal stack layout).

quad_layout()/ggheatmap(): For column annotation, the layout matrix will be transposed before use (if data is a function, it is applied to the transposed matrix), as column annotation uses columns as observations but alignment requires rows.
stack_layout(): The layout matrix is used as is, aligning all plots along a single axis.

Examples

ggheatmap(matrix(rnorm(81), nrow = 9)) +
    anno_top() +
    ggalign() +
    geom_point(aes(y = value))
#> → heatmap built with `geom_tile()`


# if data is `NULL`, a three column data frame will be created
# (`.panel`, `.index`, `.x`/`.y`)
ggheatmap(matrix(rnorm(81), nrow = 9)) +
    anno_top(size = 0.5) +
    align_dendro(k = 3L) +
    ggalign(data = NULL, size = 0.2) +
    geom_tile(aes(y = 1L, fill = .panel))
#> → heatmap built with `geom_tile()`