Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/teunbrand/ggplateplot
What the Package Does (One Line, Title Case)
https://github.com/teunbrand/ggplateplot
Last synced: about 1 month ago
JSON representation
What the Package Does (One Line, Title Case)
- Host: GitHub
- URL: https://github.com/teunbrand/ggplateplot
- Owner: teunbrand
- License: other
- Created: 2022-05-05T14:48:36.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2022-05-07T15:06:47.000Z (over 2 years ago)
- Last Synced: 2024-08-03T23:23:41.152Z (3 months ago)
- Language: R
- Size: 1.91 MB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%",
dev = "ragg_png",
dpi = 132
)
set.seed(42)
```
# ggplateplot
[](https://github.com/teunbrand/ggplateplot/actions)
[](https://app.codecov.io/gh/teunbrand/ggplateplot?branch=master)
[](https://CRAN.R-project.org/package=ggplateplot)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
Well, well, well... it seems you've found this package for plotting: wells.
The goal of {ggplateplot} is to extend {ggplot2} to make it easier to make plots resembling cell culture microwell plates. This packages takes care of some of the layouts, relying on the flexibility of {ggplot2} and extensions to add layers, scales, theme adjustments et cetera.
## Installation
You can install the development version of {ggplateplot} like so:
``` r
# install.packages("remotes")
remotes::install_github("teunbrand/ggplateplot")
```
## Example
This is a terse example of how one could make a plot from a `matrix` of values.
```{r example_matrix}
library(ggplot2)
library(ggplateplot)
plate <- matrix(rnorm(24), nrow = 4, ncol = 6)
ggplateplot(plate, aes(fill = value)) +
geom_well()
```
Instead of providing a `matrix`, we can also provide long-format data. It should automatically detect an appropriate layout for the plate based on the number of rows in the `data` argument, when it has 6, 12, 24, 48, 96 or 384 rows.
```{r example_long}
df <- expand.grid(
x = 1:8,
y = LETTERS[1:6]
)
df$values <- rnorm(nrow(df))
ggplateplot(df, aes(x, y, fill = values)) +
geom_well()
```
## How does it work?
This package is not a package that instantly makes your plots prettier or easier. It is a formatting tool for a very particular kind of plot, of microwell shaped data, in {ggplot2}'s ecosystem.
The `ggplateplot()` function above is a thin wrapper around the `ggplot()` function. It does a few automated things to make your plots look more like cell culture plates.
### Geom
First off, the {ggplateplot} package has a specialised layer (geom) for drawing wells. This isn't a particularly exciting layer as it just draws circles as you would with `geom_point()`. A small bit of magic comes from combining this geom with `coord_plate()`, in that the `size` aesthetic is synced with the diameter of wells.
```{r geom_well}
p <- ggplot(df, aes(x, y, fill = values)) +
geom_well()
p
```
### Coord
The crux of {ggplateplot} is `coord_plate()`, which modifies how several panel components of a plot are drawn.
#### Theming
The following adjustments to the theming of a plot are made.
* The `panel.background` and `panel.border` follow the shape of a microwell plate. Corners are rounded a little bit and you can 'bite' off some corners with the `corner` argument to resemble a microwell plate better.
* The `panel.grid.major` now draws circles around the wells.
* The `panel.grid.minor` performs the role of the major panel grid.
```{r coord_plate_theme}
p + coord_plate(corner = "topright", spec = 48) +
theme(
panel.grid.major = element_line(colour = "dodgerblue"),
panel.grid.minor = element_line(colour = "tomato"),
panel.background = element_rect(colour = "black", fill = "white")
)
```
#### Layout
The `coord_plate()` function has a `specs` argument that takes a description of a well plate. We've included descriptions for 6, 12, 24, 48, 96 and 384-well plates in the package. If we mismatch the number of datapoints with the layout, we might get inappropriate layouts. In the example below, we're purposfully giving the wrong layout for the shape of the data to demonstrate that, among other things, the spacing of wells is off.
```{r coord_plate_spec}
p + coord_plate(specs = 96)
```
To offer slightly more flexibility than the standard layouts, you can set a custom layout with `custom_plate_spec()`.
```{r coord_plate_custom}
df <- data.frame(
x = rep(1:5, each = 4),
y = rep(LETTERS[1:4], 5),
value = rnorm(20)
)
ggplot(df, aes(x, y, fill = value)) +
geom_well() +
coord_plate(spec = custom_plate_spec(ncol = 5, nrow = 4))
```
If you want to even further customise the layout, you can use `new_plate_spec()` to control even more parameters of the layout.
```{r, coord_plate_new}
spec <- new_plate_spec(
width = 100, height = 100,
hor_spacing = 15,
ver_spacing = 20,
well_diameter = 12,
ncol = 5, nrow = 4,
corner_size = 25
)
ggplot(df, aes(x, y, fill = value)) +
geom_well() +
coord_plate(spec = spec)
```
### Circling back
So what does `ggplateplot()` do exactly? Well, it just tries to automatically match the shape of your data to an appropriate setting for `coord_plate()`. If you have data that doesn't match the dimensions of one of the standard plates, we recommend that you simply use `ggplot() + coord_plate()` instead, and customise from there. For `matrix` input, it additionally converts it to long format and automatically sets `x` and `y` aesthetics. The values in the matrix are converted to a `value` column.
```{r round_off}
plate <- matrix(rnorm(384), ncol = 24, nrow = 16)
ggplateplot(plate, aes(fill = value)) +
geom_well()
```
## Interacting with ggplot2
While {ggplateplot} makes it easier to make plots of plates, it still requires some familiarity with the ggplot2 package. The `ggplateplot()` functions return regular ggplot objects, so they can be combined with the usual functions one can use to manipulate plots. Below is an example of combining it with other {ggplot2} functions. We can use an array instead of matrix input to make variable out of the 3rd dimension, which we can use to create facets.
```{r complete_example}
m <- array(1:192, dim = c(8, 12, 2))
ggplateplot(m, aes(fill = value)) +
geom_point(shape = 24, size = 2.5) +
scale_fill_viridis_c() +
scale_y_reverse(name = "Rows", labels = LETTERS[1:8]) +
facet_wrap(~ Var3) +
theme(
panel.background = element_rect(colour = "black", fill = NA),
panel.grid.major = element_line(colour = "grey90"),
panel.grid.minor = element_line(colour = "grey97")
) +
labs(x = "Columns")
```