Advanced examples in base R"
In rphylopic: Get Silhouettes of Organisms from PhyloPic

Authors: William Gearty & Lewis A. Jones

Last updated: 2024-09-03

# Introduction Herein we provide three example applications of the **rphylopic** package using base R. However, note that all demonstrated functionality is also available for use with the `{ggplot2}` package and showcased in a [separate vignette](b-advanced-ggplot.html). # Basic accession and transformation The **rphylopic** package provides robust and flexible tools to access and transform PhyloPic silhouettes. Here we demonstrate this using the example dataset of Antarctic penguins from the `{palmerpenguins}` R package. First, let's load our libraries and the penguin data: wzxhzdk:0 Now, let's pick a silhouette to use for the penguins. Let's pick #2: wzxhzdk:1 You may have noticed in the preview that the silhouette was a little slanted. Let's rotate it clockwise just a smidgen: wzxhzdk:2 Now, let's clean the data and split the data among the three species: wzxhzdk:3 Now we're going to make a three panel plot, one panel for each species. Within each panel, we'll plot the penguins' bill lengths vs. their flipper lengths: wzxhzdk:4

plot of chunk base-penguin-plot-1

That's a nice basic plot! But you know what would make it nicer? If we added a penguin silhouette to the plot. Sadly, we don't have a different silhouette for each species (although we could make one...), so let's just go with putting a single silhouette in the top panel. To do that, we can use the `add_phylopic_base()` function. Note that the `x` and `y` arguments specify the center of the silhouette, and the `height` argument specifies how tall the silhouette is in the units of the y-axis. wzxhzdk:5

plot of chunk base-penguin-plot-2

Isn't that nifty! We can go a step further, though. What if we used little penguins instead of points?! To do that, we can once again use the `add_phylopic_base()` function. In this case, we can again specify `img = penguin_rot` since we want to use the same image for each x-y pair: wzxhzdk:6

plot of chunk base-penguin-plot-3

Oh no, the silhouettes are way too big! The default for `add_phylopic_base()` is to make the silhouette the same height as the plot, which is way too big for our case here. Let's make the size of the silhouettes relative to the penguins' body masses. A scaling factor of 8 seems to work well for this size figure. wzxhzdk:7

plot of chunk base-penguin-plot-4

Finally, let's give the female and male penguins different fill colors. We'll also add a legend to the last panel. wzxhzdk:8

plot of chunk base-penguin-plot-5

Now that's a nice figure! # Geographic distribution In much the same way as generic x-y plotting, the **rphylopic** package can be used in base R to plot organism silhouettes on a map. That is, to plot data points (e.g., species occurrences) as silhouettes. We provide an example here of how this might be achieved. For this application, we use the example occurrence dataset of early (Carboniferous to Early Triassic) tetrapods from the `{palaeoverse}` R package to visualize the geographic distribution of *Diplocaulus* fossils. First, let's load our libraries and the tetrapod data: wzxhzdk:9 Then we'll subset our occurrences to only those for *Diplocaulus*: wzxhzdk:10 Now, let's plot those occurrences on a world map. Here we use the `{geodata}` and `{raster}` packages to generate the map. Then we add colored points on top of this. Note that we use `alpha = 0.75` in case there are multiple occurrences in the same place. That way, the darker the color, the more occurrences in that geographic location. wzxhzdk:11

plot of chunk base-geog-plot-1

Now, as with the penguin figure above, we can easily replace those points with silhouettes. wzxhzdk:12

plot of chunk base-geog-plot-2

Snazzy! Note that we used the genus name as the `name` argument here. However, if we were plotting occurrences of multiple genera, we'd definitely want to plot them as different silhouettes using `name = tetrapods$genus`. # Phylogenetics Another common use case of PhyloPic silhouettes is to represent taxonomic information. In this example, we demonstrate how to use silhouettes within a phylogenetic framework. In this case, the phylogeny, taken from the `{phytools}` package, includes taxa across all vertebrates. Even many taxonomic experts are unlikely to know the scientific names of these 11 disparate taxa, so we'll replace the names with PhyloPic silhouettes. First, let's load our libraries and data: wzxhzdk:13 We can use a vectorized version of the `get_uuid()` function to retrieve UUID values for all of the species at once. However, just in case we get an error, we wrap the `get_uuid()` call in a `tryCatch()` call. This way, we should get either a UUID or `NA` for each species: wzxhzdk:14 wzxhzdk:15 Oh no, we weren't able to find a silhouette for *Myotis lucifugus* (little brown bat)! Good thing we used `tryCatch()`! Given the coarse resolution of this phylogeny, we can just grab a silhouette for the subfamily (Vespertilioninae): wzxhzdk:16 I'm also not a huge fan of the boar picture. Let's choose an alternative with `pick_phylopic()`. wzxhzdk:17 Now that we've got our phylogeny and UUIDs, we could go ahead and create our figure. However, time for a quick aside. The time required for `add_phylopic_base()` and the other **rphylopic** visualization functions scales with the number of *unique* names/UUIDs, not the number of plotted silhouettes. Therefore, if you are plotting a lot of *different* silhouettes, these functions can take quite a long time to poll PhyloPic for each unique name, download the silhouettes, and convert them to be added to the plot. If you plan to use the same silhouettes for multiple figures, we strongly suggest that you poll PhyloPic yourself using `get_phylopic()` or `pick_phylopic()`, save the silhouettes to your R environment, and then these use image objects in the visualization functions (with the `img` argument/aesthetic). Following this advice, let's get image objects for these 11 species before we make our figure. Note that, since we've used `get_uuid()` to get these 11 UUIDs, we know that they are valid, so we don't need to catch any errors this time. wzxhzdk:18 Now let's go ahead and plot our phylogeny with the `{ape}` package: wzxhzdk:19

plot of chunk base-phylo-plot-1

Hmm...that's a bit boring. Let's add a geological timescale to the bottom using `axis_geo_phylo()` from the `{palaeoverse}` package. wzxhzdk:20

plot of chunk base-phylo-plot-2

That's looking a lot prettier! Let's go ahead and replace the tip labels with our silhouettes now using `add_phylopic_base()`. Note that while it may look like all of the tips have an x-axis value of 0, that's actually a trick from `axis_geo_phylo()`. In reality, the left end of the x-axis is 0, and the right end of the x-axis is the total height of the tree. We can calculate this using the `nodeHeights()` function. wzxhzdk:21

plot of chunk base-phylo-plot-3

Note that only a single size is specified and aspect ratio is always maintained, hence why the silhouettes all have the same height but different widths. Let's fix some of the silhouettes by rotating them 90 degrees: wzxhzdk:22 And now the finished product: wzxhzdk:23