R: Phylogenetic regression with intraspecific sampling error

pgls.Ives {phytools}

R Documentation

Phylogenetic regression with intraspecific sampling error

Description

Phylogenetic regression with within-species sampling error following Ives et al. (2007).

Usage

pgls.Ives(tree, X, y, Vx=NULL, Vy=NULL, Cxy=NULL, lower=c(1e-8,1e-8),
    fixed.b1=NULL)
pgls.SEy(model, data, corClass=corBrownian, tree,
    se=NULL, method=c("REML","ML"), interval=c(0,1000), ...)

Arguments

`tree`	a phylogeny as an object of class `"phylo"`.
`X`	a named vector containing a single independent variable (multiple independent variables to be added in future). `X` can contain the species means, or a single long vector containing the sample of values for each species. In the latter case the `names(X)` will be repeating - all samples from the same species should have the same name.
`y`	vector the dependent variable. Can be species means or individual values, as for `X`.
`Vx`	sampling variances for `X`. If `NULL`, then the within-species variance is computed from the data assuming that individual samples, not species means, have been provided in `X`.
`Vy`	sampling variances for `y`. If `NULL`, then the within-species variance is computed from the data assuming that individual samples, not species means, have been provided in `y`.
`Cxy`	sampling covariances between `X` and `y`. This will also be computed from the data if `Cxy==NULL`. Note than in this case - but not for the calculation of `Vx` and `Vy`, the same number of observations and the same ordering must be provided for `X` and `y`. If this is not the case, then it is assumed that different individuals have been sampled for `X` and `y` and thus `Cxy` is assumed to be zero for all species.
`lower`	vector specifying the lower bounds for estimation for `\sigma_x^2` and `\sigma_y^2`, respectively. (Must be > 0.)
`fixed.b1`	fixed regression slope, `\beta`. Usually set to zero for null hypothesis testing.
`model`	model to fit. (For `pgls.SEy`.)
`data`	data frame. (For `pgls.SEy`.)
`corClass`	correlation structure. (For `pgls.SEy`.)
`se`	vector of standard errors in y. (For `pgls.SEy`.)
`method`	optimization method. (For `pgls.SEy`.)
`interval`	interval over which to perform optimization. (For `pgls.SEy`.)
`...`	optional arguments. (For `pgls.SEy`.)

Details

pgls.Ives fits the phylogenetic regression model with within-species sampling error following Ives et al. (2007).

pgls.SEy fits a simpler model in which only sampling error in y is taken into account. This function uses gls from the nlme package internally for optimization and returns an object of class "gls" that is compatible with all methods for that object class.

In the case of pgls.Ives, only the bivariate regression model is implemented. Note that some problems have been reported with the optimization algorithm for this model, which is simple and thus may fail to find the ML solution.

In the case of pgls.SEy the user can (theoretically) specify any class of linear model permitted by gls.

Value

In the case of pgls.Ives, an object of class "pgls.Ives" with the following elements:

`beta`	a vector or matrix of regression coefficients.
`sig2x`	fitted BM rate for `X`.
`sig2y`	fitted BM rate for `y`.
`a`	fitted ancestral states for `X` and `y`.
`logL`	log-likelihood.
`convergence`	a value for convergence. `convergence=0` is good; see `optim` for more details.
`message`	a message for convergence.

In the case of pgls.SEy, an object of class "gls".

Author(s)

Liam Revell liam.revell@umb.edu

References

Ives, A. R., P. E. Midford, and T. Garland Jr. (2007) Within-species measurement error in phylogenetic comparative methods. Systematic Biology, 56, 252-270.

Revell, L. J. (2024) phytools 2.0: an updated R ecosystem for phylogenetic comparative methods (and other things). PeerJ, 12, e16505.