crunch: Comparative analysis using the crunch algorithm.
In caper: Comparative Analyses of Phylogenetics and Evolution in R
crunch R Documentation
Comparative analysis using the crunch algorithm.
Description
Calculate a linear model using the crunch algorithm.
Usage
crunch(formula, data, phy, names.col, stand.contr = TRUE, robust=Inf,
ref.var=NULL, node.depth=NULL, polytomy.brlen=0, equal.branch.length=FALSE,
factor.action="abort")
Arguments
formula
A model formula.
data
An 'comparative.data' object. Alternatively, a data frame.
phy
An object of class 'phylo', required when data is not a 'comparative.data' object.
names.col
A name specifying the column in 'data' that matches rows to tips in 'phy', required when data is not a 'comparative.data' object.
stand.contr
A logical flag indicating whether or not to standardize contrasts
.
robust
A threshold value of studentized residuals to exclude from the model.
ref.var
A reference variable present in the model that is used to specify the direction of calculation of contrasts. If null, this is assumed to be the first explanatory variable.
node.depth
A positive integer greater than 1 used to restrict the model to contrasts with a node depth less than or equal to the specified depth. Tips have a depth of 1.
polytomy.brlen
The internal branch length used for calculating contrasts at a polytomy, following Pagel's (1992) method.
equal.branch.length
If set to 'TRUE' then all branch lengths are set to 2.
factor.action
One of "abort", "warn" or "allow", describing whether to stop if the formula contains a factor ("abort"), or continue after converting the factor to a numeric variable, either with ("warn") or without ("allow") a warning.
Details
This function implements the 'crunch' algorithm for modelling the relationship between variables that are phylogenetically non-independent. The method was first described by Felsenstein (1985) and subsequently extended to permit the use of phylogenies with polytomies by Pagel (1992). This method was previously implemented in the Mac Classic computer programs CAIC, written by Andy Purvis, Andy Rambaut (Purvis and Rambaut, 1995) and updated by Nick Isaac and Paul-Michael Agapow.
The user provides a comparative dataset. The formula specifies the model to be fitted and contrasts are calculated in those variables. The specified reference variable is used to ensure that contrasts for multivariate models are calculated in a consistent direction at each node. The function crunch() acts as a data preparation wrapper for the function contrCalc(), which is not intended to be directly called by users. Missing data can be present in the explanatory variables: the algorithm makes use of the complete data available at each node as was the case with CAIC.
The resulting table of contrasts is then used to fit the specified model - note that the intercept is automatically dropped from the model if present, following REF HERE.
Contrasts at polytomies are calculated following Pagel (1992). The descendants from the node are split into two groups based on whether they are above or below the group mean in the reference variable. If there is no variation in the reference variable, then a 1:(N-1) split is used. Weighted means in the variables are then calculated for each subgroup and a contrast is calculated between these values using an arbitrary internal branch length.
Value
A object of class 'caic'.
Warning
At a polytomy, subtracting the internal branch length from the real branch lengths can lead to negative branch lengths. CAIC used a hard-coded internal branch length of 1 for calculating crunch contrasts at polytomies. From version 2.6.9, CAIC issued a warning if this lead to negative branch lengths but allowed contrast calculation to continue. In contrast, the implementation in crunch() uses a default internal branch length (polytomy.brlen) of 0 and also treats a negative branch length in a polytomy calculation as an error. In either case, contrast calculation on negative branch lengths is not a desirable outcome. Duplication of CAIC results therefore requires polytomy.brlen to be set to 1 and an analyis cannot be duplicated precisely if the phylogeny contains polytomies with descending branches shorter than 1. The method used by pic.lm to handle polytomies avoids such problems.
Author(s)
David Orme
References
Felsenstein, J. (1985). Phylogenies and the comparative method. Am. Nat. 125, 1-15
Pagel, M. D. (1992). A method for the analysis of comparative data. J. theor. Biol. 156, 431-442.
Purvis, A. and Rambaut, A. (1995) Comparative analysis by independent contrasts (CAIC): an Apple Macintosh application for analysing comparative data. Computer Appl. Biosciences 11, 247-251.
See Also
caic-class for 'caic' object structure and methods.
Examples
data(shorebird)
shorebird <- comparative.data(shorebird.tree, shorebird.data, Species)
crunchMod <- crunch(Egg.Mass ~ F.Mass + M.Mass, data=shorebird)
summary(crunchMod)
# plot the contrasts
crunchTab <- caic.table(crunchMod)
plot(Egg.Mass ~ F.Mass, crunchTab)
# for the actual model diagnostics
par(mfrow=c(3,2))
caic.diagnostics(crunchMod)
caper documentation built on Sept. 26, 2023, 5:10 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| crunch | R Documentation |
Comparative analysis using the crunch algorithm.
Description
Calculate a linear model using the crunch algorithm.
Usage
crunch(formula, data, phy, names.col, stand.contr = TRUE, robust=Inf,
ref.var=NULL, node.depth=NULL, polytomy.brlen=0, equal.branch.length=FALSE,
factor.action="abort")
Arguments
formula |
A model formula. |
data |
An 'comparative.data' object. Alternatively, a data frame. |
phy |
An object of class 'phylo', required when data is not a 'comparative.data' object. |
names.col |
A name specifying the column in 'data' that matches rows to tips in 'phy', required when data is not a 'comparative.data' object. |
stand.contr |
A logical flag indicating whether or not to standardize contrasts |
.
robust |
A threshold value of studentized residuals to exclude from the model. |
ref.var |
A reference variable present in the model that is used to specify the direction of calculation of contrasts. If null, this is assumed to be the first explanatory variable. |
node.depth |
A positive integer greater than 1 used to restrict the model to contrasts with a node depth less than or equal to the specified depth. Tips have a depth of 1. |
polytomy.brlen |
The internal branch length used for calculating contrasts at a polytomy, following Pagel's (1992) method. |
equal.branch.length |
If set to 'TRUE' then all branch lengths are set to 2. |
factor.action |
One of "abort", "warn" or "allow", describing whether to stop if the formula contains a factor ("abort"), or continue after converting the factor to a numeric variable, either with ("warn") or without ("allow") a warning. |
Details
This function implements the 'crunch' algorithm for modelling the relationship between variables that are phylogenetically non-independent. The method was first described by Felsenstein (1985) and subsequently extended to permit the use of phylogenies with polytomies by Pagel (1992). This method was previously implemented in the Mac Classic computer programs CAIC, written by Andy Purvis, Andy Rambaut (Purvis and Rambaut, 1995) and updated by Nick Isaac and Paul-Michael Agapow.
The user provides a comparative dataset. The formula specifies the model to be fitted and contrasts are calculated in those variables. The specified reference variable is used to ensure that contrasts for multivariate models are calculated in a consistent direction at each node. The function crunch() acts as a data preparation wrapper for the function contrCalc(), which is not intended to be directly called by users. Missing data can be present in the explanatory variables: the algorithm makes use of the complete data available at each node as was the case with CAIC.
The resulting table of contrasts is then used to fit the specified model - note that the intercept is automatically dropped from the model if present, following REF HERE.
Contrasts at polytomies are calculated following Pagel (1992). The descendants from the node are split into two groups based on whether they are above or below the group mean in the reference variable. If there is no variation in the reference variable, then a 1:(N-1) split is used. Weighted means in the variables are then calculated for each subgroup and a contrast is calculated between these values using an arbitrary internal branch length.
Value
A object of class 'caic'.
Warning
At a polytomy, subtracting the internal branch length from the real branch lengths can lead to negative branch lengths. CAIC used a hard-coded internal branch length of 1 for calculating crunch contrasts at polytomies. From version 2.6.9, CAIC issued a warning if this lead to negative branch lengths but allowed contrast calculation to continue. In contrast, the implementation in crunch() uses a default internal branch length (polytomy.brlen) of 0 and also treats a negative branch length in a polytomy calculation as an error. In either case, contrast calculation on negative branch lengths is not a desirable outcome. Duplication of CAIC results therefore requires polytomy.brlen to be set to 1 and an analyis cannot be duplicated precisely if the phylogeny contains polytomies with descending branches shorter than 1. The method used by pic.lm to handle polytomies avoids such problems.
Author(s)
David Orme
References
Felsenstein, J. (1985). Phylogenies and the comparative method. Am. Nat. 125, 1-15
Pagel, M. D. (1992). A method for the analysis of comparative data. J. theor. Biol. 156, 431-442.
Purvis, A. and Rambaut, A. (1995) Comparative analysis by independent contrasts (CAIC): an Apple Macintosh application for analysing comparative data. Computer Appl. Biosciences 11, 247-251.
See Also
caic-class for 'caic' object structure and methods.
Examples
data(shorebird)
shorebird <- comparative.data(shorebird.tree, shorebird.data, Species)
crunchMod <- crunch(Egg.Mass ~ F.Mass + M.Mass, data=shorebird)
summary(crunchMod)
# plot the contrasts
crunchTab <- caic.table(crunchMod)
plot(Egg.Mass ~ F.Mass, crunchTab)
# for the actual model diagnostics
par(mfrow=c(3,2))
caic.diagnostics(crunchMod)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.