pgls: Phylogenetic generalized linear models
In caper: Comparative Analyses of Phylogenetics and Evolution in R

View source: R/pgls.R

pgls	R Documentation

Phylogenetic generalized linear models

Description

Fits a linear model, taking into account phylogenetic non-independence between data points. The strength and type of the phylogenetic signal in the data matrix can also be accounted for by adjusting branch length transformations (lambda, delta and kappa). These transformations can also be optimised to find the maximum likelihood transformation given the data and the model.

Usage

pgls(formula, data, lambda = 1.0, kappa = 1.0,  delta= 1.0, param.CI = 0.95, 
	 control = list(fnscale=-1), bounds = NULL)
pgls.likelihood(optimPar, fixedPar, y, x, V, optim.output=TRUE, names.optim=NULL)
pgls.blenTransform(V, fixedPar)

Arguments

`formula`	A model formula
`data`	A 'comparative.data' object containing the covariance matrix and data to be used in the model.
`lambda`	A value for the lambda transformation.
`kappa`	A value for the kappa transformation.
`delta`	A value for the delta transformation.
`param.CI`	A p value used to calculate confidence intervals.
`control`	A list of control parameters for the optim function.
`bounds`	A list of bounds to use for branch length transformations (see Details).
`optimPar`	A named vector of branch length parameters to be optimised to find the maximum likelihood value.
`fixedPar`	A named vector of fixed values for branch length parameters.
`y`	A column matrix of the model response.
`x`	The design matrix of the model.
`V`	A phylogenetic covariance matrix.
`optim.output`	A logical value. If true then 'pgls.likelihood' returns only the likelihood value for use in the 'optim' function.
`names.optim`	The name of a single parameter being optimised. This is only required for estimating parameter confidence intervals, where the function 'uniroot' strips names from vectors.

Details

This function fits a linear model controlling for the non-independence between cases resulting from phylogenetic structure in the data. The stucture of the phylogenetic signal can be controlled by altering the parameters lambda, delta and kappa (see the 'caper' vignette for details). The implementation of the method is currently as described in Freckleton et al (2002).

The branch length transformations can be optimised between bounds using maximum likelihood by setting the value for a transformation to 'ML'. The default bounds are: lambda = c(1e-6,1), kappa = c(1e-6,3) and delta=c(1e-6,3). These defaults may be overridden by passing a named list with new elements to the bounds argument - only the bounds to be changed need to be provided (e.g. bounds=list(lambda=c(0,3))).

The 'pgls.likelihood' and 'pgls.blenTransform' methods are not primarily intended to be called by users. The 'pgls.likelihood' function provides a general method to calculate the likelihood of a model, given the covariance matrix, response, design matrix and branch length parameters.

Value

The 'pgls' function returns an object of class pgls containing the following:

"na.action" "param.CI"

`call`	The original call to the 'pgls' function
`model`	A summary of the fitted model containing:
`formula`	The model formula supplied.
`data`	The comparative data object provided.
`dname`	The name of the comparative data object.
`logLikY`	The log likelihood of the response variable given the model.
`RMS`	The residual mean square variance in the model.
`RSSQ`	The residual sum of squares from the model.
`NMS`	The null mean square variance for the model.
`NSSQ`	The null sum of squares for the response.
`aic`	The AIC score of the model
`aicc`	The AICc score of the model, correcting for the number of cases and parameters estimated
`n`	The number of rows of data used in fitting the model
`k`	The number of parameter estimates
`sterr`	The standard errors of the parameter estimates
`Vt`	The phylogenetic covariance matrix used in the model, with branch length transformations applied.
`fitted`	The predicted values
`residuals`	The non-phylogenetic residuals
`phyres`	The phylogenetic residuals
`x`	The design matrix of the model
`varNames`	The variables include in the model.
`y`	The response of the model.
`namey`	The name of the response variable.
`param`	A named numeric vector of length three giving the branch length transformations used in the model.
`mlVals`	A named logical vector of length three indicating which branch length values in 'param' are maximum likelihood estimates.
`bounds`	The bounds on branch length parameter estimates used in the model.
`param.CI`	A named list of length three giving confidence intervals and the p values at the parameter bounds for optimised branch length transformations. Fixed parameters will have a NULL entry in this list.
`na.action`	A named vector identifying any rows of missing data excluded from the model.

Warning

The model is fitted using a data frame reduced to complete row cases to eliminate missing values. In order to ensure that the models fitted using different subsets of the data are comparable, the whole data frame data is reduced to complete cases. In the future, a scope argument may be provided to control this but at present the data frame should be reduced to only those variables used in the maximal model in order to avoid prevent redundant variables causing rows to be dropped unnecessarily.

Author(s)

Rob Freckleton; David Orme

References

R. P. Freckleton, P. H. Harvey, and M. Pagel. Phylogenetic analysis and comparative data: A test and review of evidence. American Naturalist, 160:712-726, 2002.

Examples

data(shorebird)
shorebird <- comparative.data(shorebird.tree, shorebird.data, Species, vcv=TRUE, vcv.dim=3)
mod1 <- pgls(log(Egg.Mass) ~ log(M.Mass) * log(F.Mass), shorebird, lambda='ML')
mod2 <- pgls(log(Egg.Mass) ~ log(M.Mass), data=shorebird, lambda='ML', delta='ML')

caper documentation built on Sept. 26, 2023, 5:10 p.m.