Cut the phylogenies and continuous trait mappings of a list of contMaps for a given focal time in the past

Cuts off all the branches of the phylogeny which are younger than a specific time in the past (i.e. the focal_time). Branches overlapping the focal_time are shortened to the focal_time. Likewise, remove continuous trait mapping for the cut off branches by updating the $tree$maps and $tree$mapped.edge elements.

Usage

cut_contMaps_for_focal_time(contMaps, focal_time, keep_tip_labels = TRUE)

Arguments

contMaps: List of objects of class "contMap", typically generated with phytools::contMap(), that contains a phylogenetic tree and associated continuous trait mapping. The phylogenetic tree must be rooted and fully resolved/dichotomous, but it does not need to be ultrametric (it can include fossils).
focal_time: Numeric. The time, in terms of time distance from the present, for which the tree and mapping must be cut. It must be smaller than the root age of the phylogeny.
keep_tip_labels: Logical. Specify whether terminal branches with a single descendant tip must retain their initial tip.label. Default is TRUE.

Value

The function returns an updated list of objects as cut contMaps of class "contMap".

Each contMap object contains three elements:

$tree. A list of classes "simmap" and "phylo". This function updates and adds multiple useful sub-elements to the $tree element.
- $maps An updated list of named numeric vectors. Provides the mapping of trait values along each remaining edge.
- $mapped.edge An updated matrix. Provides the evolutionary time spent across trait values (columns) along the remaining edges (rows).
- $root_age Integer. Stores the age of the root of the tree.
- $nodes_ID_df Data.frame with two columns. Provides the conversion from the new_node_ID to the initial_node_ID. Each row is a node.
- $initial_nodes_ID Character vector. Provides the initial ID of internal nodes. Used to plot internal node IDs as labels with ape::nodelabels().
- $edges_ID_df Data.frame with two columns. Provides the conversion from the new_edge_ID to the initial_edge_ID. Each row is an edge/branch.
- $initial_edges_ID Character vector. Provides the initial ID of edges/branches. Used to plot edge/branch IDs as labels with ape::edgelabels().
$cols A named character vector mapping trait values with colors to display on the plot.
$lims A numeric vector of length 2 storing the initial min and max values of the trait (trait values are scaled between 0 and 1000 in $tree$maps)

Details

The phylogenetic trees are cut for a specific time in the past (i.e. the focal_time).

When a branch with a single descendant tip is cut and keep_tip_labels = TRUE, the leaf left is labeled with the tip.label of the unique descendant tip.

When a branch with a single descendant tip is cut and keep_tip_labels = FALSE, the leaf left is labeled with the node ID of the unique descendant tip.

In all cases, when a branch with multiple descendant tips (i.e., a clade) is cut, the leaf left is labeled with the node ID of the MRCA of the cut-off clade.

The continuous trait mappings are updated accordingly by removing mapping associated with the cut off branches.

Author

Maël Doré

Examples

if (deepSTRAPP::is_dev_version())
{
 ## The R package 'contsimmap' is needed for this example to work.
 # Please install it manually from: https://github.com/bstaggmartin/contsimmap.

 # ----- Prepare data ----- #

 # Load phylogeny and tip data
 # Load eel phylogeny and tip data from the R package phytools
 # Source: Collar et al., 2014; DOI: 10.1038/ncomms6505
 data("eel.tree", package = "phytools")
 data("eel.data", package = "phytools")

 # Extract body size
 eel_data <- stats::setNames(eel.data$Max_TL_cm,
                             rownames(eel.data))

  # (May take several seconds to run)
 ## Map multiple trait evolution histories on the phylogeny using continuous stochastic mapping
 eel_mapped_trait_data <- prepare_trait_data(
   tip_data = eel_data,
   trait_data_type = "continuous",
   phylo = eel.tree,
   evolutionary_models = "BM",
   run_stochastic_maps = TRUE,
   nb_simulations = 10,
   plot_map = FALSE,
   verbose = TRUE)

 # Extract list of stochastic maps
 eel_contMaps <- eel_mapped_trait_data$contMaps

 # ----- Example 1: keep_tip_labels = TRUE ----- #

 # Cut contMaps to 20 Mya while keeping tip.label
 # on terminal branches with a unique descending tip.
 updated_contMaps <- cut_contMaps_for_focal_time(contMaps = eel_contMaps,
                                                 focal_time = 20,
                                                 keep_tip_labels = TRUE)

 # Plot node labels on stochastic map n°1 with cut-off
 plot_contMap(eel_contMaps[[1]], lwd = 2, fsize = c(0.5, 1))
 ape::nodelabels(cex = 0.5)
 abline(v = max(phytools::nodeHeights(eel_contMaps[[1]]$tree)[,2]) - 20,
        col = "red", lty = 2, lwd = 2)

 # Plot initial node labels on cut stochastic map n°1
 plot_contMap(updated_contMaps[[1]], fsize = c(0.8, 1))
 ape::nodelabels(cex = 0.8, text = updated_contMaps[[1]]$tree$initial_nodes_ID)

 # ----- Example 2: keep_tip_labels = FALSE ----- #

 # Cut contMap to 20 Mya while NOT keeping tip.label.
 updated_contMaps <- cut_contMaps_for_focal_time(contMaps = eel_contMaps,
                                                 focal_time = 20,
                                                 keep_tip_labels = FALSE)

 # Plot node labels on stochastic map n°1 with cut-off
 plot_contMap(eel_contMaps[[1]], fsize = c(0.5, 1))
 ape::nodelabels(cex = 0.5)
 abline(v = max(phytools::nodeHeights(eel_contMaps[[1]]$tree)[,2]) - 20,
        col = "red", lty = 2, lwd = 2)

 # Plot initial node labels on cut stochastic map
 plot_contMap(updated_contMaps[[1]], fsize = c(0.8, 1))
 ape::nodelabels(cex = 0.8, text = updated_contMaps[[1]]$tree$initial_nodes_ID)
 
}