# Extract continuous trait data mapped on a phylogeny at a given time in the past Extracts the most likely trait values found along branches at a specific time in the past (i.e. the `focal_time`). Optionally, the function can update the mapped phylogeny (`contMap`) such as branches overlapping the `focal_time` are shorten to the `focal_time`, and the continuous trait mapping for the cut off branches are removed by updating the `$tree$maps` and `$tree$mapped.edge` elements. ```r extract_most_likely_trait_values_from_contMap_for_focal_time( contMap, ace = NULL, tip_data = NULL, focal_time, update_contMap = FALSE, keep_tip_labels = TRUE ) ``` ## Arguments - `contMap`: Object of class `"contMap"`, typically generated with `prepare_trait_data()` or `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 includes fossils). - `ace`: Named numeric vector (Optional). Ancestral Character Estimates (ACE) of the internal nodes, typically generated with `phytools::fastAnc()`, `phytools::anc.ML()`, or `ape::ace()`. Names are nodes_ID of the internal nodes. Values are ACE of the trait. Needed to provide accurate estimates of trait values. - `tip_data`: Named numeric vector (Optional). Tip values of the trait. Names are nodes_ID of the internal nodes. Needed to provide accurate tip values. - `focal_time`: Integer. The time, in terms of time distance from the present, at which the tree and mapping must be cut. It must be smaller than the root age of the phylogeny. - `update_contMap`: Logical. Specify whether the mapped phylogeny (`contMap`) provided as input should be updated for visualization and returned among the outputs. Default is `FALSE`. The update consists in cutting off branches and mapping that are younger than the `focal_time`. - `keep_tip_labels`: Logical. Specify whether terminal branches with a single descendant tip must retained their initial `tip.label` on the updated contMap. Default is `TRUE`. Used only if `update_contMap = TRUE`. ## Returns By default, the function returns a list with three elements. * `$trait_data` A named numerical vector with ML trait values found along branches overlapping the `focal_time`. Names are the tip.label/tipward node ID. * `$focal_time` Integer. The time, in terms of time distance from the present, at which the trait data were extracted. * `$trait_data_type` Character string. Define the type of trait data as "continuous". Used in downstream analyses to select appropriate statistical processing. If `update_contMap = TRUE`, the output is a list with four elements: `$trait_data`, `$focal_time`, `$trait_data_type`, and `$contMap`. * `$contMap` An object of class that contains the updated `contMap` with branches and mapping that are younger than the `focal_time` cut off. The function also adds multiple useful sub-elements to the `$contMap$tree` element. * `$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` Vector of character strings. 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` Vector of character strings. Provides the initial ID of edges/branches. Used to plot edge/branch IDs as labels with `ape::edgelabels()`. ## Details The mapped phylogeny (`contMap`) is cut at a specific time in the past (i.e. the `focal_time`) and the current trait values of the overlapping edges/branches are extracted. ----- Extract `trait_data` ----- If providing only the `contMap` trait values at tips and internal nodes will be extracted from the mapping of the `contMap` leading to a slight dependency with the actual tip data and estimated ancestral character values. True ML estimates will be used if `tip_data` and/or `ace` are provided as optional inputs. In practice the discrepancy is negligible. ----- Update the `contMap` ----- To obtain an updated `contMap` alongside the trait data, set `update_contMap = TRUE`. The update consists in cutting off branches and mapping that are younger than 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 mapping `contMap` (`$tree$maps` and `$tree$mapped.edge`) is updated accordingly by removing mapping associated with the cut off branches. ## Examples ```r # ----- Example 1: Only extent taxa (Ultrametric tree) ----- # ## Prepare data # Load eel data from the R package phytools # Source: Collar et al., 2014; DOI: 10.1038/ncomms6505 library(phytools) data(eel.tree) data(eel.data) # Extract body size eel_data <- setNames(eel.data$Max_TL_cm, rownames(eel.data)) # Get Ancestral Character Estimates based on a Brownian Motion model # To obtain values at internal nodes eel_ACE <- phytools::fastAnc(tree = eel.tree, x = eel_data) # Run a Stochastic Mapping based on a Brownian Motion model # to interpolate values along branches and obtain a "contMap" object eel_contMap <- phytools::contMap(eel.tree, x = eel_data, res = 100, # Number of time steps plot = FALSE) # Set focal time to 50 Mya focal_time <- 50 # (May take several minutes to run) ## Extract trait data and update contMap for the given focal_time # Extract from the contMap (values are not exact ML estimates) eel_test <- extract_most_likely_trait_values_from_contMap_for_focal_time( contMap = eel_contMap, focal_time = focal_time, update_contMap = TRUE) # Extract from tip data and ML estimates of ancestral characters (values are true ML estimates) eel_test <- extract_most_likely_trait_values_from_contMap_for_focal_time( contMap = eel_contMap, ace = eel_ACE, tip_data = eel_data, focal_time = focal_time, update_contMap = TRUE) ## Visualize outputs # Print trait data eel_test$trait_data # Plot node labels on initial stochastic map with cut-off plot(eel_contMap, fsize = c(0.5, 1)) ape::nodelabels() abline(v = max(phytools::nodeHeights(eel_contMap$tree)[,2]) - focal_time, col = "red", lty = 2, lwd = 2) # Plot updated contMap with initial node labels plot(eel_test$contMap) ape::nodelabels(text = eel_test$contMap$tree$initial_nodes_ID) # ----- Example 2: Include fossils (Non-ultrametric tree) ----- # ## Test with non-ultrametric trees like mammals in motmot ## Prepare data # Load mammals phylogeny and data from the R package motmot included within deepSTRAPP # Data source: Slater, 2013; DOI: 10.1111/2041-210X.12084 data("mammals", package = "deepSTRAPP") mammals_tree <- mammals$mammal.phy mammals_data <- setNames(object = mammals$mammal.mass$mean, nm = row.names(mammals$mammal.mass))[mammals_tree$tip.label] # Get Ancestral Character Estimates based on a Brownian Motion model # To obtain values at internal nodes mammals_ACE <- phytools::fastAnc(tree = mammals_tree, x = mammals_data) # Run a Stochastic Mapping based on a Brownian Motion model # to interpolate values along branches and obtain a "contMap" object mammals_contMap <- phytools::contMap(mammals_tree, x = mammals_data, res = 100, # Number of time steps plot = FALSE) # Set focal time to 80 Mya focal_time <- 80 # (May take several minutes to run) ## Extract trait data and update contMap for the given focal_time # Extract from the contMap (values are not exact ML estimates) mammals_test <- extract_most_likely_trait_values_from_contMap_for_focal_time( contMap = mammals_contMap, focal_time = focal_time, update_contMap = TRUE) # Extract from tip data and ML estimates of ancestral characters (values are true ML) mammals_test <- extract_most_likely_trait_values_from_contMap_for_focal_time( contMap = mammals_contMap, ace = mammals_ACE, tip_data = mammals_data, focal_time = focal_time, update_contMap = TRUE) ## Visualize outputs # Print trait data mammals_test$trait_data # Plot node labels on initial stochastic map with cut-off phytools::plot.contMap(mammals_contMap, fsize = c(0.5, 1)) ape::nodelabels() abline(v = max(phytools::nodeHeights(mammals_contMap$tree)[,2]) - focal_time, col = "red", lty = 2, lwd = 2) # Plot updated contMap with initial node labels phytools::plot.contMap(mammals_test$contMap, fsize = c(0.8, 1)) ape::nodelabels(text = mammals_test$contMap$tree$initial_nodes_ID) ``` ## See Also `cut_phylo_for_focal_time()` `cut_contMap_for_focal_time()` Associated main function: `extract_most_likely_trait_values_for_focal_time()` Sub-functions for other types of trait data: `extract_most_likely_states_from_densityMaps_for_focal_time()` `extract_most_likely_ranges_from_densityMaps_for_focal_time()` ## Author(s) Maël Doré

extract_most_likely_trait_values_from_contMap_for_focal_time function