tanggle_vignette.knit

# 1 Introduction

Here we present a vignette for the R package tanggle, and provide an overview of its functions and their usage. Tanggle extends the ggtree R package (???) to allow for the visualization of several types of phylogenetic networks using the ggplot2 (???) syntax. More specifically, tanggle contains functions to allow the user to effectively plot: (1) split (i.e. implicit) networks (unrooted, undirected) and (2) explicit networks (rooted, directed) with reticulations. It offers an alternative to the plot functions already available in ape (???) and phangorn (???).

# 2 List of functions

Function name | Brief description
--- | ---
`geom_splitnet` | Adds a splitnet layer to a ggplot, to combine visualising data and the network
`ggevonet` | Plots an explicit network from a phylo object
`ggsplitnet` | Plots an implicit network from a phylo object
`minimize_overlap` | Reduces the number of reticulation lines crossing over in the plot
`node_depth_evonet` | Returns the depths or heights of nodes and tips in the phylogenetic network

# 3 Getting started

Install the package from Bioconductor directly:

    if (!requireNamespace("BiocManager", quietly = TRUE))
        install.packages("BiocManager")

    BiocManager::install("tanggle")

Or install the development version of the package from Github.

    if (!requireNamespace("remotes", quietly=TRUE))
        install.packages("remotes")
    remotes::install_github("KlausVigo/tanggle")

If you need to install ggtree from github:

    remotes::install_github("YuLab-SMU/ggtree")

And load all the libraries:

    library(tanggle)
    library(phangorn)
    library(ggtree)

# 4 Split Networks

Split networks are data-display objects which allow for the definition of 2 (or more) options for non-compatible splits. Split networks are most often used to visualize consensus networks (???) or neighbor-nets (???). This can be done either by using the `consensusNet` or `neighbor-net` functions in phangorn (???) or by importing nexus files from SplitsTree (???).

## 4.1 Data Types

tanggle accepts three forms of input data for split networks. The following input options all generate a networx object for plotting.

- Nexus file created with SplitsTree (???) and read with the `read.nexus.network` function in phangorn (???).

- Read in a split network in nexus format:

    fdir <- system.file("extdata/trees", package = "phangorn")
    Nnet <- phangorn::read.nexus.networx(file.path(fdir,"woodmouse.nxs"))

2. A collection of gene trees (e.g.~from RAxML (???)) in one of the following formats:
   - Nexus file read with the function `read.nexus`
   - Text file in Newick format (one gene tree per line) read with the function `read.tree` A consensus split network is then computed using the function `consensusNet` in phangorn (???).

- Sequences in nexus, fasta or phylip format, read with the function `read.phyDat` in phangorn (???) or the function `read.dna` in ape (???). Distances matrices are then computed for specific models of evolution using the function `dist.ml` in phangorn (???) or `dist.dna` in ape (???). From the distance matrix, a split network is reconstructed using the function `neighborNet` in phangorn (???). Optional: branch lengths may be estimated using the function `splitsNetworks` in phangorn (???).

## 4.2 Plotting a Split Network:

We can plot the network with the default options:

    p <- ggsplitnet(Nnet) + geom_tiplab2()
    p

When we can set the limits for the x and y axis so that the labels are readable.

    p <- p + xlim(-0.019, .003) + ylim(-.01,.012)
    p

You can rename tip labels. Here we changed the names to species from 1 to 15:

    Nnet$translate$label <- seq_along(Nnet$tip.label)

We can include the tip labels with `geom_tiplab2`, and customize some of the options. For example, here the tip labels are in blue and both in bold and italics, and we show the internal nodes in green:

    ggsplitnet(Nnet) + geom_tiplab2(col = "blue", font = 4, hjust = -0.15) +
        geom_nodepoint(col = "green", size = 0.25)

Nodes can also be annotated with `geom_point`.

    ggsplitnet(Nnet) + geom_point(aes(shape=isTip, color=isTip), size=2)

## 4.3 Plotting Explicit Networks

The function `ggevonet` plots explicit networks (phylogenetic trees with reticulations). A recent addition to ape (???) made it possible to read in trees in extended newick format (???).

Read in an explicit network (example from Fig. 2 in Cardona et al. 2008):

    z <- read.evonet(text = "((1,((2,(3,(4)Y#H1)g)e,(((Y#H1,5)h,6)f)X#H2)c)a,
                                ((X#H2,7)d,8)b)r;")

Plot an explicit network:

    ggevonet(z, layout = "rectangular") + geom_tiplab() + geom_nodelab()

    p <- ggevonet(z, layout = "slanted") + geom_tiplab() + geom_nodelab()
    p + geom_tiplab(size=3, color="purple")

    p + geom_nodepoint(color="#b5e521", alpha=1/4, size=10)

# 5 Summary

This vignette illustrates all the functions in the R package tanggle, and provides some examples on how to plot both explicit and implicit networks. The split network plots should take most of the functions compatible with unrooted trees in ggtree. The layout options for explicit network plots are rectangular or slanted.

# Session info

    sessionInfo()
    #> R version 4.6.0 RC (2026-04-17 r89917)
    #> Platform: x86_64-pc-linux-gnu
    #> Running under: Ubuntu 24.04.4 LTS
    #>
    #> Matrix products: default
    #> BLAS:   /home/biocbuild/bbs-3.24-bioc/R/lib/libRblas.so
    #> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0  LAPACK version 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] phangorn_2.12.1  ape_5.8-1        tanggle_1.19.2   ggtree_4.3.0
    #> [5] ggplot2_4.0.3    BiocStyle_2.41.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] fastmatch_1.1-8         gtable_0.3.6            xfun_0.58
    #>  [4] bslib_0.11.0            htmlwidgets_1.6.4       lattice_0.22-9
    #>  [7] quadprog_1.5-8          vctrs_0.7.3             tools_4.6.0
    #> [10] generics_0.1.4          yulab.utils_0.2.4       parallel_4.6.0
    #> [13] tibble_3.3.1            pkgconfig_2.0.3         Matrix_1.7-5
    #> [16] ggplotify_0.1.3         RColorBrewer_1.1-3      S7_0.2.2
    #> [19] lifecycle_1.0.5         compiler_4.6.0          farver_2.1.2
    #> [22] treeio_1.37.0           tinytex_0.59            codetools_0.2-20
    #> [25] ggfun_0.2.0             fontquiver_0.2.1        fontLiberation_0.1.0
    #> [28] htmltools_0.5.9         sass_0.4.10             yaml_2.3.12
    #> [31] lazyeval_0.2.3          pillar_1.11.1           jquerylib_0.1.4
    #> [34] tidyr_1.3.2             MASS_7.3-65             cachem_1.1.0
    #> [37] magick_2.9.1            nlme_3.1-169            fontBitstreamVera_0.1.1
    #> [40] tidyselect_1.2.1        aplot_0.2.9             digest_0.6.39
    #> [43] dplyr_1.2.1             purrr_1.2.2             bookdown_0.46
    #> [46] labeling_0.4.3          fastmap_1.2.0           grid_4.6.0
    #> [49] cli_3.6.6               magrittr_2.0.5          patchwork_1.3.2
    #> [52] dichromat_2.0-0.1       withr_3.0.2             gdtools_0.5.1
    #> [55] scales_1.4.0            rappdirs_0.3.4          rmarkdown_2.31
    #> [58] igraph_2.3.2            otel_0.2.0              evaluate_1.0.5
    #> [61] knitr_1.51              gridGraphics_0.5-1      rlang_1.2.0
    #> [64] ggiraph_0.9.6           Rcpp_1.1.1-1.1          glue_1.8.1
    #> [67] tidytree_0.4.7          BiocManager_1.30.27     jsonlite_2.0.0
    #> [70] R6_2.6.1                systemfonts_1.3.2       fs_2.1.0

# 6 References

# Appendix