-
Notifications
You must be signed in to change notification settings - Fork 7
/
README.Rmd
147 lines (121 loc) · 5.73 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
---
output: github_document
params:
mode: !r if (endsWith(as.character(desc::desc_get_version()), '9000')) 'devel' else 'release'
release: "https://yunuuuu.github.io/ggalign"
devel: "https://yunuuuu.github.io/ggalign/dev"
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
```{r echo=FALSE}
mode <- params$mode
url <- params[[mode]]
```
# ggalign <a href="https://yunuuuu.github.io/ggalign/"><img src="man/figures/logo.png" align="right" height="139" alt="ggalign website" /></a>
<!-- badges: start -->
[](https://github.com/Yunuuuu/ggalign/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/Yunuuuu/ggalign?branch=main)
[](https://CRAN.R-project.org/package=ggalign)
<!-- badges: end -->
This package extends ggplot2 by providing advanced tools for aligning and
organizing multiple plots, particularly those that automatically reorder
observations, such as dendrogram. It offers fine control over layout adjustment
and plot annotations, enabling you to create complex, publication-quality
visualizations while still using the familiar grammar of ggplot2.
## Why use `ggalign`?
`ggalign` focuses on aligning observations across multiple plots. It leverages
the `"number of observations"` in the
[vctrs](https://vctrs.r-lib.org/reference/vec_size.html) package or `NROW()`
function to maintain consistency in plot organization.
If you've ever struggled with aligning plots with self-contained ordering (like
dendrogram), or applying consistent grouping or ordering across multiple plots
(e.g., with k-means clustering), `ggalign` is designed to make this easier. The
package integrates seamlessly with ggplot2, providing the flexibility to use its
geoms, scales, and other components for complex visualizations.
## Installation
You can install `ggalign` from `CRAN` using:
```{r, eval=FALSE}
install.packages("ggalign")
```
Alternatively, install the development version from
[r-universe](https://yunuuuu.r-universe.dev/ggalign) with:
```{r, eval=FALSE}
install.packages("ggalign",
repos = c("https://yunuuuu.r-universe.dev", "https://cloud.r-project.org")
)
```
or from [GitHub](https://github.com/Yunuuuu/ggalign) with:
```{r, eval=FALSE}
# install.packages("remotes")
remotes::install_github("Yunuuuu/ggalign")
```
## Getting Started
The usage of `ggalign` is simple if you're familiar with `ggplot2` syntax, the
typical workflow includes:
- Initialize the layout using `ggheatmap()`/`ggside()`, `quad_layout()` or
`ggstack()`.
- Customize the layout with:
- `align_group()`: Group observations into panel with a group variable.
- `align_kmeans()`: Group observations into panel by kmeans.
- `align_order()`: Reorder layout observations based on statistical weights
or by manually specifying the observation index.
- `align_dendro()`: Reorder or Group layout based on hierarchical clustering.
- Adding plots with `ggalign()` or `ggfree()`, and then layer additional
ggplot2 elements such as geoms, stats, or scales.
For documents of the release version, please see <`r params$release`>, for
documents of the development version, please see <`r params$devel`>.
## Basic example
Below, we'll walk through a basic example of using `ggalign` to create a heatmap
with a `dendrogram`.
```{r, eval=FALSE}
library(ggalign)
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)))
# initialize the heatmap layout, we can regard it as a normal ggplot object
ggheatmap(small_mat) +
# we can directly modify geoms, scales and other ggplot2 components
scale_fill_viridis_c() +
# add annotation in the top
anno_top() +
# in the top annotation, we add a dendrogram, and split observations into 3 groups
align_dendro(aes(color = branch), k = 3) +
# in the dendrogram we add a point geom
geom_point(aes(color = branch, y = y)) +
# change color mapping for the dendrogram
scale_color_brewer(palette = "Dark2")
```
`r sprintf("", url)`
## Compare with other ggplot2 heatmap extension
`ggalign` offers advantages over extensions like
[ggheatmap](https://github.com/XiaoLuo-boy/ggheatmap) by providing full
compatibility with `ggplot2`. With `ggalign`, you can:
- Seamlessly integrate ggplot2 `geoms`, `stats`, `scales` et al. into your
layouts.
- Align dendrograms even in facetted plots.
- Easily create complex layouts, including multiple heatmaps arranged vertically
or horizontally.
## Compare with ComplexHeatmap
### Pros
- Full integration with the `ggplot2` ecosystem.
- Heatmap annotation axes and legends are automatically generated.
- Dendrogram can be easily customized and colored.
- Flexible control over plot size and spacing.
- Can easily align with other `ggplot2` plots by panel area.
- Can easily extend for other clustering algorithm, or annotation plot.
### Cons
Fewer Built-In Annotations: May require additional coding for specific
annotations or customization compared to the extensive built-in annotation
function in [ComplexHeatmap](https://github.com/jokergoo/ComplexHeatmap).
## More Complex Examples
Here are some more advanced visualizations using `ggalign`:
`r sprintf("", url)`
`r sprintf("", url)`