Helper Functions for Species Delimitation Analysis

Helpers functions to process, analyse, and visualize the output of single locus species delimitation methods. For full functionality, please install suggested software at < https://legallab.github.io/delimtools/articles/install.html>.

delimtools

IMPORTANT

This software is under active development, and as such cannot be assumed to be free of bugs or poor functionality. Always inspect results carefully. If you find a problem, please report it with as much detail as possible in Issues. Unfortunately in its current form, some of the functions (abgd_tbl(), asap_tbl() and mptp_tbl()) will not work natively on Windows operating systems, only on Unix (MacOS, Linux). This is because third party binaries (executable programs) are required. We have implemented a Windows solution by importing results from the webservers that are commonly used to run these analyses, e.g. ABGD, ASAP, and mPTP. There are also difficulties with installing R required package dependancies to run gmyc_tbl() and bgmyc_tbl() because these are no longer under development and available on CRAN, and must be installed from archived sources. Please refer to https://legallab.github.io/delimtools/articles/install.html for instructions on how to install. A tutorial vignette running through all major package functionality is found at https://legallab.github.io/delimtools/articles/delimtools.html.

Overview

The official GitHub repository for the R package delimtools (Bittencourt et al., in prep.).

delimtools provides helper functions for the analysis of single-locus species delimitation methods such as GMYC (Monaghan et al., 2009), bGMYC (Reid & Carstens, 2012), mPTP (Kapli et al., 2017) and ASAP (Puillandre et al., 2020). These software run multiple different platforms (e.g. R, Unix, webservers), and also do not output their results in a consistent format to allow easy comparison. To address these shortcomings we have developed a suite of functions to standardise and simplify generating single-locus species delimitations.

Dependencies

Delimtools mainly depends on the tidyverse and ggtree packages. To install these, run the command lines below:

Install tidyverse:

install.packages("tidyverse")

Install ggtree

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

BiocManager::install("ggtree")

Installation

To install delimtools you may execute the following commands. We recommend the usage of the latest CRAN release always.

Latest stable version from CRAN

install.packages("delimtools")

Development version from GitHub:

devtools::install_github("LegalLab/delimtools")

Or a specific version via renv:

renv::install("LegalLab/[email protected]")

Examples

Here, we will demonstrate plotting a single-locus species delimitation analysis of a Geophagus eartheater cichlid dataset (Ximenes et al., 2021) using a variety of methods. A tutorial vignette running through all major package functionality is found at https://legallab.github.io/delimtools/articles/delimtools.html.

Redhead Eartheater Geophagus pyrocephalus

library(delimtools)
library(dplyr)

# make tip label table
tip.tab <- geophagus_info |> 
  filter(gbAccession %in% geophagus_beast@phylo$tip.label) |>
  mutate(labs= glue::glue("{gbAccession} | {scientificName}")) |> 
  select(gbAccession, labs, scientificName)

# get cols
cols <- delim_brewer(delim= geophagus_delims, package="randomcoloR", seed=42)

# plot
delim_autoplot(delim = geophagus_delims, 
               tr = geophagus_beast, 
               consensus = TRUE,
               n_match = 4,
               delim_order = c("asap","abgd","locmin","gmyc","bgmyc","ptp", "mptp","morph"),
               tbl_labs = tip.tab, 
               col_vec = cols,
               hexpand = 0.7,
               widths = c(0.5, 0.5))
#> Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
#> ℹ Please use `linewidth` instead.
#> ℹ The deprecated feature was likely used in the ggtree package.
#>   Please report the issue at <https://github.com/YuLab-SMU/ggtree/issues>.
#> This warning is displayed once per session.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.