Contents

1 Introduction

In the evolving field of evolutionary biology and phylogenetics, visualizing phylomorphospace plays a pivotal role in understanding the diversification of traits across species within a phylogenetic framework. Phylomorphospace is a graphical representation that combines phylogenetic information and morphological (trait) data, mapping the evolutionary trajectories of species in a multidimensional space. However, as research progresses, datasets not only increase in size but also in the complexity of their relationships, which makes the visualization process more challenging and demands advanced visualization solutions.

Here, we introduce ggtreeSpace, a comprehensive visualization tool designed for plotting fully annotated phylomorphospaces using the grammar of graphics, offering researchers with extensive control and customization options for their phylomorphospace plots.

Currently, there are other Bioconductor packages like phytools that also support creating a phylomorphospace. phytools facilitates plotting with its phylomorphospace function, which allows for customization and annotation, including the ability to set edge and node colors. And it also supports plotting 3d phylomorphospace with phylomorphospace3d function.

Compares to phytools, ggtreeSpace focus on crafting 2D phylomorphospaces using the grammar of graphics, enabling the creation of fully annotated visualizations through a layer-by-layer annotation approach. This method provides researchers with a more intuitive and user-friendly experience in plotting, enhancing the logic and visualization clarity. ggtreeSpace not only includes unique layers specifically designed for phylomorphospace annotations but also supports layers from the ggplot2 and ggtree communities, offering a wide range of customization options. Additionally, it supports adding phylomorphospace as a graphic layer, enabling the combination of tree-like structures with various types of spaces, such as maps or histological staining images, thus broadening the applications of phylomorphospace analysis.

2 Installation

You can use the following commands to install ggtreeSpace:

if (!require("BiocManager"))
    install.packages("BiocManager")
BiocManager::install("ggtreeSpace")

2.1 Demonstration

library(ggtree)
library(ggtreeSpace)
library(phytools)
library(ggplot2)
library(dplyr)

ggtreeSpace serves as a wrapper for ggtree package. In the past, when users tried to plot phylomorphospace with ggtree, they needed to be familiar with the infrastructure of it and take multiple steps to achieve the most basic effects. This was not only inconvenient but also limited its usage in more complex analyses.

tr <- rtree(15)
td <- fastBM(tr, nsim = 2)

tda1 <- fastAnc(tr, td[, 1])
tda2 <- fastAnc(tr, td[, 2])
tda <- cbind(tda1, tda2)
tdn <- rbind(td, tda)


trd <- fortify(tr)
trd <- trd |>
        select(-c("x", "y")) |>
        mutate(
            x = tdn[, 1],
            y = tdn[, 2])

p <- ggtree(tr = trd,
            layout = "unrooted") +
        theme_bw()
## "daylight" method was used as default layout for unrooted tree.
p

Now with ggtreeSpace, users can plot basic phylomorphospace easily with the ggtreespace function, and add annotation to it with the + operator. In this example, we add symbolic point to the tip of phylomorphospace. From the phylomorphospace plot, we can observe the evolutionary trajectories of different species, illustrating how they diverge and adapt in their respective trait dimensions. This visual representation allows us to identify patterns of convergence and divergence among species, highlight instances of adaptive radiation, and so on.

ggtreespace(tr, td) +
    geom_tippoint()

ggtreeSpace also supports adding phylomorphospace as a graphic layer. This can broaden the applications of phylomorphospace analysis by combine the tree-like structure with different types of spaces.

tr1 <- rtree(15)
td1 <- fastBM(tr1, nsim = 2)
ggplot() +
    geom_treespace(tr1, td1)

You can also introduce an additional heatmap layer based on your data, adding another dimension of data to better elucidate how this data can affect evolutionary patterns. For example, species may cluster together in the morphospace due to shared environmental adaptations, and we can visualize this through the heatmap. This can provide insights into the underlying mechanisms driving species evolution and diversification.

tr <- rtree(15)
td <- fastBM(tr, nsim = 2, bounds = c(0, Inf))
col <- colorRampPalette(c(
    "#FFFFCC", "#FFEDA0", "#FED976", "#FEB24C",
    "#FD8D3C", "#FC4E2A", "#E31A1C", "#B10026"
))(24)
tdex <- data.frame(
    z = fastBM(tr, nsim = 1, bounds = c(0, Inf)),
    node = 1:15
)
p <- ggtreespace(tr, td)
p %<+% tdex +
    geom_tippoint() +
    geom_tsheatmap(
        trait = "z", alpha = 0.7,
        resolution = 0.01, bin = 24
    ) +
    scale_fill_manual(
        values = col,
        guide = guide_colorsteps(show.limits = TRUE)
    ) +
    theme_treespace2() +
    theme(
        legend.key.height = unit(1, "null"),
        legend.justification.top = "right"
    )
## Warning: Removed 26842 rows containing non-finite outside the scale range
## (`stat_contour_filled()`).

3 Session information

Here is the output of sessionInfo() on the system on which this document was compiled:

## R Under development (unstable) (2024-10-21 r87258)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.1 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.21-bioc/R/lib/libRblas.so 
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_GB              LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: America/New_York
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] dplyr_1.1.4       ggplot2_3.5.1     phytools_2.3-0    maps_3.4.2       
## [5] ape_5.8           ggtreeSpace_1.3.0 ggtree_3.15.0     BiocStyle_2.35.0 
## 
## loaded via a namespace (and not attached):
##  [1] fastmatch_1.1-4         gtable_0.3.6            xfun_0.48              
##  [4] bslib_0.8.0             lattice_0.22-6          numDeriv_2016.8-1.1    
##  [7] quadprog_1.5-8          vctrs_0.6.5             tools_4.5.0            
## [10] generics_0.1.3          yulab.utils_0.1.7       parallel_4.5.0         
## [13] tibble_3.2.1            fansi_1.0.6             highr_0.11             
## [16] pkgconfig_2.0.3         Matrix_1.7-1            ggplotify_0.1.2        
## [19] scatterplot3d_0.3-44    lifecycle_1.0.4         compiler_4.5.0         
## [22] farver_2.1.2            deldir_2.0-4            treeio_1.31.0          
## [25] tinytex_0.53            munsell_0.5.1           mnormt_2.1.1           
## [28] combinat_0.0-8          codetools_0.2-20        ggfun_0.1.7            
## [31] htmltools_0.5.8.1       sass_0.4.9              yaml_2.3.10            
## [34] lazyeval_0.2.2          pillar_1.9.0            jquerylib_0.1.4        
## [37] tidyr_1.3.1             MASS_7.3-61             cachem_1.1.0           
## [40] clusterGeneration_1.3.8 magick_2.8.5            iterators_1.0.14       
## [43] foreach_1.5.2           nlme_3.1-166            phangorn_2.12.1        
## [46] tidyselect_1.2.1        aplot_0.2.3             digest_0.6.37          
## [49] purrr_1.0.2             bookdown_0.41           labeling_0.4.3         
## [52] fastmap_1.2.0           grid_4.5.0              colorspace_2.1-1       
## [55] expm_1.0-0              cli_3.6.3               magrittr_2.0.3         
## [58] patchwork_1.3.0         optimParallel_1.0-2     utf8_1.2.4             
## [61] withr_3.0.2             scales_1.3.0            DEoptim_2.2-8          
## [64] rmarkdown_2.28          igraph_2.1.1            interp_1.1-6           
## [67] coda_0.19-4.1           evaluate_1.0.1          knitr_1.48             
## [70] doParallel_1.0.17       gridGraphics_0.5-1      rlang_1.1.4            
## [73] isoband_0.2.7           Rcpp_1.0.13             glue_1.8.0             
## [76] tidytree_0.4.6          BiocManager_1.30.25     jsonlite_1.8.9         
## [79] R6_2.5.1                fs_1.6.4