extract_most_likely_trait_values_from_contMap_for_focal_time: Extract continuous trait data mapped on a phylogeny at a...
In deepSTRAPP: Test for Differences in Diversification Rates over Time

extract_most_likely_trait_values_from_contMap_for_focal_time

R Documentation

Extract continuous trait data mapped on a phylogeny at a given time in the past

Description

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.

Usage

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`.

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.

Value

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().

Author(s)

Maël Doré

Examples

# ----- 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)

deepSTRAPP documentation built on Jan. 20, 2026, 1:06 a.m.