rphylopic: An R package for fetching, transforming, and visualising PhyloPic silhouettes

Effective data visualisation is vital for data exploration, analysis and communication in research. In ecology and evolutionary biology, data are often associated with various taxonomic entities. Graphics of organisms associated with these taxa are valuable for framing results within a broader biological context. However, acquiring and using such resources can be challenging due to availability and licensing constraints. The PhyloPic database solves many of these issues by making organism silhouettes freely available. Tools that integrate this database with existing research workflows are needed to remove hurdles associated with data visualisation in the biological sciences. Here, we introduce rphylopic, an R package for fetching, transforming and visualising silhouettes of organisms from the PhyloPic database. In addition to making over 8000 organism silhouettes available within the R programming language, rphylopic empowers users to modify the appearance of these silhouettes for ultimate customisability when coding production–quality visualisations in both base R and ggplot2 workflows. In this work, we provide details about how the package can be installed, its implementation and potential use cases. For the latter, we showcase three examples across the ecology and evolutionary biology spectrum. Our hope is that rphylopic will make it easier for biologists to develop more accessible and engaging data visualisations by making external resources readily accessible, customisable and usable within R. In turn, by integrating into existing workflows, rphylopic helps to ensure that science is reproducible and accessible.

the taxonomic affinity, availability and licensing of such resources can be hurdles to incorporating them into research articles.
PhyloPic (https://www.phylopic.org) solves many of the aforementioned hurdles by providing an online open-access database of silhouette images of animals, plants and other life forms.To date, the silhouettes have been created by over 500 volunteer contributors, are available for reuse under various Creative Commons licences and are stored within a taxonomic/phylogenetic framework (e.g.phylum Mollusca and clade pan-Mollusca are both valid).
While PhyloPic is almost never cited within scientific publications, silhouettes from the database have been utilised to convey taxonomic information effectively and simply for innumerable scientific articles, conference contributions and much more.However, despite this already wide array of applications, usage hurdles exist due to its platform-agnostic nature.For example, while silhouettes can be downloaded in raster or vector formats, these can still be difficult to integrate into a coding-based scientific workflow, especially when the user is trying to maintain reproducibility.Often, custom code and/or postproduction editing are required to accommodate these images.
Here, we describe rphylopic, a dedicated R package for interfacing with the PhyloPic database.The package contains functions for accessing, transforming and visualising PhyloPic silhouettes.We first provide instructions for installing the package and details on its implementation.Second, we demonstrate the functionality available in rphylopic through usage examples.Finally, we provide details about the resources we have made available to the community and to support rphylopic users.

| I N S TA LL ATI O N
The rphylopic package can be installed from CRAN using the install.packages function in R (R Core Team, 2023): install.packages("rphylopic") If preferred, the development version of rphylopic can be installed from GitHub via the remotes R package (Csárdi et al., 2023): remotes::install_github("palaeoverse-community/rphylopic") Following installation, rphylopic can be loaded via the library function in R: library("rphylopic")

| IMPLEMENTATION
A summary of the functions currently available in rphylopic is provided in Table 1.Detailed description is provided below followed by usage examples to demonstrate the functionality and versatility of the package.

| Fetching
Image data (i.e.silhouettes) are fetched from the PhyloPic application programming interface service via the get_phylopic function.
The function requires an image universally unique identifier (UUID), which can be provided by the user for a known silhouette.If the # Get data for an image img_vec <-get_phylopic(uuid = uuid, format = "vector") # vector format img_ras <-get_phylopic(uuid = uuid, format = "raster") # raster format Silhouettes can be returned as both Scalable Vector Graphics (SVG) and Portable Network Graphics (PNG), depending on the userdefined format ('vector' and 'raster', respectively).An additional argument (height) can be defined for the 'raster' format to control the image height in pixels (larger height values result in higher resolutions).However, in most cases, we encourage users to use the default 'vector' format to maintain the highest quality possible.
Multiple silhouettes can exist for a single taxonomic name in PhyloPic, particularly at higher taxonomic levels.To help facilitate user selection from various image silhouettes, we provide the pick_phylopic function to enable users to interactively pick an image through visualising the available options (Figure 1): img_pick <-pick_phylopic(name = "Scleractinia", view = 4) The function save_phylopic is provided to allow users to conveniently save any vector silhouettes in a range of formats, including the following: Portable Document Format (PDF), Portable Network Graphics (PNG), Scale Vector Graphics (SVG), Tag Image File Format (TIFF), Joint Photographic Experts Group (JPEG) and bitmap (BMP).Note, this is not required if all further transformations and visualisations will be conducted within R; however, we include this function for users who may still need to use these silhouettes outside R.

| Transformation
Once a silhouette is picked and saved in the user's R environment, it may be useful to transform the image to better suit the particular visualisation of interest.We have implemented three user-friendly functions to accommodate three transformations that might be # Change colour to blue and transparency to 50% img_col <-recolor_phylopic(img = img_vec, alpha = 0.5, fill = "blue") For convenience, we have also included these transformation options within all of the visualisation functions discussed in the next section.However, when the same transformed silhouette will be used for multiple visualisations, we suggest transforming the silhouette first, saving it as a new object, then using this new object for visualisation purposes.

| Visualisation
In recognition of the wide range of users who may use the package,

| Attribution
The rphylopic package gathers resources (i.

| 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 data set of Antarctic penguins from the palmerpenguins R package (Horst et al., 2020).Since we do not know which silhouette we want to use, we first use pick_phylopic to identify a suitable silhouette for Pygoscelis.We then rotate this silhouette and use it instead of points for a standard x-y plot showing the relationship between bill length and flipper length (Figure 2).
Note that we modify the size and fill of the silhouette based on the mass and sex of each penguin, respectively.The fill aesthetic can be used to modify the body colour of the silhouette, while the colour aesthetic is used for modifying the outline colour.Here, we specify colour = NA to leave the outline transparent.As with all ggplot-related functions, geom_phylopic accepts both 'color' and 'colour' as aesthetic names.scale_size_continuous(guide = "none") + scale_fill_manual("Sex", values = c("orange", "blue"), labels = c("Female", "Male")) + facet_wrap(~species, ncol = 1) + theme_bw(base_size = 15) + theme(legend.position= c(0.9,0.9))

| Geographic distribution
In much the same way as generic x-y plotting, the rphylopic package can be used in combination with ggplot2 (Wickham, 2016) to plot organism silhouettes on a map (Figure 3).That is, to plot data points (e.g.species occurrences) as silhouettes.We provide an example here of how this might be achieved for individuals who wish to do so.
For this application, we use the example occurrence data set of early (Carboniferous to Early Triassic) tetrapods from the palaeoverse R package (Jones et al., 2023) to visualise the geographic distribution of Diplocaulus fossils.

| 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 (Figure 4).In this case, the phylogeny, from the phytools R package (Revell, 2012), includes taxa across all vertebrates.Even many taxonomic experts are unlikely to know the scientific names of these 11 disparate taxa, so we replace the names with PhyloPic silhouettes.We use the ggtree R package (Yu et al., 2017) to plot the phylogeny and the deeptime R package (Gearty, 2023) to add a geological timescale to the background.We use a vectorised version of the get_uuid function to retrieve UUID values for all of the species at once; however, one of the scientific names is not matched in the PhyloPic database so we need to use a higher taxonomic name.We also choose to use the pick_phylopic function to select a specific image for the boar.
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.

F
An example of the output from pick_phylopic for selecting image silhouettes.The image silhouettes are from PhyloPic (https://www.phylopic.org; Keesey, 2023).Silhouette 1 was contributed by Victor Piñon-González (2023; CC0 1.0), and silhouettes 2-4 were contributed by Guillaume Dera (2022; CC0 1.0).desired by the user: flipping, rotating and recolouring.All three functions work on both vector and raster versions of silhouettes.The flip_phylopic function can be used to flip a silhouette horizontally and/or vertically.This may be useful if, for example, the user wants all of the silhouettes to face the same direction.# Flip silhouette horizontally img_flip <-flip_phylopic(img = img_vec, horizontal = TRUE, vertical = FALSE) The rotate_phylopic function can be used to rotate a silhouette an arbitrary number of degrees.This may be useful when trying to align a silhouette with text or other objects within a figure.# Rotate silhouette by 45 degrees img_rot <-rotate_phylopic(img = img_vec, angle = 45) Finally, the recolor_phylopic function can be used to modify the fill colour, outline colour and/or transparency of a silhouette.The vast majority of PhyloPic silhouettes are black and fully opaque by default.However, it may be useful to change this when the user is trying to either match an existing visualisation colour palette or trying to convey extra information, such as categorical data, through colour.
we have included functions to add the desired PhyloPic silhouettes to both base R and ggplot2 plots.Furthermore, for convenience, each of the following functions works with the names of species/clades (the name argument/aesthetic), UUIDs (the uuid argument/aesthetic) or image objects (vector or raster) (the img argument/aesthetic).For simplicity, we will only showcase the use of names here.The add_phylopic_base function can be used to add one or more silhouettes to a base R plot.The function behaves very similarly to the base R points function, where x and y coordinates are supplied for the centres of the silhouettes.The ysize argument can be used to vary the size of the silhouettes.For convenience, if any of these arguments are vectors, the other arguments will be recycled as necessary.For example, a single silhouette can be plotted at multiple x and y coordinates, or multiple silhouettes can be plotted at multiple y coordinates but all with the same x coordinate.#Make a simple base R plot plot(x = 0:10, y = 0:10, type = "n", main = "A cat") # Add a cat in multiple places add_phylopic_base(name = "Felis catus", x = seq(2, 8, 2), y = seq(2, 8, 2), ysize = 2)The equivalent function for ggplot2 usage is the add_phylopic function, which adds PhyloPic silhouettes as a separate layer to an existing ggplot object.It works very similarly to the annotate function in the ggplot2 package(Wickham, 2016).A common use case for this is to add a PhyloPic silhouette as a background image: # Load the ggplot2 package library(ggplot2) # Make a simple ggplot plot with a faded iris flower in the background ggplot(iris) + add_phylopic(x = 6.1, y = 3.2, name = "Iris", alpha = 0.2) + geom_point(aes(x = Sepal.Length, y = Sepal.Width))In case the user already has a data.frame of data, we have also provided the geom_phylopic function, which acts like the geom_point function from ggplot2, except the specified silhouettes are used as points.This can be combined with other functions (e.g.facet_wrap) from ggplot2 and other packages to create complex visualisations: # Assemble a data.framedf <-data.frame(x= 2:5, y = seq(10, 25, 5), name = c("leopard", "walrus", "house mouse", "iris")) # Plot each silhouette in its own panel ggplot(df) + geom_phylopic(aes(x = x, y = y, name = name), colour = "purple", size = 10) + facet_wrap(~name) + coord_cartesian(xlim = c(1,6), ylim = c(5, 30)) As mentioned above, for convenience, these three functions all allow for transformations during the plotting stage.For the add_phylopic and add_phylopic_base functions, horizontal, vertical, alpha, color and fill are arguments.For the geom_phylopic function, these are ggplot2 aesthetics.These transformations work whether silhouettes are specified as names, UUIDs or image objects.
e. silhouettes) from the PhyloPic database.The silhouettes are made available under various Creative Common copyright licences and should be appropriately attributed when used (see figure captions for examples).To help facilitate this process, including automatic generation of attribution statements, we provide the function get_attribution: # Get valid uuid uuid <-get_uuid(name = "Acropora cervicornis") # Get attribution data for uuid att <-get_attribution(uuid = uuid) # Get attribution data for uuid as text output get_attribution(uuid = uuid, text = TRUE) This function returns attribution data for a specific image UUID, including the following: contributor name, contributor UUID, contributor contact, image UUID and the type of licence.While not requested by the creator of PhyloPic (T.Michael Keesey), we also encourage acknowledgement of his work.Note, when requesting a UUID (get_uuid) or image (pick_phylopic, geom_phylopic, add_phylopic, add_phylopic_base), the results can be filtered to exclude specific copyright licences that might not be appropriate in some instances (e.g. with a ShareAlike clause that is often incompatible with use in journal publications): # Exclude images with a ShareAlike clause uuid <-get_uuid(name = "Bacteria", filter = "sa") img <-pick_phylopic(name = "Bacteria", filter = "sa") If you use the rphylopic package in your workflow, we also ask that you cite the package appropriately.A citation for the package can be accessed via the function citation: citation("rphylopic")4 | APPLI C ATI ONHerein, we provide three example applications of the rphylopic package in combination with ggplot2(Wickham, 2016).These examples are greatly expanded in an associated step-by-step vignette of the package.All of this demonstrated functionality is also available for base R and showcased in a separate step-bystep vignette of the package.The vignettes are available online (https://rphyl opic.palaeoverse.org/articles/) and are also bundled with the package: browseVignettes("rphylopic")
Summary table of the functions currently available in the rphylopic R package.
TA B L E 1