---
title: "How to stretch an nLTT timepoints matrix"
author: "Richel Bilderbeek"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
#output: pdf_document
vignette: >
  %\VignetteIndexEntry{How to stretch an nLTT timepoints matrix}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

An nLTT plot consists out of points that denote a number of (normalized)
lineages in (normalized) time. For nLTT plots with only a few points,
`stretch_nltt_matrix` inserts timepoints.

## Examples

For all examples, the following R code must be run:

```{r}
library(ape)
library(nLTT) # nolint
library(testit)
```

### Example: Easy tree

Create an easy tree:

```{r}
newick <- "((A:1,B:1):1,C:2);"
phylogeny <- ape::read.tree(text = newick)
plot(phylogeny)
ape::add.scale.bar() #nolint
```

From this tree, we can create an nLTT plot:

```{r}
nltt_plot(phylogeny)
```

We can extract the timepoints of the nLTT plot using the
`get_phylogeny_nltt_matrix` function. 

```{r}
nltt <- nLTT::get_phylogeny_nltt_matrix(phylogeny)
print(nltt)
```

The timepoints are plotted in red over the nLTT plot:

```{r}
nltt_plot(phylogeny)
points(nltt, pch = 19, col = "red")
```

The function `stretch_nltt_matrix` inserts timepoints, as shown in this table:

```{r}
nltt <- nLTT::get_phylogeny_nltt_matrix(phylogeny)
stretch_matrix <- nLTT::stretch_nltt_matrix(
  nltt, dt = 0.25, step_type = "upper"
)
print(stretch_matrix)
```

Plotting these as blue points between the red points:

```{r}
nltt_plot(phylogeny)
points(nltt, pch = 19, col = "red")
points(stretch_matrix, pch = 19, col = "blue")
```

A good result is when all blue points fall on the line.

### Example: Tree that has two branching events at the same time

Create an easy tree:

```{r}
newick <- "((A:1,B:1):1,(C:1,D:1):1);"
phylogeny <- ape::read.tree(text = newick)
plot(phylogeny)
ape::add.scale.bar() #nolint
```

From this tree, we can create an nLTT plot:

```{r}
nltt_plot(phylogeny)
```

We can extract the timepoints of the nLTT plot using the
`get_phylogeny_nltt_matrix` function. 

```{r}
nltt <- nLTT::get_phylogeny_nltt_matrix(phylogeny)
print(nltt)
```

The timepoints are plotted
in red over the nLTT plot:

```{r}
nltt_plot(phylogeny)
points(nltt, pch = 19, col = "red")
```

The function `stretch_nltt_matrix` inserts timepoints, as shown in this table:

```{r}
nltt <- nLTT::get_phylogeny_nltt_matrix(phylogeny)
stretch_matrix <- nLTT::stretch_nltt_matrix(
  nltt, dt = 0.25, step_type = "upper"
)
print(stretch_matrix)
```

Plotting these as blue points between the red points:


```{r}
nltt_plot(phylogeny)
points(nltt, pch = 19, col = "red")
points(stretch_matrix, pch = 19, col = "blue")
```

A good result is when all blue points fall on the line.

### Example: Complex tree

Create a complex tree:


```{r}
newick <- paste0("((((XD:1,ZD:1):1,CE:2):1,(FE:2,EE:2):1):4,((AE:1,BE:1):1,",
  "(WD:1,YD:1):1):5);"
)
phylogeny <- ape::read.tree(text = newick)
plot(phylogeny)
ape::add.scale.bar() #nolint
```

From this tree, we can create an nLTT plot:

```{r}
nltt_plot(phylogeny)
```

We can extract the timepoints of the nLTT plot using the
`get_phylogeny_nltt_matrix` function. 

```{r}
nltt <- nLTT::get_phylogeny_nltt_matrix(phylogeny)
print(nltt)
```

The timepoints are plotted
in red over the nLTT plot:

```{r}
nltt_plot(phylogeny)
points(nltt, pch = 19, col = "red")
```

The function `stretch_nltt_matrix` inserts blue points between these
red points:

```{r}
nltt <- nLTT::get_phylogeny_nltt_matrix(phylogeny)
nltt_plot(phylogeny)
stretch_matrix <- nLTT::stretch_nltt_matrix(
  nltt, dt = 0.05, step_type = "upper"
)
points(nltt, pch = 19, col = "red")
points(stretch_matrix, pch = 19, col = "blue")
```

A good result is when all blue points fall on the line.