OUwie.dredge: Generalized Detection of shifts in OU process

In OUwie: Analysis of Evolutionary Rates in an OU Framework

Generalized Detection of shifts in OU process

Description

Allows the hypothesis free detection of shifts in the OU process. The number and location of shifts is estimated using a user-specified information criterion.

Usage

OUwie.dredge(phy, data, criterion=c("AIC", "AICc", "BIC", "mBIC"), shift.max=3, 
sigma.sq.max.k=3, alpha.max.k=3, root.age=NULL, scaleHeight=FALSE, root.station=FALSE, 
shift.point=0.5, mserr="none", algorithm=c("invert", "three.point"), 
opts = list("algorithm"="NLOPT_LN_SBPLX", "maxeval"="1000", 
"ftol_rel"=.Machine$double.eps^0.5))

Arguments

phy	a phylogenetic tree, in ape “phylo” format and with internal nodes labeled denoting the ancestral selective regimes
data	a dataframe containing two columns, taxon names in the first column, and species trait information in the second column.
criterion	information criterion to use for shift detection.
shift.max	maximum allowed number of shifts.
sigma.sq.max.k	maximum allowed number of sigma.sq parameters.
alpha.max.k	maximum allowed number of alpha parameters.
root.age	indicates the age of the tree. This is to be used in cases where the "tips" are not contemporary, such as in cases for fossil trees. Default is NULL meaning latest tip is modern day.
scaleHeight	a logical indicating whether the total tree height should be scaled to 1. The default is FALSE.
root.station	a logical indicating whether the starting state, theta_0, should be estimated.
shift.point	the point along a branch where a regime change is assumed to have occurred (if SIMMAP=FALSE. The default is set to 0.5, or halfway along a branch.
algorithm	designates whether the standard matrix inversion ('invert') or the faster 'three-point' algorithm of Ho and Ane (2013) should be used.
mserr	designates whether a fourth column in the data matrix contains measurement error for each species value ("known"). The measurement error is assumed to be the standard error of the species mean. The default is "none".
opts	a list of options to pass to nloptr for the optimization: useful to adjust for faster, coarser searches

Details

This is an expanded version of the shift point model of Ho and Ane (2014). This is currently being tested, but as of now we strongly recommend using the mBIC criterion when searching for shifts.

Value

OUwie.dredge returns an object of class OUwie.dredge. This is a list with elements:

$loglik	the maximum log-likelihood.
$criterion	the information criterion to use for shift detection.
$criterion.score	the information criterion score used for shift detection.
$shift.model	The shift model estimated from the data.
$solution	a matrix containing the maximum likelihood estimates of alpha and sigma^2.
$mserr.est	indicates value of the measurement error if it was estimated from the data.
$theta	a matrix containing the maximum likelihood estimates of theta.
$tot.states	A vector of names for the different regimes
$index.mat	The indices of the parameters being estimated are returned. The numbers correspond to the row in the eigvect and can useful for identifying the parameters that are causing the objective function to be at a saddlepoint (see Details)
$simmap.tree	A logical indicating whether the input phylogeny is a SIMMAP formatted tree.
$root.age	The user-supplied age at the root of the tree.
$scaleHeight	Indicates whether the tree was constrained to a total height of 1.
$shift.point	The user-specified portion of the branch where a regime shift occurs.
$opts	Settings used for optimization routine.
$data	The shift model dataset, which includes regime painting for each tip.
$phy	The shift model painted phylogeny.
$root.station	A logical indicating whether the starting state, theta_0, was estimated
$starting.vals	the starting values used for the parameter search.
$regime.weights	A table containing parameter estimates and the weights for time spent in each regime for each tip.

Author(s)

Jeremy M. Beaulieu

References

Ho, L.S.T., and C. Ane. 2014. Intrinsic inference difficulties for trait evolution with Ornstein-Uhlenbeck models. Methods in Ecology and Evolution, 5: 1133-1146.

OUwie documentation built on June 15, 2022, 5:15 p.m.