R: Calculate mean & standard deviation of a numeric trait on a...

get_trait_stats_over_time {castor} | R Documentation

## Calculate mean & standard deviation of a numeric trait on a dated tree over time.

### Description

Given a rooted and dated phylogenetic tree, and a scalar numeric trait with known value on each node and tip of the tree, calculate the mean and the variance of the trait's states across the tree at discrete time points. For example, if the trait represents "body size", then this function calculates the mean body size of extant clades over time.

### Usage

    get_trait_stats_over_time(tree, states, Ntimes=NULL, times=NULL, check_input=TRUE)

### Arguments

`tree` | A rooted tree of class "phylo", where edge lengths represent time intervals (or similar).
`states` | Numeric vector, specifying the trait's state at each tip and each node of the tree (in the order in which tips & nodes are indexed). May include `NA` or `NaN` if values are missing for some tips/nodes.
`Ntimes` | Integer, number of equidistant time points for which to calculade clade counts. Can also be `NULL`, in which case `times` must be provided.
`times` | Integer vector, listing time points (in ascending order) for which to calculate clade counts. Can also be `NULL`, in which case `Ntimes` must be provided.
`check_input` | Logical, specifying whether to perform some basic checks on the validity of the input data. If you are certain that your input data are valid, you can set this to `FALSE` to reduce computation.

### Details

If `tree$edge.length` is missing, then every edge in the tree is assumed to be of length 1. The tree may include multi-furcations as well as mono-furcations (i.e. nodes with only one child). The tree need not be ultrametric (e.g. may include extinct tips), although in general this function only makes sense if edge lengths correspond to time (or similar).

Either `Ntimes` or `times` must be non-`NULL`, but not both. `states` need not include names; if it does, then these are checked to be in the same order as in the tree (if `check_input==TRUE`).

### Value

A list with the following elements:

`Ntimes` | Integer, indicating the number of returned time points. Equal to the provided `Ntimes` if applicable.
`times` | Numeric vector of size Ntimes, listing the considered time points in increasing order. If `times` was provided as an argument to the function, then this will be the same as provided.
`clade_counts` | Integer vector of size Ntimes, listing the number of tips or nodes considered at each time point.
`means` | Numeric vector of size Ntimes, listing the arithmetic mean of trait states at each time point.
`stds` | Numeric vector of size Ntimes, listing the population standard deviation of trait states at each time point.

### Author(s)

Stilianos Louca

### Examples

    # generate a random tree
    tree = generate_random_tree(list(birth_rate_intercept=1), max_tips=1000)$tree

    # simulate a numeric trait under Brownian-motion
    trait = simulate_bm_model(tree, diffusivity=1)
    states = c(trait$tip_states,trait$node_states)

    # calculate trait stats over time
    results = get_trait_stats_over_time(tree, states, Ntimes=100)

    # plot trait stats over time (mean +/- std)
    M = results$means
    S = results$stds
    matplot(x=results$times,
            y=matrix(c(M-S,M+S),ncol=2,byrow=FALSE),
            main = "Simulated BM trait over time",
            lty = 1, col="black",
            type="l", xlab="time", ylab="mean +/- std")

[Package castor version 1.3.3 Index]