surfaceSummary: Summarize SURFACE Output
In surface: Fitting Hansen Models to Investigate Convergent Evolution

Description Usage Arguments Details Value Note Author(s) References See Also Examples

Extracts the most important results from the output of the forward, backward, or both phases of a SURFACE analysis

1	surfaceSummary(fwd = NULL, bwd = NULL)

`fwd`	A list returned by `surfaceForward` (which may be stored as the `$fwd` component of the list returned by `runSurface`)
`bwd`	A list returned by `surfaceBackward` (which may be stored as the `$bwd` component of the list returned by `runSurface`)

If both fwd and bwd are provided, both phases of the analysis will be summarized together

A list with the following components:

`n_steps`	number of iterations in the stepwise analysis
`lnls`	matrix of traits-by-iterations, giving the log-likelihood for each trait at each iteration of the analysis
`n_regimes_seq`	matrix of the summaries of regime structure at each iteration of the model
`aics`	vector giving the AICc value at each step
`shifts`	shifts present in the final fitted Hansen model
`n_regimes`	summary of regime structure of the final fitted Hansen model (see note below)
`alpha`	estimate of alpha for each trait in the final model
`sigma_squared`	estimate of sigma_squared for each trait in the final model
`theta`	matrix of estimated optima (one per regime per trait) in the final model

The elements n_regimes_seq and n_regimes contain measures of the regime structure in a SURFACE analysis (for each iteration, and in the final model, respectively). The measures returned are: k (the number of regime shifts, counting the basal regime as 1), kprime, (the number of regimes, some of which may be reached by multiple shifts), deltak (k-kprime, a measure of convergence), c (the number of shifts to convergent regimes, another measure of convergence), kprime_conv (the number of convergent regimes shifted to multiple times), and kprime_nonconv (the number of nonconvergent regimes only shifted to once)

Travis Ingram

Ingram, T. & Mahler, D.L. (2013) SURFACE: detecting convergent evolution from comparative data by fitting Ornstein-Uhlenbeck models with stepwise AIC. Methods in Ecology and Evolution 4: 416-425.

surfaceForward, surfaceBackward

	## Not run: 
data(surfaceDemo)
tree<-surfaceDemo$tree
dat<-surfaceDemo$sim$dat
result<-runSurface(tree,dat)
surfaceSummary(result$fwd,result$bwd)
	
## End(Not run)