README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# sGMYC: GMYC analysis with subsampling

<!-- badges: start -->
<!-- badges: end -->

sGMYC runs a single-threshold GMYC analysis (Pons et al. 2006) using the splits package (Fujisawa & Barraclough 2013) with 
subsamples of sequences obtained from within the species 
delimited using all sequences. It also plots a heatmap of 
conspecificity probabilities among samples based on functions 
of the bGMYC package (Reid & Carstens 2012). When more than one tree are provided, sGMYC can implement the analysis with multiple cores using the parallel and doParallel packages.

## Installation

You can install the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("arleyc/sGMYC")
```
## Example: full analysis with bGMYC vs. subsampling with sGMYC

1) Load an example dataset (hypotree) included with the sGMYC package:

```{r example1}
library(sGMYC)

data("hypotree")

ape::print.phylo(hypotree)
```

2) Run a single-threshold GMYC analysis with the splits package:

```{r example2}
library(splits)

gmyc(hypotree, quiet=TRUE)->fullgmyc

summary(fullgmyc)

plot(fullgmyc)
```

3) GMYC estimates 12 (9-15) species. Next, use bGMYC to implement a full Bayesian GMYC analysis:

```{r example3}
library(bGMYC)

fullbgmyc<-bgmyc.singlephy(hypotree, mcmc=10000, burnin=1000, thinning=100)

#Calculate matrix of conspecificity probabilities
fullbgmyc.probmat<-bGMYC::spec.probmat(fullbgmyc)

# Calculate a point estimate of the number of species
length(bgmyc.point(fullbgmyc.probmat,0.05))
```

4) Based on cutoff value of PP=0.05, bGMYC estimates 8 species; use a heatmap plot to display the probabilities of conspecificity:

``` {r example4}
#Plot heatmap of conspecificity probabilities
plot.bgmycprobmat(fullbgmyc.probmat,hypotree)
```

5) In sGMYC, subsample two sequences from each of the species originally estimated with the full GMYC:

```{r example5}
subgmyc<-sGMYC(hypotree,subsamp=2,nreps=100)
```

6) sGMYC estimates 2 species across all 100 subsampling replicates. We can also plot a heatmap that summarizes the variation in species limits based on subsampling:

```{r example6}
#Calculate matrix of conspecificity probabilities

subgmyc.probmat<-sGMYC::spec.probmat(subgmyc)

#Plot heatmap of conspecificity probabilities

plot.bgmycprobmat(subgmyc.probmat,hypotree)
```

```{r example7}
#Species delimitation with subsampling using multiple trees and computer cores

#Plotting heatmap of conspecificity probabilities
```

## References

Fujisawa T & Barraclough TG. 2013. Delimiting species using single-locus data and the Generalized Mixed Yule Coalescent approach: A revised method and evaluation on simulated data sets. Systematic Biology 62:707–724, doi: 10.1093/sysbio/syt033

Pons J, Barraclough TG, Gomez-Zurita J, Cardoso A, Duran DP, Hazell S, Kamoun S, Sumlin WD & Vogler AP. 2006. Sequence-based species delimitation for the DNA taxonomy of undescribed insects. Systematic Biology 55:595-609, doi: 10.1080/10635150600852011.

Reid NM & Carstens BC. 2012. Phylogenetic estimation error can decrease the accuracy of species delimitation: a Bayesian implementation of the general mixed Yule-coalescent model. BMC Evolutionary Biology 12:196, doi: 10.1186/1471-2148-12-196.

## Citation

de Magalhães RF, Santos MTT & Camargo A. 2024. Subsampling GMYC (sGMYC): a new algorithmic implementation of the generalized mixed Yule-coalescent model. I Brazilian Congress of Evolutionary Biology, Curitiba, Brazil.