{"id":13711616,"url":"https://github.com/teunbrand/ggplateplot","last_synced_at":"2025-03-20T10:23:11.924Z","repository":{"id":103976104,"uuid":"489013031","full_name":"teunbrand/ggplateplot","owner":"teunbrand","description":"What the Package Does (One Line, Title Case)","archived":false,"fork":false,"pushed_at":"2022-05-07T15:06:47.000Z","size":1999,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-25T10:44:12.125Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/teunbrand.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-05-05T14:48:36.000Z","updated_at":"2025-01-05T08:34:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"b5d00ed0-8e4d-4ebd-a7bd-18606a5face2","html_url":"https://github.com/teunbrand/ggplateplot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teunbrand%2Fggplateplot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teunbrand%2Fggplateplot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teunbrand%2Fggplateplot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teunbrand%2Fggplateplot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teunbrand","download_url":"https://codeload.github.com/teunbrand/ggplateplot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244592294,"owners_count":20477886,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T23:01:09.910Z","updated_at":"2025-03-20T10:23:11.901Z","avatar_url":"https://github.com/teunbrand.png","language":"R","funding_links":[],"categories":["Plot layers"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse  = TRUE,\n  comment   = \"#\u003e\",\n  fig.path  = \"man/figures/README-\",\n  out.width = \"100%\",\n  dev       = \"ragg_png\",\n  dpi       = 132\n)\nset.seed(42)\n```\n\n# ggplateplot\n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/teunbrand/ggplateplot/workflows/R-CMD-check/badge.svg)](https://github.com/teunbrand/ggplateplot/actions)\n[![Codecov test coverage](https://codecov.io/gh/teunbrand/ggplateplot/branch/master/graph/badge.svg)](https://app.codecov.io/gh/teunbrand/ggplateplot?branch=master)\n[![CRAN status](https://www.r-pkg.org/badges/version/ggplateplot)](https://CRAN.R-project.org/package=ggplateplot)\n[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)\n\u003c!-- badges: end --\u003e\n\nWell, well, well... it seems you've found this package for plotting: wells.\n\nThe 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.\n\n## Installation\n\nYou can install the development version of {ggplateplot} like so:\n\n``` r\n# install.packages(\"remotes\")\nremotes::install_github(\"teunbrand/ggplateplot\")\n```\n\n## Example\n\nThis is a terse example of how one could make a plot from a `matrix` of values.\n\n```{r example_matrix}\nlibrary(ggplot2)\nlibrary(ggplateplot)\n\nplate \u003c- matrix(rnorm(24), nrow = 4, ncol = 6)\n\nggplateplot(plate, aes(fill = value)) +\n  geom_well()\n```\n\nInstead 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.\n\n```{r example_long}\ndf \u003c- expand.grid(\n  x = 1:8,\n  y = LETTERS[1:6]\n)\ndf$values \u003c- rnorm(nrow(df))\n\nggplateplot(df, aes(x, y, fill = values)) +\n  geom_well()\n```\n\n## How does it work?\n\nThis 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.\n\nThe `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. \n\n### Geom\n\nFirst 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.\n\n```{r geom_well}\np \u003c- ggplot(df, aes(x, y, fill = values)) +\n  geom_well()\np\n```\n\n### Coord\n\nThe crux of {ggplateplot} is `coord_plate()`, which modifies how several panel components of a plot are drawn.\n\n#### Theming\n\nThe following adjustments to the theming of a plot are made.\n\n* 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.\n* The `panel.grid.major` now draws circles around the wells.\n* The `panel.grid.minor` performs the role of the major panel grid.\n\n```{r coord_plate_theme}\np + coord_plate(corner = \"topright\", spec = 48) +\n  theme(\n    panel.grid.major = element_line(colour = \"dodgerblue\"),\n    panel.grid.minor = element_line(colour = \"tomato\"),\n    panel.background = element_rect(colour = \"black\", fill = \"white\")\n  )\n```\n\n#### Layout\n\nThe `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.\n\n```{r coord_plate_spec}\np + coord_plate(specs = 96)\n```\n\nTo offer slightly more flexibility than the standard layouts, you can set a custom layout with `custom_plate_spec()`.\n\n```{r coord_plate_custom}\ndf \u003c- data.frame(\n  x = rep(1:5, each = 4),\n  y = rep(LETTERS[1:4], 5),\n  value = rnorm(20)\n)\n\nggplot(df, aes(x, y, fill = value)) +\n  geom_well() +\n  coord_plate(spec = custom_plate_spec(ncol = 5, nrow = 4))\n```\n\nIf you want to even further customise the layout, you can use `new_plate_spec()` to control even more parameters of the layout.\n\n```{r, coord_plate_new}\nspec \u003c- new_plate_spec(\n  width = 100, height = 100,\n  hor_spacing = 15,\n  ver_spacing = 20,\n  well_diameter = 12, \n  ncol = 5, nrow = 4,\n  corner_size = 25\n)\n\nggplot(df, aes(x, y, fill = value)) +\n  geom_well() +\n  coord_plate(spec = spec)\n```\n\n### Circling back\n\nSo 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.\n\n```{r round_off}\nplate \u003c- matrix(rnorm(384), ncol = 24, nrow = 16)\n\nggplateplot(plate, aes(fill = value)) +\n  geom_well()\n```\n\n## Interacting with ggplot2\n\nWhile {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.\n\n```{r complete_example}\nm \u003c- array(1:192, dim = c(8, 12, 2))\n\nggplateplot(m, aes(fill = value)) +\n  geom_point(shape = 24, size = 2.5) +\n  scale_fill_viridis_c() +\n  scale_y_reverse(name = \"Rows\", labels = LETTERS[1:8]) +\n  facet_wrap(~ Var3) +\n  theme(\n    panel.background = element_rect(colour = \"black\", fill = NA),\n    panel.grid.major = element_line(colour = \"grey90\"),\n    panel.grid.minor = element_line(colour = \"grey97\")\n  ) +\n  labs(x = \"Columns\")\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteunbrand%2Fggplateplot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteunbrand%2Fggplateplot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteunbrand%2Fggplateplot/lists"}