# Extract categorical trait data mapped on a phylogeny at a given time in the past Extracts the most likely states found along branches at a specific time in the past (i.e. the `focal_time`). Optionally, the function can update the mapped phylogeny (`densityMaps`) such as branches overlapping the `focal_time` are shorten to the `focal_time`, and the trait mapping for the cut off branches are removed by updating the `$tree$maps` and `$tree$mapped.edge` elements. ```r extract_most_likely_states_from_densityMaps_for_focal_time( densityMaps, ace = NULL, tip_data = NULL, focal_time, update_densityMaps = FALSE, keep_tip_labels = TRUE ) ``` ## Arguments - `densityMaps`: List of objects of class `"densityMap"`, typically generated with `prepare_trait_data()`, that contains a phylogenetic tree and associated posterior probability of being in a given state along branches. Each object (i.e., `densityMap`) corresponds to a state. The phylogenetic tree must be rooted and fully resolved/dichotomous, but it does not need to be ultrametric (it can includes fossils). - `ace`: (Optional) Numerical matrix that record the posterior probabilities of ancestral states at internal nodes, obtained with `prepare_trait_data()` as output in the `$ace` slot. Rows are internal nodes_ID. Columns are states. Values are posterior probabilities of each state per node. Needed to provide accurate estimates of ancestral states. - `tip_data`: (Optional) Named character string vector of tip states. 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_densityMaps`: Logical. Specify whether the mapped phylogeny (`densityMaps`) 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 densityMaps. Default is `TRUE`. Used only if `update_map = TRUE`. ## Returns By default, the function returns a list with three elements. * `$trait_data` A named character string vector with ML states 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 "categorical". Used in downstream analyses to select appropriate statistical processing. If `update_densityMaps = TRUE`, the output is a list with four elements: `$trait_data`, `$focal_time`, `$trait_data_type`, and `$densityMaps`. * `$densityMaps` A list of objects of class `"densityMap"` that contains the updated `densityMap` of each state, with branches and mapping that are younger than the `focal_time` cut off. The function also adds multiple useful sub-elements to the `$densityMaps$tree` elements. * `$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 (`densityMaps`) 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` ----- Most likely states are extracted from the posterior probabilities displayed in the `densityMaps`. The state with the highest probability is assigned to each tip and cut branches at `focal_time`. 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 `densityMaps` ----- To obtain updated `densityMaps` alongside the trait data, set `update_densityMaps = 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 categorical trait mapping in `densityMap` (`$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) ----- # ## Load categorical trait data mapped on a phylogeny data(eel_cat_3lvl_data, package = "deepSTRAPP") # Explore data str(eel_cat_3lvl_data, 1) eel_cat_3lvl_data$densityMaps # Three density maps: one per state # Set focal time to 10 Mya focal_time <- 10 # (May take several minutes to run) ## Extract trait data and update densityMaps for the given focal_time # Extract from the densityMaps eel_cat_3lvl_data_10My <- extract_most_likely_states_from_densityMaps_for_focal_time( densityMaps = eel_cat_3lvl_data$densityMaps, # ace = eel_cat_3lvl_data$ace, focal_time = focal_time, update_densityMaps = TRUE) ## Print trait data str(eel_cat_3lvl_data_10My, 1) eel_cat_3lvl_data_10My$trait_data ## Plot density maps as overlay of all state posterior probabilities # Plot initial density maps with ACE pies plot_densityMaps_overlay(densityMaps = eel_cat_3lvl_data$densityMaps, fsize = 0.5) abline(v = max(phytools::nodeHeights(eel_cat_3lvl_data$densityMaps[[1]]$tree)[,2]) - focal_time, col = "red", lty = 2, lwd = 2) # Plot updated densityMaps with ACE pies plot_densityMaps_overlay(eel_cat_3lvl_data_10My$densityMaps, fsize = 0.7) # ----- 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") # Obtain mammal tree mammals_tree <- mammals$mammal.phy # Convert mass data into categories mammals_mass <- setNames(object = mammals$mammal.mass$mean, nm = row.names(mammals$mammal.mass))[mammals_tree$tip.label] mammals_data <- mammals_mass mammals_data[seq_along(mammals_data)] <- "small" mammals_data[mammals_mass > 5] <- "medium" mammals_data[mammals_mass > 10] <- "large" table(mammals_data) # (May take several minutes to run) ## Produce densityMaps using stochastic character mapping based on an equal-rates (ER) Mk model mammals_cat_data <- prepare_trait_data(tip_data = mammals_data, phylo = mammals_tree, trait_data_type = "categorical", evolutionary_models = "ER", nb_simulations = 100, plot_map = FALSE) # Set focal time focal_time <- 80 ## Extract trait data and update densityMaps for the given focal_time # Extract from the densityMaps mammals_cat_data_80My <- extract_most_likely_states_from_densityMaps_for_focal_time( densityMaps = mammals_cat_data$densityMaps, focal_time = focal_time, update_densityMaps = TRUE) ## Print trait data str(mammals_cat_data_80My, 1) mammals_cat_data_80My$trait_data ## Plot density maps as overlay of all state posterior probabilities # Plot initial density maps with ACE pies plot_densityMaps_overlay(densityMaps = mammals_cat_data$densityMaps, fsize = 0.7) abline(v = max(phytools::nodeHeights(mammals_cat_data$densityMaps[[1]]$tree)[,2]) - focal_time, col = "red", lty = 2, lwd = 2) # Plot updated densityMaps with ACE pies plot_densityMaps_overlay(mammals_cat_data_80My$densityMaps, fsize = 0.8) ``` ## See Also `cut_phylo_for_focal_time()` `cut_densityMaps_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_trait_values_from_contMap_for_focal_time()` `extract_most_likely_ranges_from_densityMaps_for_focal_time()` ## Author(s) Maël Doré

extract_most_likely_states_from_densityMaps_for_focal_time function