Skip to content

Commit

Permalink
update
Browse files Browse the repository at this point in the history
  • Loading branch information
@Yunuuuu
Yunuuuu committed Oct 9, 2024
1 parent 0b3d5e5 commit bd443b3
Show file tree
Hide file tree
Showing 2 changed files with 131 additions and 71 deletions.
92 changes: 60 additions & 32 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,34 +21,62 @@ knitr::opts_chunk$set(
<!-- badges: end -->
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)
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() +
Expand All @@ -63,35 +91,35 @@ 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)
- [Layout Plot](https://yunuuuu.github.io/ggalign/articles/layout-plot.html)
- [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.
110 changes: 71 additions & 39 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
<!-- badges: end --> 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)
Expand All @@ -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() +
Expand All @@ -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)
Expand All @@ -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.

0 comments on commit bd443b3

Please sign in to comment.