# rphylopic ![](https://images.phylopic.org/images/c65573fb-2659-46b9-b7a0-065232a2a08b/vector.svg) The purpose of the `rphylopic` package is to allow users to add silhouettes of organisms to plots generated in base R and `ggplot2`. To do so, it uses silhouettes made available via the [PhyloPic website](http://phylopic.org/). `rphylopic` was originally developed and maintained by [Scott Chamberlain](https://scottchamberlain.info). From ver. 1.0.0, the package is now developed and maintained by [William Gearty](https://williamgearty.com) and [Lewis A. Jones](https://www.lewisajones.com/) from the [Palaeoverse team](https://palaeoverse.org). ## Installation The stable version of `rphylopic` can be installed from CRAN using: ``` r install.packages("rphylopic") ``` The development version of `rphylopic` can be installed via GitHub using: ``` r install.packages("remotes") remotes::install_github("palaeoverse/rphylopic") ``` # How does it work? ## Get an image uuid ``` r # Load rphylopic library(rphylopic) # Get a single image uuid for a species uuid <- get_uuid(name = "Canis lupus", n = 1) # Get the image for that uuid img <- get_phylopic(uuid = uuid) # But multiple silhouettes can exist per species... uuid <- get_uuid(name = "Canis lupus", n = 5) ``` ## Pick an image ``` r # How do I pick?! # It's difficult without seeing the image itself, let's use: img <- pick_phylopic(name = "Canis lupus", n = 5) ``` ## Plot an image ### Base R ``` r # OK, now we've got the image we want... let's add it to a plot! plot(x = 1, y = 1, type = "n") add_phylopic_base(img = img, x = 1.25, y = 1.25, height = 0.25) # But can't we just add an image straight away using the uuid? Sure! uuid <- get_uuid(name = "Canis lupus", n = 1) add_phylopic_base(uuid = uuid, x = 1, y = 1, height = 0.25) # What about just using the first image linked to the name? Definitely! add_phylopic_base(name = "Canis lupus", x = 0.75, y = 0.75, height = 0.25) # Black is a bit boring? OK... add_phylopic_base(name = "Canis lupus", x = 0.75, y = 1.25, height = 0.25, color = "orange") ``` ### ggplot2 ``` r # All of this functionality is available for ggplot2 as well... # But we use add_phylopic and geom_phylopic instead! library(ggplot2) # Get image uuid <- get_uuid(name = "Iris", n = 1) img <- get_phylopic(uuid = uuid) # Put a silhouette behind a plot ggplot(iris) + add_phylopic(x = 6.1, y = 3.2, img = img, alpha = 0.2) + geom_point(aes(x = Sepal.Length, y = Sepal.Width)) # Plot silhouettes as points! ggplot(iris) + geom_phylopic(aes(x = Sepal.Length, y = Sepal.Width), img = img, color = "purple", height = 0.25) ``` ## Get attribution ``` r # PhyloPic has a lot of contributors and we should acknowledge # their work. You can get data about images using get_attribution # Get valid uuid uuid <- get_uuid(name = "Nycticebus") # Get attribution data for uuid get_attribution(uuid = uuid) ``` ## Save an image ``` r # How do I save an image? # Get image img <- pick_phylopic(name = "Phascolarctos cinereus", n = 1) # Save image save_phylopic(img = img) ``` # How to contribute? If you are interested in contributing to the `rphylopic` R package, you can do so by following these [guidelines](https://rphylopic.palaeoverse.org/CONTRIBUTING.html). # Code of Conduct As with any community project, society, or meeting we feel it is important to established some expectations of behaviour. Please read our [code of conduct](https://rphylopic.palaeoverse.org/CODE_OF_CONDUCT.html), and reach out if you ever face any issues. Everyone has the right to live and work in a harassment-free environment. # Attribution If you use the `rphylopic` package in your work, please acknowledge the contributors responsible for the image, acknowledge the creator of PhyloPic ([Michael Keesey](http://tmkeesey.net)), and cite the following for `rphylopic`: Gearty, W. and Jones, L.A. 2023. rphylopic: An R package for fetching, transforming, and visualising PhyloPic silhouettes. Methods in Ecology and Evolution, 14(11), 2700-2708. doi: [10.1111/2041-210X.14221](https://doi.org/10.1111/2041-210X.14221). # Cheat sheet ![](reference/figures/cheatsheet.png) ![](reference/figures/logo.png) [Hex logo and cheatsheet by Miranta Kouvari](https://www.mirantakouvari.com) # Package index ## Getting silhouettes Functions for identifying and retrieving PhyloPic silhouettes. - [`get_uuid()`](https://rphylopic.palaeoverse.org/reference/get_uuid.md) : Get a PhyloPic uuid - [`resolve_phylopic()`](https://rphylopic.palaeoverse.org/reference/resolve_phylopic.md) : Use a taxonomic name from another database to get a PhyloPic image UUID - [`pick_phylopic()`](https://rphylopic.palaeoverse.org/reference/pick_phylopic.md) : Pick a PhyloPic image from available options - [`get_phylopic()`](https://rphylopic.palaeoverse.org/reference/get_phylopic.md) [`print(`*``*`)`](https://rphylopic.palaeoverse.org/reference/get_phylopic.md) [`print(`*``*`)`](https://rphylopic.palaeoverse.org/reference/get_phylopic.md) : Retrieve an image for a given PhyloPic uuid - [`plot(`*``*`)`](https://rphylopic.palaeoverse.org/reference/plot_phylopic.md) [`plot(`*``*`)`](https://rphylopic.palaeoverse.org/reference/plot_phylopic.md) : Preview a PhyloPic silhouette - [`get_attribution()`](https://rphylopic.palaeoverse.org/reference/get_attribution.md) : Get PhyloPic attribution data - [`browse_phylopic()`](https://rphylopic.palaeoverse.org/reference/browse_phylopic.md) : Browse PhyloPic for a given taxonomic name or uuid - [`save_phylopic()`](https://rphylopic.palaeoverse.org/reference/save_phylopic.md) : Save a PhyloPic image ## Adding silhouettes to plots Functions for adding silhouettes to various plots. - [`geom_phylopic()`](https://rphylopic.palaeoverse.org/reference/geom_phylopic.md) : Geom for adding PhyloPic silhouettes to a plot - [`phylopic_key_glyph()`](https://rphylopic.palaeoverse.org/reference/phylopic_key_glyph.md) : Use PhyloPics as legend key glyphs - [`scale_height_continuous()`](https://rphylopic.palaeoverse.org/reference/scales.md) [`scale_width_continuous()`](https://rphylopic.palaeoverse.org/reference/scales.md) : Scales for phylopic height or width - [`add_phylopic()`](https://rphylopic.palaeoverse.org/reference/add_phylopic.md) : Annotate a ggplot plot with PhyloPics - [`add_phylopic_base()`](https://rphylopic.palaeoverse.org/reference/add_phylopic_base.md) : Add PhyloPics to a base R plot - [`add_phylopic_legend()`](https://rphylopic.palaeoverse.org/reference/add_phylopic_legend.md) : Add a PhyloPic legend for a base R plot - [`add_phylopic_tree()`](https://rphylopic.palaeoverse.org/reference/add_phylopic_tree.md) : Add PhyloPics to a phylogenetic tree plotted with base R - [`phylopic_igraph`](https://rphylopic.palaeoverse.org/reference/phylopic_igraph.md) : Use PhyloPic silhouettes with igraph - [`clear_phylopic_cache()`](https://rphylopic.palaeoverse.org/reference/clear_phylopic_cache.md) : Clear the rphylopic cache ## Modifying silhouettes Functions to modify silhouettes in various ways. - [`flip_phylopic()`](https://rphylopic.palaeoverse.org/reference/flip_phylopic.md) : Flip a PhyloPic silhouette along its horizontal and/or vertical axis - [`rotate_phylopic()`](https://rphylopic.palaeoverse.org/reference/rotate_phylopic.md) : Rotate a PhyloPic silhouette - [`recolor_phylopic()`](https://rphylopic.palaeoverse.org/reference/recolor_phylopic.md) : Recolor a PhyloPic image # Articles ### All vignettes - [Getting started with rphylopic](https://rphylopic.palaeoverse.org/articles/a-getting-started.md): - [Advanced examples in ggplot](https://rphylopic.palaeoverse.org/articles/b-advanced-ggplot.md): - [Advanced examples in base R](https://rphylopic.palaeoverse.org/articles/c-advanced-base.md):