caic.diagnostics {caper}

Diagnostic tools for independent contrasts models

Description

These functions are a set of diagnostic tools to assess whether a particular contrast model is adequate.

Usage

caic.table(caicObj, validNodes=TRUE, nodalValues=FALSE, ultrametric.tol=0.0001,
           CAIC.codes=FALSE, style="CAIC")
caic.diagnostics(caicObj, which.terms=NULL, which.tests=c("NV","SD","AGE"),
           plot=TRUE, outlier=3, ultrametric.tol=0.0001, plot.signif=plot, 
           alpha=0.05, cex.id=0.7,  ...)
## S3 method for class 'caic.diagnostics'
print(x, ...)
caic.robust(caicObj, robust=3)
caic.label(phy, charset=NULL, action="insert", style="CAIC", tips=FALSE)

Arguments

caicObj

An object of class 'caic'

validNodes

A logical indicating whether to return only the nodes at which valid contrasts have been drawn or all nodes in the phylogeny.

nodalValues

A logical indicating whether to include the estimated nodal values in the contrasts table.

ultrametric.tol

A value in branch length units indicating how large a departure from ultrametric path lengths is permitted before calculating node ages is blocked.

CAIC.codes

Should CAIC style node labels be added to the contrast table?

style

Either 'CAIC', which is the default, or 'RLE' for run-length encoded codes.

which.terms

A character vector of the terms in the linear model for which diagnostic checks should be made. The default is to use all terms.

which.tests

A character vector of the tests to conduct. Any of 'NV', 'SD' and 'Age' may be selected and the default is to use all three.

plot

A logical indicating whether or not to create plots of the diagnostic tests.

outlier

A value indicating the size of absolute studentized residuals above which a contrast will be highlighted in diagnostic plots

robust

A value indicating the size of absolute studentized residuals above which a contrast will be removed from the contrast model.

plot.signif

By default, significant relationships are indicated on the plots by showing the model line.

alpha

This value sets the significance at which model predictions are added to the diagnostic plots.

cex.id

Adjust the size of labels added to outlier points.

x

An object of class 'caic diagnostics' to be printed out

...

Generic arguments to print.caic.diagnostics or plot arguments for print.caic.diagnostics.

phy

A 'phylo' object.

charset

A vector of characters to be used to construct CAIC codes.

action

One of 'replace', 'append' or 'insert'.

tips

A logical indicating whether to modify the tip labels of the phylogeny in addition to the internal node labels.

Details

The most general function (caic.table) extracts a data frame from a 'caic' object that contains the contrasts, expected variance ('contrVar'), node depth, number of descendant lineages and studentized residuals. It can also optionally include the nodal values estimated at internal nodes and CAIC style node labels. This data frame is very similar to the output files generated by CAIC and MacroCAIC. By default, only the valid nodes contributing contrasts to the model are shown but other internal nodes can also be included ('validNodes=FALSE').

The caic.diagnostics function carries out a set of regression tests on the absolute values of contrasts in a model. These include regression against estimates of the nodal values ('NV), standard deviation at each node ('SD') and, where the underlying phylogeny is ultrametric, the log age at each node ('AGE'). Significant regressions indicate problems with the distribution of the contrast values. The user can select which of these plots are to be generated and also which terms in the contrasts model will be plotted. The function can also plot these relationships and show the slope of problematic tests (slope significance < alpha).

Plots from the caic.diagnostics function will plot outliers in red and label these points. Outliers are identified as points with absolute studentized residuals greater than the cutoff specified in 'outlier'. The function caic.robust is a simple method to obtain a refitted 'caic' object model from which these outlying contrasts have been excluded.

The caic.label function provides a method to label nodes (and optionally tips) with CAIC phylogeny codes. These are simple alphabetic sequences that indicate the branching structure of the tree from the root and are unique for each node. With deeply nested trees, these codes can be very long and so the option 'RLE' is provided to reduce the length of codes for plotting onto trees: for example, the code AABAAAC would be converted to 2AB3AC. If action is 'replace', then the phylogeny tip and node labels are replaced with the CAIC codes. If action is 'append', then the codes are appended onto the end of existing labels, with the internal node numbers used if no node labels exist. Finally, if action is 'insert', then a named character vector called 'edge.caic.code' is inserted into the 'phylo' object list.

Value

caic.table

A data frame of contrasts and other nodal values.

caic.diagnostics

An array of slope coefficients for each test (rows) and for each term (depth).

caic.robust

A 'caic' object with a model omitting outliers.

caic.labels

A 'phylo' object with modified labels.

Author(s)

David Orme

See Also

crunch, brunch, macrocaic

Examples

data(shorebird)
shorebird <- comparative.data(shorebird.tree, shorebird.data, Species)
crunchMod <- crunch(log(Egg.Mass) ~  log(M.Mass) + log(F.Mass), data=shorebird)
caic.diagnostics(crunchMod)