# Plot a Phylogeny with Organismal Silhouettes from PhyloPic, Called Via the Paleobiology Database API This function will take a phylogeny, preferably a taxonomy-tree created from classification information and/or parent-child taxon information pulled from the Paleobiology Database via function `makePBDBtaxonTree`, and use the Paleobiology Database's API to plot silhouettes of each given tip taxon in replacement of their normal tip labels. ```r plotPhyloPicTree( tree, taxaDataPBDB = tree$taxaDataPBDB, maxAgeDepth = NULL, depthAxisPhylo = FALSE, colorAxisPhylo = "black", addTaxonStratDurations = FALSE, taxaStratRanges = tree$tipTaxonFourDateRanges, stratDurationBoxWidth = 0.7, sizeScale = 0.9, removeSurroundingMargin = TRUE, orientation = "rightwards", resetGrPar = TRUE, taxaColor = NULL, transparency = 1, cacheDir = "cachedPhyloPicPNGs", cacheImage = TRUE, noiseThreshold = 0.1, rescalePNG = TRUE, trimPNG = TRUE, colorGradient = "original", failIfNoInternet = TRUE, ... ) ``` ## Arguments - `tree`: A phylogeny of class `phylo` which will be plotted, with the terminal tip taxa replaced by silhouettes. The tree will be plotted with edge lengths. - `taxaDataPBDB`: A `data.frame` of taxonomic data from the Paleobiology Database containing an `$image_no` variable, as returned when `show = "img"` is used. See **Details**. - `maxAgeDepth`: The maximum tree depth displayed for a tree given with branch lengths (age depth for a dated tree). The portion of the phylogeny older than this date will not be shown. `NULL` by default. If provided, the input tree must have branch lengths in `tree$edge.length`. - `depthAxisPhylo`: If `TRUE`, the `ape` function `axisPhylo` is run to add an axis of the tree depth to the tree, which must have branch lengths. `FALSE` by default. If `removeSurroundingMargin = TRUE`, which removes extraneous margins, the margins of the plot will be adjusted to make room for the plotted axis. - `colorAxisPhylo`: A color in which the axis for the phylogenetic's depth (generally a time-scale) will be plotted in, for both the axis, its tickmarks, and the labels for the tickmarks. - `addTaxonStratDurations`: If `TRUE`, solid color boxes are plotted on the tree to indicated known taxon ranges, from the oldest possible for the oldest known observation of that taxon, to the youngest possible age for the youngest known observation of that taxon. This information needs to be supplied as input, see argument `taxaStratRanges`. If `FALSE` (the default), nothing happens. - `taxaStratRanges`: A matrix of four-date range information, as is often used when converting Paleobiology Database taxon data to a dated tree. By default, this is expected to be located at `tree$tipTaxonFourDateRanges`, which is where such data is placed by default by the function `dateTaxonTreePBDB`. If `addTaxonStratDurations = FALSE` (the default), this data is not checked for. - `stratDurationBoxWidth`: The width of the stratigraphic duration boxes plotted for taxa on the tree. By default, this is 0.7 units. If `addTaxonStratDurations = FALSE` (the default), this argument affects nothing. - `sizeScale`: The default is `sizeScale = 0.9`. - `removeSurroundingMargin`: This argument controls the `no.margin` argument in the function `plot.phylo`, which controls whether a (very large) margin is placed around the plotted tree, or not. By default, `plotPhyloPicTree` will suppress that margin, so that the plotted tree goes (very nearly) to the edges of the plotting area. - `orientation`: Controls the direction the phylogeny is plotted in - can be either "rightwards" or "upwards". - `resetGrPar`: If `TRUE` (the default), the graphic parameters are reset, so that choices of margins and coordinate system manipulation done as part of this function do not impact the next plot made in this graphic device. If you need to add additional elements to the plot after running this function within R, you should set this argument to `FALSE`. - `taxaColor`: Controls the color of plotted PhyloPics. Can either be `NULL` (the default, all taxa will be plotted as black), or a character vector that is either length 1, or the same length as the number of taxa. If `taxaColor` is length 1, then the value is either interpreted as matching a tip label (in which case, the named taxon will be highlighted in bright red), or as a color, which all PhyloPics will then be plotted as that color. If the vector is the same length as the number of taxa on `tree`, each value should be a character value of a named color in base R, allowing user control over each PhyloPic individually. All PhyloPics expressed in colors other than the default black are transformed as under the argument `colorGradient = "trueMonochrome"`, so that the PhyloPic is expressed with no intermediate gray-scale values. - `transparency`: A numeric value between 0 and 1, either length 1, or the same length as the number of tips on `tree`. This indicates the transparency of either all the plotted PhyloPics, or allows user control over each PhyloPic individually. The default is 1, which represents maximum opaqueness, applied to all PhyloPics. - `cacheDir`: If not `NULL`, this value is used as the name of a sub-directory of the working directory for which to look for (or store) cached versions of PhyloPic PNGs to save on processing speed and the need to pull the images from an external PNG. If `NULL`, then cached images will not be checked for, and images downloaded will not be cached. The default is - `cacheImage`: If `TRUE` (the default), images downloaded from the Paleobiology Database and/or the PhyloPic Database will be cached to save on processing speed and avoid the need to pull the images from an external PNG. - `noiseThreshold`: A threshold for noise in the PNG from PhyloPic to be treated as meaningless noise (i.e. a color that is effectively whitespace) and thus can be trimmed as empty margin which can be trimmed before the silhouette is plotted. The units for this argument are on a scale from 0 to 1, with 0 being true white space, and values between 0 and 0.5 representing colors closer to whitespace than true black. The default is `noiseThreshold = 0.1`. - `rescalePNG`: If `TRUE` (the default), the downloaded PhyloPic has its color values rebalanced to go from the most extreme white to the most extreme black. Some (especially PBDB's versions) have varying levels of gray compression-related artifacts and may not be properly on a black-to-white scale. - `trimPNG`: If `TRUE` (the default), the PhyloPic PNG is trimmed to remove extraneous whitespace from the top and bottom, before rescaling of the color values of the PNG. - `colorGradient`: Controls the depth gradient of color for the PhyloPics. For typical plotting in black color, this means adjusting the grayscale (and possibly removing any gray scale). Most of the silhouettes are binary black-and-white already but some aren't, but those gray-scale values (sometimes?) seem to exist to indicate very fine features. However, maybe an image is far too much gray-scale, in which case users can apply this argument. If `colorGradient = "original"` (the default), then nothing is adjusted. If `colorGradient = "trueMonochrome"`, the entire image's gradients are simplified to a duality: either fully colored or fully transparent. If `colorGradient = "increaseDisparity"`, then a slightly less extreme option is applied, with values transformed to greatly remove in-between gray-scale value, shifting them toward color or not-color without making the silhouette purely monochrome. - `failIfNoInternet`: If the Paleobiology Database or another needed internet resource cannot be accessed, perhaps because of no internet connection, should the function fail (with an error) or should the function return `NULL` and return an informative message instead, thus meeting the CRAN policy that such functionalities must 'fail gracefully'? The default is `TRUE` but all examples that might be auto-run use `FALSE` so they do not fail during R CHECK. - `...`: Additional arguments, passed to `plot.phylo` for plotting of the tree. These additional arguments may be passed to `plot`, and from there to `plot`. Some arguments are reserved and cannot be passed, particularly: `direction`, `show.tip.label`, `no.margin`, `plot`, `xlim`, and`ylim`. ## Returns This function silently returns the positions for elements in the tree (.e. the environmental information obtained about the previous plotting environment of the tree as plotted), along with a saved set of the graphic parameters as they were at the end of the function's run. ## Details This function preferably will pull the identifiers for which images are to be associated with the tip taxa from `taxaDataPBDB$image_no`. By default, `taxaDataPBDB` itself is assumed to be an element of `tree` named `tree$taxaData`, as the PBDB data table used to construct the tree is appended to the output tree when `makePBDBtaxonTree` is used to construct a taxonomy-tree. If the functions listed in `getDataPBDB` are used to obtain the taxonomic data, this table will include the `image_no` variable, which is the image identifier numbers needed to call PNGs from the Paleobiology Database API. If `taxaDataPBDB` isn't provided, either by the user directly, or as an element of `tree`. ## Examples ```r # Note that some examples here use argument # failIfNoInternet = FALSE so that functions do # not error out but simply return NULL if internet # connection is not available, and thus # fail gracefully rather than error out (required by CRAN). # Remove this argument or set to TRUE so functions DO fail # when internet resources (paleobiodb) is not available. library(paleotree) taxaAnimals<-c("Archaeopteryx", "Eldredgeops", "Corvus", "Acropora", "Velociraptor", "Gorilla", "Olenellus", "Lingula", "Dunkleosteus", "Tyrannosaurus", "Triceratops", "Giraffa", "Megatheriidae", "Aedes", "Histiodella", "Rhynchotrema", "Pecten", "Homo", "Dimetrodon", "Nemagraptus", "Panthera", "Anomalocaris") animalData <-getSpecificTaxaPBDB(taxaAnimals, failIfNoInternet = FALSE) if(!is.null(animalData)){ tree <- makePBDBtaxonTree( animalData, rankTaxon = "genus", failIfNoInternet = FALSE ) plotPhyloPicTree(tree = tree, failIfNoInternet = FALSE) # let's plot upwards but at a funny size dev.new(height = 5, width = 10) plotPhyloPicTree(tree = tree, orientation = "upwards", failIfNoInternet = FALSE) # dated tree plotting #date the tree timeTree <- dateTaxonTreePBDB(tree, minBranchLen = 10) plotPhyloPicTree(tree = timeTree) # plotting the dated tree with an axis plotPhyloPicTree( tree = timeTree, depthAxisPhylo = TRUE) # now upwards! plotPhyloPicTree(tree = timeTree, orientation = "upwards", depthAxisPhylo= TRUE) ################################### # plotting a time tree with stratigraphic ranges plotPhyloPicTree(tree = timeTree, addTaxonStratDurations = TRUE) plotPhyloPicTree(tree = timeTree, addTaxonStratDurations = TRUE, orientation = "upwards", depthAxisPhylo= TRUE) ################################################ # adjusting a tree to ignore a very old root # let's pretend that metazoans are extremely old treeOldRoot <- timeTree rootEdges <- timeTree$edge[,1] == (Ntip(timeTree)+1) rootEdgeLen <- timeTree$edge.length[rootEdges] treeOldRoot$edge.length[rootEdges] <- rootEdgeLen + 1500 treeOldRoot$root.time <- NULL # plot it plot(treeOldRoot) axisPhylo() # yep, that's really old # let's plot it now with the PhyloPic plotPhyloPicTree(tree = treeOldRoot, depthAxisPhylo = TRUE) # let's crop that old lineage plotPhyloPicTree(tree = treeOldRoot, maxAgeDepth = 500, depthAxisPhylo = TRUE) # cool! ################################## # playing with colors plotPhyloPicTree(tree = tree, taxaColor = "green") # inverting the colors par(bg="black") taxaColors <- rep("white",Ntip(tree)) # making a red giraffe taxaColors[4] <- "red" plotPhyloPicTree( tree = tree, orientation = "upwards", edge.color = "white", taxaColor=taxaColors) } # end if to test if animalData was NULL # end donttest segment ###################################### ## Not run: # let's try some different phylopics # like a nice tree of commonly known tetrapods tetrapodList<-c("Archaeopteryx", "Columba", "Ectopistes", "Corvus", "Velociraptor", "Baryonyx", "Bufo", "Rhamphorhynchus", "Quetzalcoatlus", "Natator", "Tyrannosaurus", "Triceratops", "Gavialis", "Brachiosaurus", "Pteranodon", "Crocodylus", "Alligator", "Giraffa", "Felis", "Ambystoma", "Homo", "Dimetrodon", "Coleonyx", "Equus", "Sphenodon", "Amblyrhynchus") tetrapodData <-getSpecificTaxaPBDB(tetrapodList) tree <- makePBDBtaxonTree(tetrapodData, rankTaxon = "genus") plotPhyloPicTree(tree = tree) #################################### # let's check our speed increase from caching! # can try this on your own machine #first time system.time(plotPhyloPicTree(tree = tree)) # second time system.time(plotPhyloPicTree(tree = tree)) ################################## # make a pretty plot taxaSeventyEight <- c( "Archaeopteryx", "Pinus", "Procoptodon", "Olenellus", "Eldredgeops", "Quetzalcoatlus", "Homo", "Tyrannosaurus", "Triceratops", "Giraffa", "Bolivina", "Cancer", "Dicellograptus", "Dunkleosteus", "Solanum", "Anomalocaris", "Climacograptus", "Halysites", "Cyrtograptus", "Procoptodon", "Megacerops", "Moropus", "Dimetrodon", "Lingula", "Rhynchosaurus", "Equus", "Megaloceros", "Rhynchotrema", "Pecten", "Echinaster", "Eocooksonia", "Neospirifer", # "Prototaxites", "Cincinnaticrinus", "Nemagraptus", "Monograptus", "Pongo", "Acropora", "Histiodella", "Agathiceras", "Juramaia", "Opabinia", "Arandaspis", "Corvus", "Plethodon", "Latimeria", "Phrynosoma", "Araucarioxylon", "Velociraptor", "Hylonomus", "Elginerpeton", "Rhyniognatha", "Tyto", "Dromaius", "Solenopsis", "Gorilla", "Ginkgo", "Terebratella", "Caretta", "Crocodylus", "Rosa", "Prunus", "Lycopodium", "Meganeura", "Diplodocus", "Brachiosaurus", "Hepaticae", "Canadaspis", "Pikaia", "Smilodon", "Mammuthus", "Exaeretodon", "Redondasaurus", "Dimetrodon", "Megatheriidae", "Metasequoia", "Aedes", "Panthera", "Megalonyx") dataSeventyEight <-getSpecificTaxaPBDB(taxaSeventyEight) tree <- makePBDBtaxonTree(dataSeventyEight, rankTaxon = "genus") timeTree <- dateTaxonTreePBDB(tree, minBranchLen = 10) date <- format(Sys.time(), "%m-%d-%y") file <- paste0( "tree_taxa78_phylopic_stratTree_", date, ".pdf") png(file = file, height = 5, width = 12, units = "in", res = 300) par(bg="black") par(mar=c(0,0,3,0)) taxaColors <- rep("white", Ntip(timeTree)) taxaColors[4] <- "red" plotPhyloPicTree( tree = timeTree, orientation = "upwards", addTaxonStratDurations = TRUE, edge.color = "white", maxAgeDepth = 700, taxaColor=taxaColors, depthAxisPhylo = TRUE, colorAxisPhylo = "white") dev.off() shell.exec(file) ## End(Not run) ``` ## References Peters, S. E., and M. McClennen. 2015. The Paleobiology Database application programming interface. **Paleobiology** 42(1):1-7. ## See Also See `getDataPBDB`, `makePBDBtaxonTree`, and `plotPhyloPicTree`. ## Author(s) David W. Bapst

plotPhyloPicTree function