From bd443b39df0e961fff4027737afa7f00a0fbb98e Mon Sep 17 00:00:00 2001 From: Yunuuuu Date: Wed, 9 Oct 2024 14:24:39 +0800 Subject: [PATCH] update --- README.Rmd | 92 ++++++++++++++++++++++++++++---------------- README.md | 110 ++++++++++++++++++++++++++++++++++------------------- 2 files changed, 131 insertions(+), 71 deletions(-) diff --git a/README.Rmd b/README.Rmd index a755c24b..073f640d 100644 --- a/README.Rmd +++ b/README.Rmd @@ -21,26 +21,54 @@ knitr::opts_chunk$set( This package extends ggplot2 by providing advanced tools for aligning and organizing multiple plots, particularly those that automatically reorder -observations, such as dendrograms. It offers flexible control over plot layout -and plot annotations, enabling users to create complex, publication-quality -heatmaps or combined visualizations while utilizing the familiar grammar of -graphics. +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 `install.packages("ggalign")`. -Alternatively you can install the development version of `ggalign` from -[GitHub](https://github.com/) with: +You can install `ggalign` from `CRAN` using: +```{r, eval=FALSE} +install.packages("ggalign") +``` +Alternatively, install the development version 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, +`ggalign` works with a simple workflow: + + - Initialize the layout using `ggheatmap()` or `ggstack()`. + - Customize the layout with: + - `align_group()`: Group layout axis into panel with a group variable. + - `align_kmeans()`: Group layout axis into panel by kmeans + - `align_reorder()`: Reorder layout observations based on statistical weights + or allows for manual reordering based on user-defined criteria. + - `align_dendro()`: Reorder or Group layout based on hierarchical clustering + - Adding plots with `ggalign()` or `ggpanel()`, then add ggplot2 elements like + geoms, stats, scales. + ## Basic example -The usage of `ggalign` is simple if you're familiar with `ggplot2` syntax, we -first initialize the layout, we then reorder the layout, or group the layout -into panels, and add plots, layers, scales, coords with `+`. +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) @@ -48,7 +76,7 @@ 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 heamtap layout, we can regard it as a normal ggplot object +# 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() + @@ -63,11 +91,31 @@ ggheatmap(small_mat) + ``` ![](https://yunuuuu.github.io/ggalign/articles/complete-examples_files/figure-html/unnamed-chunk-3-1.png) +## Compare with other ggplot2 heatmap extension +The main advantage of `ggalign` over other extensions like ggheatmap is its full +compatibility with the ggplot2 grammar. You can seamlessly use any ggplot2 +geoms, stats, and scales to build 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. + +### Cons +Fewer Built-In Annotations: May require additional coding for specific +annotations or customization compared to the extensive built-in annotation +function in ComplexHeatmap. + ## More Complex Examples +Here are some more advanced visualizations using `ggalign`: ![](https://yunuuuu.github.io/ggalign/articles/more-examples_files/figure-html/unnamed-chunk-3-1.png) ![](https://yunuuuu.github.io/ggalign/articles/more-examples_files/figure-html/unnamed-chunk-2-1.png) -## Documentation +## Further Documentation - [Heatmap Layout](https://yunuuuu.github.io/ggalign/articles/heatmap-layout.html) - [Layout Customization](https://yunuuuu.github.io/ggalign/articles/layout-customize.html) @@ -75,23 +123,3 @@ ggheatmap(small_mat) + - [Stack Layout](https://yunuuuu.github.io/ggalign/articles/stack-layout.html) - [Scales and Facets](https://yunuuuu.github.io/ggalign/articles/scales-and-facets.html) -## Compre with other ggplot2 heatmap extension -In comparison to other heatmap extensions of `ggplot2`, such as -[ggheatmap](https://github.com/XiaoLuo-boy/ggheatmap), `ggalign` fully supports -the `ggplot2` syntax. This means you can incorporate any geoms, stats, scales, -etc., and allowing for the creation of more complex heatmap 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. -- Dendrograms can be easily customized and colored based on cluster -characteristics. -- Enhanced flexibility in controlling plot size, and spacing. -- Can easily align with `ggplot2` plots by panel area. - -### Cons -Fewer Built-In Annotations: May require additional coding for specific -annotations or customization compared to the extensive built-in annotation -function in ComplexHeatmap. diff --git a/README.md b/README.md index f6ac2801..1df95715 100644 --- a/README.md +++ b/README.md @@ -12,28 +12,62 @@ coverage](https://codecov.io/gh/Yunuuuu/ggalign/branch/main/graph/badge.svg)](ht status](https://www.r-pkg.org/badges/version/ggalign)](https://CRAN.R-project.org/package=ggalign) This package extends ggplot2 by providing advanced tools for aligning and organizing multiple plots, particularly those -that automatically reorder observations, such as dendrograms. It offers -flexible control over plot layout and plot annotations, enabling users -to create complex, publication-quality heatmaps or combined -visualizations while utilizing the familiar grammar of graphics. +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 `install.packages("ggalign")`. -Alternatively you can install the development version of `ggalign` from -[GitHub](https://github.com/) with: +You can install `ggalign` from `CRAN` using: + +``` r +install.packages("ggalign") +``` + +Alternatively, install the development version from +[GitHub](https://github.com/Yunuuuu/ggalign) with: ``` r # install.packages("remotes") remotes::install_github("Yunuuuu/ggalign") ``` -## Basic example +## Getting Started The usage of `ggalign` is simple if you’re familiar with `ggplot2` -syntax, we first initialize the layout, we then reorder the layout, or -group the layout into panels, and add plots, layers, scales, coords with -`+`. +syntax, `ggalign` works with a simple workflow: + +- Initialize the layout using `ggheatmap()` or `ggstack()`. +- Customize the layout with: + - `align_group()`: Group layout axis into panel with a group variable. + - `align_kmeans()`: Group layout axis into panel by kmeans + - `align_reorder()`: Reorder layout observations based on statistical + weights or allows for manual reordering based on user-defined + criteria. + - `align_dendro()`: Reorder or Group layout based on hierarchical + clustering +- Adding plots with `ggalign()` or `ggpanel()`, then add ggplot2 + elements like geoms, stats, scales. + +## Basic example + +Below, we’ll walk through a basic example of using `ggalign` to create a +heatmap with a `dendrogram`. ``` r library(ggalign) @@ -42,7 +76,7 @@ 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 heamtap layout, we can regard it as a normal ggplot object +# 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() + @@ -58,12 +92,36 @@ ggheatmap(small_mat) + ![](https://yunuuuu.github.io/ggalign/articles/complete-examples_files/figure-html/unnamed-chunk-3-1.png) +## Compare with other ggplot2 heatmap extension + +The main advantage of `ggalign` over other extensions like ggheatmap is +its full compatibility with the ggplot2 grammar. You can seamlessly use +any ggplot2 geoms, stats, and scales to build 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. + +### Cons + +Fewer Built-In Annotations: May require additional coding for specific +annotations or customization compared to the extensive built-in +annotation function in ComplexHeatmap. + ## More Complex Examples +Here are some more advanced visualizations using `ggalign`: ![](https://yunuuuu.github.io/ggalign/articles/more-examples_files/figure-html/unnamed-chunk-3-1.png) ![](https://yunuuuu.github.io/ggalign/articles/more-examples_files/figure-html/unnamed-chunk-2-1.png) -## Documentation +## Further Documentation - [Heatmap Layout](https://yunuuuu.github.io/ggalign/articles/heatmap-layout.html) @@ -75,29 +133,3 @@ ggheatmap(small_mat) + Layout](https://yunuuuu.github.io/ggalign/articles/stack-layout.html) - [Scales and Facets](https://yunuuuu.github.io/ggalign/articles/scales-and-facets.html) - -## Compre with other ggplot2 heatmap extension - -In comparison to other heatmap extensions of `ggplot2`, such as -[ggheatmap](https://github.com/XiaoLuo-boy/ggheatmap), `ggalign` fully -supports the `ggplot2` syntax. This means you can incorporate any geoms, -stats, scales, etc., and allowing for the creation of more complex -heatmap 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. -- Dendrograms can be easily customized and colored based on cluster - characteristics. -- Enhanced flexibility in controlling plot size, and spacing. -- Can easily align with `ggplot2` plots by panel area. - -### Cons - -Fewer Built-In Annotations: May require additional coding for specific -annotations or customization compared to the extensive built-in -annotation function in ComplexHeatmap.