---
title: "Using TBRDist"
author: "Martin R. Smith"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using TBRDist}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

'TBRDist' is an R package to compare unrooted phylogenetic trees using the 
SPR, TBR and Replug distances.

## Loading trees

This document assumes familiarity with the process of [loading trees into R](https://ms609.github.io/TreeTools/articles/load-trees.html).

We'll work with some simple trees generated using the 
'[TreeTools](https://ms609.github.io/TreeTools/)' package.

```{r, align='center', fig.width=7}
library('TreeTools', quietly = TRUE, warn.conflicts = FALSE)

tree1 <- BalancedTree(10)
tree2 <- PectinateTree(10)

origPar <- par(mfrow = 1:2, mar = rep(0.2, 4)) # Set up plotting area
plot(tree1)
plot(tree2)
```

## Calculating distances

After installing TBRDist (`install.packages('TBRDist')`), load the package into
R with

```{r}
library('TBRDist')
```

To generate an approximate SPR distance between two unrooted trees, use:

```{r}
USPRDist(tree1, tree2)
```

For Replug distances, it's:

```{R}
ReplugDist(tree1, tree2)
```

For TBR distances, use:

```{r}
TBRDist(tree1, tree2, exact = TRUE)
```

When calculating an exact TBR distance, we receive information on the
maximum agreement forest for free (i.e. with no extra processing cost):

```{r}
TBRDist(tree1, tree2, exact = TRUE, maf = TRUE)
```

Once trees have more than about a dozen tips, it becomes slow to calculate the 
exact distance.  In the interests of speed, we may wish to approximate the value
of the TBR distance:

```{r}
TBRDist(tree1, tree2, exact = FALSE)
```

## Comparing multiple trees

To avoid multiple calls, each function can also be used to compare lists of 
trees (or `multiPhylo` objects) against a single tree:

```{r}
TBRDist(tree1, list(tree1, tree2), exact = TRUE, maf = TRUE)
```

Or against each corresponding entry in a second list:

```{r}
USPRDist(list(tree1, tree2, tree2), list(tree2, tree1, tree2))
```

## Citation

If you use 'TBRDist' in your research, please cite:

* Chris Whidden and Frederick A. Matsen IV (2017). Calculating the Unrooted Subtree-Prune-and-Regraft Distance. eprint arXiv:[1511.07529](https://arxiv.org/abs/1511.07529).

Optionally, a citation to the 'TBRDist' R package would be welcome:

* Smith (2019). TBRDist: Calculate SPR and TBR distance between unrooted phylogenetic trees. [doi:10.5281/zenodo.3548333](https://dx.doi.org/10.5281/zenodo.3548333)

```{r echo=FALSE}
par(origPar)
```