Stack Layout

stack_layout() put plots horizontally or vertically. You can also use the alias ggstack().

Input data

The data input can be a numeric or character vector, a matrix, and a data frame. Simple vector will be converted into a one column matrix.

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

By default, ggstack() will create the layout, but no plot will be drawn until you add a plot element:

ggstack(small_mat)

We can add any align_*() function to customize the layout or integrate plots into the stack.

ggstack(small_mat) + align_dendro()

ggstack(small_mat) +
    align_kmeans(centers = 3L) +
    ggalign(data = rowSums) +
    geom_bar(aes(value, fill = .panel), orientation = "y", stat = "identity") +
    facet_grid(switch = "y") +
    theme(strip.text = element_text()) +
    align_dendro(aes(color = branch))

By default, ggstack() arranges the plots horizontally. To change the direction to vertical, use the direction argument:

ggstack(small_mat, "v") + align_dendro()

Note that vertical stack take the x-axis as the observations, but horizontal stack take the y-axis as the observations.

Data frame Input

Unlike heatmap_layout()/ggheatmap(), data frames are not automatically converted into a matrix within ggstack().

When using data frames, be cautious as many align_*() functions only accept matrix. If the necessary data is not explicitly provided to an align_*() function, the data frame from ggstack() will be passed to the function and internally converted into a matrix, which may result in missing values.

An exception is the align_gg()/ggalign() function, which can handle both matrix and data frames. When the input is a matrix (or a simple vector), it will be transformed into a long-format data frame. When the input is a data frame, only the necessary panel and axis information will be added to the data frame.

ggstack(mtcars) +
    ggalign(aes(mpg)) +
    geom_point()

Note align_gg()/ggalign() always applies a default mapping for the parallel axes of the data index within the layout. This mapping is aes(y = .data$.y) for horizontal stack and aes(x = .data$.x) for vertical stack. So here we only provide mapping for the x-axis.

For more information on adding plots, refer to the vignette: vignette("layout-plot").

Heatmap plot

Besides the align_*() functions, we can also add the heatmap_layout()/ggheatmap() into the stack layout.

ggstack(small_mat) +
    ggheatmap()

As mentioned earlier, vertical stacks use the x-axis for observations, while horizontal stacks use the y-axis. However, heatmap layouts always use the y-axis for observations. When a heatmap layout is added to a vertical stack layout, the inherited data is automatically converted to a matrix and transposed before use.

ggstack(small_mat, direction = "v") +
    ggheatmap()

Once a heatmap layout is added, any further elements you add will be applied to this heatmap layout. You can include align_* elements or any ggplot2 components for the heatmap.

ggstack(small_mat) +
    ggheatmap() +
    scale_fill_viridis_c()

If you’d like to add elements to the stack layout rather than the heatmap layout, you can easily switch from the heatmap layout to the stack layout using stack_active().

ggstack(small_mat) +
    ggheatmap() +
    scale_fill_viridis_c() +
    stack_active() +
    ggalign(data = rowSums) +
    geom_bar(aes(value), fill = "red", orientation = "y", stat = "identity")

One exception is the heatmap layout itself, which cannot be added to another heatmap layout. Therefore, you can directly add a heatmap layout to the stack layout without using stack_active().

ggstack(small_mat, "v") +
    ggheatmap() +
    ggheatmap() &
    scale_fill_viridis_c()

Control sizes

A length of 3 sizes should be provided in ggstack() when putting a heatmap with flank annotation into the stack layout. For vertical stacks, this means heatmaps with left or right annotations; for horizontal stacks, this means heatmaps with top or bottom annotations. The first size controls the relative width/height of the left or top annotation, the second controls the relative size of the heatmap body width/height, and the third controls the relative width/height of the right or bottom annotation.

By default the three rows/columns will have equal sizes.

ggstack(small_mat, "v") +
    ggheatmap() +
    scale_fill_viridis_c() +
    hmanno("l") +
    align_dendro(aes(color = .panel), k = 3L) +
    hmanno("r") +
    ggalign(data = rowSums) +
    geom_bar(aes(value, fill = .panel), orientation = "y", stat = "identity") +
    ggheatmap()

ggstack(small_mat, "v", c(1, 2, 1)) +
    ggheatmap() +
    scale_fill_viridis_c() +
    hmanno("l") +
    align_dendro(aes(color = .panel), k = 3L) +
    hmanno("r") +
    ggalign(data = rowSums) +
    geom_bar(aes(value, fill = .panel), orientation = "y", stat = "identity") +
    ggheatmap()

In this way, heatmap body width/height specified in hmanno() or ggheatmap() won’t work.

ggstack(small_mat, "v") +
    ggheatmap() +
    scale_fill_viridis_c() +
    hmanno("l") +
    align_dendro(aes(color = .panel), k = 3L) +
    hmanno("r") +
    ggalign(data = rowSums) +
    geom_bar(aes(value, fill = .panel), orientation = "y", stat = "identity") +
    ggheatmap(.width = unit(2, "null"))

By default the flank annotation will fill the whole stack flank, but we can still control the total size of heatmap annotation in hmanno().

ggstack(small_mat, "v") +
    ggheatmap() +
    scale_fill_viridis_c() +
    hmanno("l", size = unit(2, "cm")) +
    align_dendro(aes(color = .panel), k = 3L) +
    hmanno("r") +
    ggalign(data = rowSums) +
    geom_bar(aes(value, fill = .panel), orientation = "y", stat = "identity") +
    ggheatmap()

You can also use npc unit.

ggstack(small_mat, "v") +
    ggheatmap() +
    scale_fill_viridis_c() +
    hmanno("l", size = unit(0.5, "npc")) +
    align_dendro(aes(color = .panel), k = 3L) +
    hmanno("r") +
    ggalign(data = rowSums) +
    geom_bar(aes(value, fill = .panel), orientation = "y", stat = "identity") +
    ggheatmap()

Session information

sessionInfo()
#> R version 4.4.0 (2024-04-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04 LTS
#> 
#> Matrix products: default
#> BLAS/LAPACK: /usr/lib/x86_64-linux-gnu/libmkl_rt.so;  LAPACK version 3.8.0
#> 
#> locale:
#>  [1] LC_CTYPE=C.UTF-8       LC_NUMERIC=C           LC_TIME=C.UTF-8       
#>  [4] LC_COLLATE=C           LC_MONETARY=C.UTF-8    LC_MESSAGES=C.UTF-8   
#>  [7] LC_PAPER=C.UTF-8       LC_NAME=C              LC_ADDRESS=C          
#> [10] LC_TELEPHONE=C         LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C   
#> 
#> time zone: Asia/Shanghai
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] ggalign_0.0.4 ggplot2_3.5.1
#> 
#> loaded via a namespace (and not attached):
#>  [1] sass_0.4.9         utf8_1.2.4         generics_0.1.3     digest_0.6.36     
#>  [5] magrittr_2.0.3     evaluate_0.24.0    grid_4.4.0         RColorBrewer_1.1-3
#>  [9] bookdown_0.39      iterators_1.0.14   fastmap_1.2.0      foreach_1.5.2     
#> [13] jsonlite_1.8.8     ggrastr_1.0.2      seriation_1.5.6    fansi_1.0.6       
#> [17] viridisLite_0.4.2  scales_1.3.0       codetools_0.2-20   textshaping_0.4.0 
#> [21] jquerylib_0.1.4    cli_3.6.3          registry_0.5-1     rlang_1.1.4       
#> [25] munsell_0.5.1      withr_3.0.0        cachem_1.1.0       yaml_2.3.8        
#> [29] ggbeeswarm_0.7.2   tools_4.4.0        dplyr_1.1.4        colorspace_2.1-0  
#> [33] vctrs_0.6.5        TSP_1.2-4          ca_0.71.1          R6_2.5.1          
#> [37] lifecycle_1.0.4    vipor_0.4.7        ragg_1.3.2         pkgconfig_2.0.3   
#> [41] beeswarm_0.4.0     pillar_1.9.0       bslib_0.7.0        gtable_0.3.5      
#> [45] data.table_1.15.4  glue_1.7.0         systemfonts_1.1.0  xfun_0.45         
#> [49] tibble_3.2.1       tidyselect_1.2.1   highr_0.11         knitr_1.47        
#> [53] farver_2.1.2       htmltools_0.5.8.1  rmarkdown_2.27     labeling_0.4.3    
#> [57] compiler_4.4.0