-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
173 lines (127 loc) · 6.48 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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
---
output: github_document
---
<!-- 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%",
dev = "ragg_png",
dpi = 132
)
set.seed(42)
```
# ggplateplot
<!-- badges: start -->
[](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)
<!-- badges: end -->
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")
```