How to stretch an nLTT timepoints matrix

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Richel Bilderbeek

2025-05-06

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:

library(ape)
library(nLTT) # nolint
library(testit)

Example: Easy tree

Create an easy tree:

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:

nltt_plot(phylogeny)

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

nltt <- nLTT::get_phylogeny_nltt_matrix(phylogeny)
print(nltt)

##      time         N
## [1,]  0.0 0.3333333
## [2,]  0.5 0.6666667
## [3,]  1.0 1.0000000

The timepoints are plotted in red over the nLTT plot:

nltt_plot(phylogeny)
points(nltt, pch = 19, col = "red")

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

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

##      [,1]      [,2]
## [1,] 0.00 0.6666667
## [2,] 0.25 0.6666667
## [3,] 0.50 1.0000000
## [4,] 0.75 1.0000000
## [5,] 1.00 1.0000000

Plotting these as blue points between the red points:

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:

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:

nltt_plot(phylogeny)

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

nltt <- nLTT::get_phylogeny_nltt_matrix(phylogeny)
print(nltt)

##      time    N
## [1,]  0.0 0.25
## [2,]  0.5 0.50
## [3,]  0.5 0.75
## [4,]  1.0 1.00

The timepoints are plotted in red over the nLTT plot:

nltt_plot(phylogeny)
points(nltt, pch = 19, col = "red")

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

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

##      [,1] [,2]
## [1,] 0.00  0.5
## [2,] 0.25  0.5
## [3,] 0.50  1.0
## [4,] 0.75  1.0
## [5,] 1.00  1.0

Plotting these as blue points between the red points:

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:

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:

nltt_plot(phylogeny)

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

nltt <- nLTT::get_phylogeny_nltt_matrix(phylogeny)
print(nltt)

##            time         N
##  [1,] 0.0000000 0.1111111
##  [2,] 0.5714286 0.2222222
##  [3,] 0.7142857 0.3333333
##  [4,] 0.7142857 0.4444444
##  [5,] 0.7142857 0.5555556
##  [6,] 0.8571429 0.6666667
##  [7,] 0.8571429 0.7777778
##  [8,] 0.8571429 0.8888889
##  [9,] 1.0000000 1.0000000

The timepoints are plotted in red over the nLTT plot:

nltt_plot(phylogeny)
points(nltt, pch = 19, col = "red")

The function stretch_nltt_matrix inserts blue points between these red points:

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.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.