Package 'phyr'

Title: Model Based Phylogenetic Analysis
Description: A collection of functions to do model-based phylogenetic analysis. It includes functions to calculate community phylogenetic diversity, to estimate correlations among functional traits while accounting for phylogenetic relationships, and to fit phylogenetic generalized linear mixed models. The Bayesian phylogenetic generalized linear mixed models are fitted with the 'INLA' package (<https://www.r-inla.org>).
Authors: Anthony Ives [aut], Russell Dinnage [aut] (ORCID: <https://orcid.org/0000-0003-0846-2819>), Lucas A. Nell [aut] (ORCID: <https://orcid.org/0000-0003-3209-0517>), Matthew Helmus [aut], Daijiang Li [aut, cre] (ORCID: <https://orcid.org/0000-0002-0925-3421>)
Maintainer: Daijiang Li <[email protected]>
License: GPL-3
Version: 1.3.0
Built: 2026-11-18 00:11:33 UTC
Source: https://github.com/daijiang/phyr

Help Index


Not in

Description

This function will return elements of x not in y

Usage

x %nin% y

Arguments

x

A vector.

y

A vector.

Value

A vector.


Create phylogenetic var-cov matrix based on phylogeny and community data

Description

This function will remove species from community data that are not in the phylogeny. It will also remove tips from the phylogeny that are not in the community data. And then convert the phylogeny to a Var-cov matrix.

Usage

align_comm_V(comm, tree, prune.tree = FALSE, scale.vcv = TRUE)

Arguments

comm

A site by species data frame, with site names as row names.

tree

A phylogeny with "phylo" as class; or a phylogenetic var-covar matrix.

prune.tree

Whether to prune the tree first then use vcv.phylo function. Default is FALSE: use vcv.phylo first then subsetting the matrix.

scale.vcv

Whether to scale vcv to a correlation matrix.

Value

A list of the community data and the phylogenetic var-cov matrix.


Generic method to output bootstrap confidence intervals from an object.

Description

Implemented only for cor_phylo objects thus far.

Usage

boot_ci(mod, ...)

Arguments

mod

A cor_phylo object.

...

Additional arguments.

Value

A list of confidence intervals.


Example community data

Description

A data frame with site names as row names, species names as column names, cells are the abundance of each species at each site.

Usage

comm_a

Format

A data frame with 15 sites and 15 species.


Example community data

Description

A data frame with site names as row names, species names as column names, cells are the abundance of each species at each site.

Usage

comm_b

Format

A data frame with 15 sites and 9 species.


Correlations among multiple variates with phylogenetic signal

Description

This function calculates Pearson correlation coefficients for multiple continuous variates that may have phylogenetic signal, allowing users to specify measurement error as the standard error of variate values at the tips of the phylogenetic tree. Phylogenetic signal for each variate is estimated from the data assuming that variate evolution is given by a Ornstein-Uhlenbeck process. Thus, the function allows the estimation of phylogenetic signal in multiple variates while incorporating correlations among variates. It is also possible to include independent variables (covariates) for each variate to remove possible confounding effects. cor_phylo returns the correlation matrix for variate values, estimates of phylogenetic signal for each variate, and regression coefficients for independent variables affecting each variate.

Usage

cor_phylo(variates, species, phy,
          covariates = NULL, 
          meas_errors = NULL,
          data = sys.frame(sys.parent()),
          REML = TRUE, 
          method = c("nelder-mead-r", "bobyqa",
              "subplex", "nelder-mead-nlopt", "sann"),
          no_corr = FALSE,
          constrain_d = FALSE,
          lower_d = 1e-7,
          rel_tol = 1e-6,
          max_iter = 1000,
          sann_options = NULL,
          verbose = FALSE,
          rcond_threshold = 1e-10,
          boot = 0,
          keep_boots = c("fail", "none", "all"))

## S3 method for class 'cor_phylo'
boot_ci(mod, refits = NULL, alpha = 0.05, ...)

## S3 method for class 'cor_phylo'
print(x, digits = max(3, getOption("digits") - 3), ...)

Arguments

variates

A formula or a matrix specifying variates between which correlations are being calculated. The formula should be one-sided of the form ~ A + B + C for variate vectors A, B, and C that are present in data. In the matrix case, the matrix must have n rows and p columns (for p variates); if the matrix columns aren't named, cor_phylo will name them ⁠par_1 ... par_p⁠.

species

A one-sided formula implicating the variable inside data representing species, or a vector directly specifying the species. If a formula, it must be of the form ~ spp for the spp object containing the species information inside data. If a vector, it must be the same length as that of the tip labels in phy, and it will be coerced to a character vector like phy's tip labels.

phy

Either a phylogeny of class phylo or a prepared variance-covariance matrix. If it is a phylogeny, we will coerce tip labels to a character vector, and convert it to a variance-covariance matrix assuming brownian motion evolution. We will also standardize all var-cov matrices to have determinant of one.

covariates

A list specifying covariate(s) for each variate. The list can contain only two-sided formulas or matrices. Formulas should be of the typical form: y ~ x1 + x2 or y ~ x1 * x2. If using a list of matrices, each item must be named (e.g., list(y = matrix(...)) specifying variate y's covariates). If the matrix columns aren't named, cor_phylo will name them ⁠cov_1 ... cov_q⁠, where q is the total number of covariates for all variates. Having factor covariates is not supported. Defaults to NULL, which indicates no covariates.

meas_errors

A list or matrix containing standard errors for each variate. If a list, it must contain only two-sided formulas like those for covariates (except that you can't have multiple measurement errors for a single variate). You can additionally pass an n-row matrix with column names corresponding to the associated variate names. Defaults to NULL, which indicates no measurement errors.

data

An optional data frame, list, or environment that contains the variables in the model. By default, variables are taken from the environment from which cor_phylo was called.

REML

Whether REML (versus ML) should be used for model fitting. Defaults to TRUE.

method

Method of optimization using nlopt or optim. Options include "nelder-mead-nlopt", "bobyqa", "subplex", "nelder-mead-r", and "sann". The first three are carried out by nlopt, and the latter two by optim. See https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/ for information on the nlopt algorithms. Defaults to "nelder-mead-r".

no_corr

A single logical for whether to make all correlations zero. Running cor_phylo with no_corr = TRUE is useful for comparing it to the same model run with correlations != 0. Defaults to FALSE.

constrain_d

If constrain_d is TRUE, the estimates of d are constrained to be between zero and 1. This can make estimation more stable and can be tried if convergence is problematic. This does not necessarily lead to loss of generality of the results, because before using cor_phylo, branch lengths of phy can be transformed so that the "starter" tree has strong phylogenetic signal. Defaults to FALSE.

lower_d

Lower bound on the phylogenetic signal parameter. Defaults to 1e-7.

rel_tol

A control parameter dictating the relative tolerance for convergence in the optimization. Defaults to 1e-6.

max_iter

A control parameter dictating the maximum number of iterations in the optimization. Defaults to 1000.

sann_options

A named list containing the control parameters for SANN minimization. This is only relevant if method == "sann". This list can only contain the names "maxit", "temp", and/or "tmax", which will control the maximum number of iterations, starting temperature, and number of function evaluations at each temperature, respectively. Defaults to NULL, which results in maxit = 1000, temp = 1, and tmax = 1. Note that these are different from the defaults for optim.

verbose

If TRUE, the model logLik and running estimates of the correlation coefficients and values of d are printed each iteration during optimization. Defaults to FALSE.

rcond_threshold

Threshold for the reciprocal condition number of two matrices inside the log likelihood function. Increasing this threshold makes the optimization process more strongly "bounce away" from badly conditioned matrices and can help with convergence and with estimates that are nonsensical. Defaults to 1e-10.

boot

Number of parametric bootstrap replicates. Bootstrapping can be run in parallel if future.apply is installed and if future::plan(...) is run before the call to cor_phylo. See the documentation for future::plan for the various options. Defaults to 0.

keep_boots

Character specifying when to output data (convergence codes and simulated variate data) from bootstrap replicates. This is useful for troubleshooting when one or more bootstrap replicates fails to converge or outputs ridiculous results. Setting this to "all" keeps all boot parameter sets, "fail" keeps sets from replicates that failed to converge, and "none" keeps no sets. Defaults to "fail".

mod

cor_phylo object that was run with the boot argument > 0.

refits

One or more cp_refits objects containing refits of cor_phylo bootstrap replicates. These are used when the original fit did not converge. Multiple cp_refits objects should be input as a list. For a given bootstrap replicate, the original fit's estimates will be used when the fit converged. If multiple cp_refits objects are input and more than one converged for a given replicate, the estimates from the first cp_refits object contain a converged fit for that replicate will be used. Defaults to NULL.

alpha

Alpha used for the confidence intervals. Defaults to 0.05.

...

arguments passed to and from other methods.

x

an object of class cor_phylo.

digits

the number of digits to be printed.

Value

cor_phylo returns an object of class cor_phylo:

call

The matched call.

corrs

The p x p matrix of correlation coefficients.

d

Values of d from the OU process for each variate.

B

A matrix of regression-coefficient estimates, SE, Z-scores, and P-values, respectively. Rownames indicate which coefficient it refers to.

B_cov

Covariance matrix for regression coefficients.

logLik

The log likelihood for either the restricted likelihood (REML = TRUE) or the overall likelihood (REML = FALSE).

AIC

AIC for either the restricted likelihood (REML = TRUE) or the overall likelihood (REML = FALSE).

BIC

BIC for either the restricted likelihood (REML = TRUE) or the overall likelihood (REML = FALSE).

niter

Number of iterations the optimizer used.

convcode

Conversion code for the optimizer. This number is 0 on success and positive on failure.

1

iteration limit reached

2

generic failure code (nlopt optimizers only).

3

invalid arguments (nlopt optimizers only).

4

out of memory (nlopt optimizers only).

5

roundoff errors limited progress (nlopt optimizers only).

6

user-forced termination (nlopt optimizers only).

10

degeneracy of the Nelder-Mead simplex (stats::optim only).

For more information on the nlopt return codes, see https://nlopt.readthedocs.io/en/latest/NLopt_Reference/#return-values.

rcond_vals

Reciprocal condition numbers for two matrices inside the log likelihood function. These are provided to potentially help guide the changing of the rcond_threshold parameter. If they are listed as NaN, then one or more of the matrices contains NA before being passed through the rcond function.

bootstrap

A list of bootstrap output, which is simply list() if boot = 0. If boot > 0, then the list contains fields for estimates of correlations (corrs), phylogenetic signals (d), coefficients (B0), and coefficient covariances (B_cov), plus a vector of convergence codes (convcodes). Depending on the value of keep_boots, this list may also contain a list of matrices containing the bootstrapped parameter sets (mats). If keep_boots == "fail", then mats will contain a ⁠<0 x 0 matrix>⁠ for rep(s) that succeed. To view bootstrapped confidence intervals, use boot_ci.

boot_ci returns a list of confidence intervals with the following fields:

corrs

Estimates of correlations. This is a matrix the values above the diagonal being the upper limits and values below being the lower limits.

d

Phylogenetic signals.

B0

Coefficient estimates.

B_cov

Coefficient covariances.

Methods (by generic)

  • boot_ci(cor_phylo): returns bootstrapped confidence intervals from a cor_phylo object

  • print(cor_phylo): prints cor_phylo objects

Walkthrough

For the case of two variables, the function estimates parameters for the model of the form, for example,

X[1]=B[1,0]+B[1,1]∗u[1,1]+ϵ[1]X[1] = B[1,0] + B[1,1] * u[1,1] + \epsilon[1]

X[2]=B[2,0]+B[2,1]∗u[2,1]+ϵ[2]X[2] = B[2,0] + B[2,1] * u[2,1] + \epsilon[2]

ϵ Gaussian(0,V)\epsilon ~ Gaussian(0, V)

where B[1,0]B[1,0], B[1,1]B[1,1], B[2,0]B[2,0], and B[2,1]B[2,1] are regression coefficients, and VV is a variance-covariance matrix containing the correlation coefficient r, parameters of the OU process d1d1 and d2d2, and diagonal matrices M1M1 and M2M2 of measurement standard errors for X[1]X[1] and X[2]X[2]. The matrix VV is 2nx2n2n x 2n, with nxnn x n blocks given by

V[1,1]=C[1,1](d1)+M1V[1,1] = C[1,1](d1) + M1

V[1,2]=C[1,2](d1,d2)V[1,2] = C[1,2](d1,d2)

V[2,1]=C[2,1](d1,d2)V[2,1] = C[2,1](d1,d2)

V[2,2]=C[2,2](d2)+M2V[2,2] = C[2,2](d2) + M2

where C[i,j](d1,d2)C[i,j](d1,d2) are derived from phy under the assumption of joint OU evolutionary processes for each variate (see Zheng et al. 2009). This formulation extends in the obvious way to more than two variates.

Author(s)

Anthony R. Ives, Lucas A. Nell

References

Zheng, L., A. R. Ives, T. Garland, B. R. Larget, Y. Yu, and K. F. Cao. 2009. New multivariate tests for phylogenetic signal and trait correlations applied to ecophysiological phenotypes of nine Manglietia species. Functional Ecology 23:1059–1069.

Examples

## Simple example using data without correlations or phylogenetic
## signal. This illustrates the structure of the input data.

set.seed(10)
phy <- ape::rcoal(10, tip.label = 1:10)
data_df <- data.frame(
    species = phy$tip.label,
    # variates:
    par1 = rnorm(10),
    par2 = rnorm(10),
    par3 = rnorm(10),
    # covariate for par2:
    cov2 = rnorm(10, mean = 10, sd = 4),
    # measurement error for par1 and par2, respectively:
    se1 = 0.2,
    se2 = 0.4
)
data_df$par2 <- data_df$par2 + 0.5 * data_df$cov2


cp <- cor_phylo(variates = ~ par1 + par2 + par3,
                covariates = list(par2 ~ cov2),
                meas_errors = list(par1 ~ se1, par2 ~ se2),
                species = ~ species,
                phy = phy,
                data = data_df)

# If you've already created matrices/lists...
X <- as.matrix(data_df[,c("par1", "par2", "par3")])
U <- list(par2 = cbind(cov2 = data_df$cov2))
M <- cbind(par1 = data_df$se1, par2 = data_df$se2)

# ... you can also use those directly
# (notice that I'm inputting an object for `species`
# bc I ommitted `data`):
cp2 <- cor_phylo(variates = X, species = data_df$species,
                 phy = phy, covariates = U,
                 meas_errors = M)



# 
# 
# ## Simulation example for the correlation between two variables. The example
# ## compares the estimates of the correlation coefficients from cor_phylo when
# ## measurement error is incorporated into the analyses with three other cases:
# ## (i) when measurement error is excluded, (ii) when phylogenetic signal is
# ## ignored (assuming a "star" phylogeny), and (iii) neither measurement error
# ## nor phylogenetic signal are included.
# 
# # In the simulations, variable 2 is associated with a single independent variable.
# 
# library(ape)
# 
# set.seed(1)
# # Set up parameter values for simulating data
# n <- 50
# phy <- rcoal(n, tip.label = 1:n)
# trt_names <- paste0("par", 1:2)
# 
# R <- matrix(c(1, 0.7, 0.7, 1), nrow = 2, ncol = 2)
# d <- c(0.3, 0.95)
# B2 <- 1
# 
# Se <- c(0.2, 1)
# M <- matrix(Se, nrow = n, ncol = 2, byrow = TRUE)
# colnames(M) <- trt_names
# 
# # Set up needed matrices for the simulations
# p <- length(d)
# 
# star <- stree(n)
# star$edge.length <- array(1, dim = c(n, 1))
# star$tip.label <- phy$tip.label
# 
# Vphy <- vcv(phy)
# Vphy <- Vphy/max(Vphy)
# Vphy <- Vphy/exp(determinant(Vphy)$modulus[1]/n)
# 
# tau <- matrix(1, nrow = n, ncol = 1) %*% diag(Vphy) - Vphy
# C <- matrix(0, nrow = p * n, ncol = p * n)
# for (i in 1:p) for (j in 1:p) {
#   Cd <- (d[i]^tau * (d[j]^t(tau)) * (1 - (d[i] * d[j])^Vphy))/(1 - d[i] * d[j])
#   C[(n * (i - 1) + 1):(i * n), (n * (j - 1) + 1):(j * n)] <- R[i, j] * Cd
# }
# MM <- matrix(M^2, ncol = 1)
# V <- C + diag(as.numeric(MM))
# 
# # Perform a Cholesky decomposition of Vphy. This is used to generate phylogenetic
# # signal: a vector of independent normal random variables, when multiplied by the
# # transpose of the Cholesky deposition of Vphy will have covariance matrix
# # equal to Vphy.
# iD <- t(chol(V))
# 
# # Perform Nrep simulations and collect the results
# Nrep <- 100
# cor.list <- matrix(0, nrow = Nrep, ncol = 1)
# cor.noM.list <- matrix(0, nrow = Nrep, ncol = 1)
# cor.noP.list <- matrix(0, nrow = Nrep, ncol = 1)
# cor.noMP.list <- matrix(0, nrow = Nrep, ncol = 1)
# d.list <- matrix(0, nrow = Nrep, ncol = 2)
# d.noM.list <- matrix(0, nrow = Nrep, ncol = 2)
# B.list <- matrix(0, nrow = Nrep, ncol = 3)
# B.noM.list <- matrix(0, nrow = Nrep, ncol = 3)
# B.noP.list <- matrix(0, nrow = Nrep, ncol = 3)
# 
# 
# set.seed(2)
# for (rep in 1:Nrep) {
# 
#   XX <- iD %*% rnorm(2 * n)
#   X <- matrix(XX, n, p)
#   colnames(X) <- trt_names
# 
#   U <- list(cbind(rnorm(n, mean = 2, sd = 10)))
#   names(U) <- trt_names[2]
# 
#   X[,2] <- X[,2] + B2[1] * U[[1]][,1] - B2[1] * mean(U[[1]][,1])
# 
#   # Call cor_phylo with (i) phylogeny and measurement error,
#   # (ii) just phylogeny,
#   # and (iii) just measurement error
#   z <- cor_phylo(variates = X,
#                  covariates = U,
#                  meas_errors = M,
#                  phy = phy,
#                  species = phy$tip.label)
#   z.noM <- cor_phylo(variates = X,
#                      covariates = U,
#                      phy = phy,
#                      species = phy$tip.label)
#   z.noP <- cor_phylo(variates = X,
#                      covariates = U,
#                      meas_errors = M,
#                      phy = star,
#                      species = phy$tip.label)
# 
#   cor.list[rep] <- z$corrs[1, 2]
#   cor.noM.list[rep] <- z.noM$corrs[1, 2]
#   cor.noP.list[rep] <- z.noP$corrs[1, 2]
#   cor.noMP.list[rep] <- cor(cbind(
#     lm(X[,1] ~ 1)$residuals,
#     lm(X[,2] ~ U[[1]])$residuals))[1,2]
# 
#   d.list[rep, ] <- z$d
#   d.noM.list[rep, ] <- z.noM$d
# 
#   B.list[rep, ] <- z$B[,1]
#   B.noM.list[rep, ] <- z.noM$B[,1]
#   B.noP.list[rep, ] <- z.noP$B[,1]
# }
# 
# correlation <- rbind(R[1, 2], mean(cor.list), mean(cor.noM.list),
#                      mean(cor.noP.list), mean(cor.noMP.list))
# rownames(correlation) <- c("True", "With M and Phy", "Without M",
#                            "Without Phy", "Without Phy or M")
# 
# signal.d <- rbind(d, colMeans(d.list), colMeans(d.noM.list))
# rownames(signal.d) <- c("True", "With M and Phy", "Without M")
# 
# est.B <- rbind(c(0, 0, B2), colMeans(B.list),
#                colMeans(B.noM.list[-39,]),  # 39th rep didn't converge
#                colMeans(B.noP.list))
# rownames(est.B) <- c("True", "With M and Phy", "Without M", "Without Phy")
# colnames(est.B) <- rownames(z$B)
# 
# # Example simulation output:
# 
# correlation
# #                       [,1]
# # True             0.7000000
# # With M and Phy   0.6943712
# # Without M        0.2974162
# # Without Phy      0.3715406
# # Without Phy or M 0.3291473
# 
# signal.d
# #                     [,1]      [,2]
# # True           0.3000000 0.9500000
# # With M and Phy 0.3025853 0.9422067
# # Without M      0.2304527 0.4180208
# 
# est.B
# #                      par1_0    par2_0 par2_cov_1
# # True            0.000000000 0.0000000  1.0000000
# # With M and Phy -0.008838245 0.1093819  0.9995058
# # Without M      -0.008240453 0.1142330  0.9995625
# # Without Phy     0.002933341 0.1096578  1.0028474

Example environmental data

Description

A data frame of site environmental variables.

Usage

envi

Format

A data frame with 15 sites and 4 variables: sand proportion, canopy shade proportion, precipitation, and minimum temperature.


Family Objects for communityPGLMM objects

Description

Family Objects for communityPGLMM objects

Usage

## S3 method for class 'communityPGLMM'
family(object, ...)

Arguments

object

the function family accesses the family objects which are stored within objects created by modelling functions (e.g., glm).

...

further arguments passed to methods.


Fitted values for communityPGLMM

Description

Fitted values on the scale of the response, conditional on the estimated random effects.

Usage

## S3 method for class 'communityPGLMM'
fitted(object, ...)

Arguments

object

A fitted model with class communityPGLMM.

...

Additional arguments passed to pglmm_predicted_values() for gaussian models fitted with bayes = FALSE (e.g. gaussian.pred).

Value

Fitted values. For binomial and poisson PGLMMs, this is equal to mu.

Examples

# community data: presence or absence of each species at each site
dat <- data.frame(
  site = rep(rownames(comm_a), times = ncol(comm_a)),
  sp = rep(colnames(comm_a), each = nrow(comm_a)),
  freq = unlist(comm_a, use.names = FALSE)
)
dat$pa <- as.numeric(dat$freq > 0)
dat$shade <- envi$shade[match(dat$site, envi$site)]
phy <- ape::keep.tip(phylotree, unique(dat$sp))

# gaussian model: fixed part plus the estimates of random effects
fit <- pglmm(freq ~ shade + (1 | sp__) + (1 | site),
  data = dat, cov_ranef = list(sp = phy)
)
head(fitted(fit))

# binomial model: fitted probabilities
fit_pa <- pglmm(pa ~ shade + (1 | sp__) + (1 | site),
  data = dat, family = "binomial", cov_ranef = list(sp = phy)
)
head(fitted(fit_pa))

Extract fixed-effects estimates

Description

Extract the fixed-effects estimates

Usage

## S3 method for class 'communityPGLMM'
fixef(object, ...)

Arguments

object

A fitted model with class communityPGLMM.

...

Ignored.

Details

Extract the estimates of the fixed-effects parameters from a fitted model. For bayesian models, the p-values are simply to indicate whether the credible intervals include 0 (p = 0.04) or not (p = 0.6).

Value

A dataframe of fixed-effects estimates.


get_design_matrix gets design matrix for gaussian, binomial, and poisson models

Description

get_design_matrix gets design matrix for gaussian, binomial, and poisson models

Usage

get_design_matrix(formula, data, random.effects, na.action = NULL)

Arguments

formula

A two-sided linear formula object describing the mixed effects of the model.

To specify that a random term should have phylogenetic covariance matrix along with non-phylogenetic one, add __ (two underscores) at the end of the group variable; e.g., + (1 | sp__) will construct two random terms, one with phylogenetic covariance matrix and another with non-phylogenetic (identity) matrix. In contrast, __ in the nested terms (below) will only create a phylogenetic covariance matrix. Nested random terms have the general form (1|sp__@site__) which represents phylogenetically related species nested within correlated sites. This form can be used for bipartite questions. For example, species could be phylogenetically related pollinators and sites could be phylogenetically related plants, leading to the random effect (1|insects__@plants__). If more than one phylogeny is used, remember to add all to the argument cov_ranef = list(insects = insect_phylo, plants = plant_phylo). Phylogenetic correlations can be dropped by removing the __ underscores. Thus, the form (1|sp@site__) excludes the phylogenetic correlations among species, while the form (1|sp__@site) excludes the correlations among sites.

Note that correlated random terms are not allowed. For example, (x|g) will be the same as (0 + x|g) in the lme4::lmer syntax. However, (x1 + x2|g) won't work, so instead use (x1|g) + (x2|g).

data

A data.frame containing the variables named in formula. Rows where the response variable is NA are dropped before fitting; this is equivalent to removing those rows from data manually before calling pglmm. As a result, pglmm(data_with_NAs) and pglmm(data[!is.na(data$y), ]) produce identical estimates.

random.effects

Optional pre-build list of random effects. If NULL (the default), the function prep_dat_pglmm will prepare the random effects for you from the information in formula, data, and cov_ranef. random.effect allows a list of pre-generated random effects terms to increase flexibility; for example, this makes it possible to construct models with both phylogenetic correlation and spatio-temporal autocorrelation. In preparing random.effect, make sure that the orders of rows and columns of covariance matrices in the list are the same as their corresponding group variables in the data. Also, this should be a list of lists, e.g. random.effects = list(re1 = list(matrix_a), re2 = list(1, sp = sp, covar = Vsp)).

na.action

What to do with NAs?

Value

A list of design matrices.


Log-likelihood of a communityPGLMM Model

Description

The log-likelihood of a model fitted with bayes = FALSE (the restricted log-likelihood if REML = TRUE), with the number of parameters as attribute df, so that stats::AIC() gives x$AIC. For binomial and poisson models, it is the approximate log-likelihood calculated by pglmm(): with method = "Laplace", the Laplace approximation of the marginal log-likelihood (the same as lme4::glmer() and glmmTMB() with REML = FALSE), and df is the number of fixed effects and variances; with method = "PQL", the log-likelihood of the gaussian model of the working response, which is not comparable with that of other software. Note that stats::BIC() uses log(nobs) and thus differs from x$BIC.

Usage

## S3 method for class 'communityPGLMM'
logLik(object, ...)

Arguments

object

A fitted model with class communityPGLMM.

...

Additional arguments, currently ignored.

Value

An object of class logLik.


Match phylogeny with community data

Description

This function will remove species from community data that are not in the phylogeny. It will also remove tips from the phylogeny that are not in the community data.

Usage

match_comm_tree(comm, tree, comm_2 = NULL)

Arguments

comm

A site by species data frame, with site names as row names.

tree

A phylogeny with "phylo" as class.

comm_2

Another optional site by species data frame, if presented, both community data and the phylogeny will have the same set of species. This can be useful for PCD with custom species pool.

Value

A list of the community data and the phylogeny.


Extracting the Model Frame from a communityPGLMM Model object

Description

Extracting the Model Frame from a communityPGLMM Model object

Usage

## S3 method for class 'communityPGLMM'
model.frame(formula, ...)

Arguments

formula

a model formula or terms object or an R object.

...

for model.frame methods, a mix of further arguments such as data, na.action, subset to pass to the default method. Any additional arguments (such as offset and weights or other named arguments) which reach the default method are used to create further columns in the model frame, with parenthesised names such as "(offset)".

For get_all_vars, further named columns to include in the model frame.


Number of Observation in a communityPGLMM Model

Description

Number of Observation in a communityPGLMM Model

Usage

## S3 method for class 'communityPGLMM'
nobs(object, use.fallback = FALSE, ...)

Arguments

object

a fitted model object.

use.fallback

logical: should fallback methods be used to try to guess the value?

...

further arguments to be passed to methods.


Phylogeny and community data from an Oldfield ecosystem in Southern Ontario, Canada

Description

A list containing a phylogeny for XX species of Oldfield forbs, as well as a presence / absence dataset for their occurrence across several locations in Southern Ontario see Dinnage (2009) for details. Sites each had two plots which experienced a different treatment each; either they has been disturbed (ploughed 1 or 2 years previously), or they were a control plot (undisturbed in recent records).

Usage

oldfield

Format

A list with two elements:

phy

A phylogeny in ape's phy format

data

A data.frame containing data on the occurrence of the species in phy

oldfield$data is a data.frame with 1786 rows, and the following 7 columns:

site_orig

integer. Site ID number.

habitat_type

character. Plot treatment: disturbed or undisturbed.

sp

character. Species name using underscore to separate binomial names (to match phylogeny).

abundance

integer. Recorded abundance of species in plot.

disturbance

integer. Whether the plot was disturbed or not. 0 or 1. 0 for undisturbed, 1 for disturbed

site_orig

character. A unique site descriptor concatenating the site number with the disturbance treatment.

pres

integer. Species presence or absence in plot. 0 or 1. 0 for absent, 1 for present


pairwise site phylogenetic community dissimilarity (PCD) within a community

Description

Calculate pairwise site PCD, users can specify expected values from pcd_pred().

Usage

pcd(comm, tree, expectation = NULL, cpp = TRUE, verbose = TRUE, ...)

Arguments

comm

A site by species data frame or matrix, sites as rows.

tree

A phylogeny for species.

expectation

nsp_pool, psv_bar, psv_pool, and nsr calculated from pcd_pred().

cpp

Whether to use loops written with c++, default is TRUE.

verbose

Do you want to see the progress?

...

Other arguments.

Value

A list of a variety of pairwise dissimilarities.

References

Ives, A. R., & Helmus, M. R. 2010. Phylogenetic metrics of community similarity. The American Naturalist, 176(5), E128-E142.

Examples

x1 = pcd_pred(comm_1 = comm_a, comm_2 = comm_b, tree = phylotree, reps = 100)
pcd(comm = comm_a, tree = phylotree, expectation = x1)

Predicted PCD with species pool

Description

This function will calculate expected PCD from one or two sets of communities (depends on the species pool)

Usage

pcd_pred(comm_1, comm_2 = NULL, tree, reps = 10^3, cpp = TRUE)

Arguments

comm_1

A site by species dataframe or matrix, with sites as rows and species as columns.

comm_2

An optional second site by species data frame. It should have the same number of rows as comm_1. This can be useful if we want to calculate temporal beta diversity, i.e. changes of the same site over time. Because data of the same site are not independent, setting comm_2 will use both communities as species pool to calculate expected PCD.

tree

The phylogeny for all species, with "phylo" as class; or a var-cov matrix.

reps

Number of random draws, default is 1000 times.

cpp

Whether to use loops written with c++, default is TRUE. If you came across with errors, try to set cpp = FALSE. This normally will run without errors, but slower.

Value

A list with species richness of the pool, expected PSV, PSV of the pool, and unique number of species richness across sites.


Phylogenetic Generalized Linear Mixed Model for Community Data

Description

This function performs Generalized Linear Mixed Models for binary, count, and continuous data, estimating regression coefficients with approximate standard errors. It is specifically designed for community data in which species occur within multiple sites (locations). A Bayesian version of PGLMM uses the package INLA, which is not available on CRAN yet. If you wish to use this option, you must first install INLA from https://www.r-inla.org/ by running install.packages('INLA', repos='https://www.math.ntnu.no/inla/R/stable') in R.

Usage

pglmm(
  formula,
  data = NULL,
  family = "gaussian",
  cov_ranef = NULL,
  random.effects = NULL,
  REML = TRUE,
  optimizer = NULL,
  repulsion = FALSE,
  add.obs.re = TRUE,
  verbose = FALSE,
  cpp = TRUE,
  bayes = FALSE,
  s2.init = NULL,
  B.init = NULL,
  reltol = 10^-6,
  maxit = 500,
  tol.pql = 10^-6,
  maxit.pql = 200,
  marginal.summ = "mean",
  calc.DIC = TRUE,
  calc.WAIC = TRUE,
  prior = "inla.default",
  prior_alpha = 0.1,
  prior_mu = 1,
  ML.init = FALSE,
  tree = NULL,
  tree_site = NULL,
  sp = NULL,
  site = NULL,
  bayes_options = NULL,
  bayes_nested_matrix_as_list = FALSE,
  posterior.sample = TRUE,
  return.fitted.marginals = TRUE,
  sparse = FALSE,
  standardize_cov = TRUE,
  method = c("PQL", "Laplace")
)

communityPGLMM(
  formula,
  data = NULL,
  family = "gaussian",
  cov_ranef = NULL,
  random.effects = NULL,
  REML = TRUE,
  optimizer = NULL,
  repulsion = FALSE,
  add.obs.re = TRUE,
  verbose = FALSE,
  cpp = TRUE,
  bayes = FALSE,
  s2.init = NULL,
  B.init = NULL,
  reltol = 10^-6,
  maxit = 500,
  tol.pql = 10^-6,
  maxit.pql = 200,
  marginal.summ = "mean",
  calc.DIC = TRUE,
  calc.WAIC = TRUE,
  prior = "inla.default",
  prior_alpha = 0.1,
  prior_mu = 1,
  ML.init = FALSE,
  tree = NULL,
  tree_site = NULL,
  sp = NULL,
  site = NULL,
  bayes_options = NULL,
  bayes_nested_matrix_as_list = FALSE,
  posterior.sample = TRUE,
  return.fitted.marginals = TRUE,
  sparse = FALSE,
  standardize_cov = TRUE,
  method = c("PQL", "Laplace")
)

Arguments

formula

A two-sided linear formula object describing the mixed effects of the model.

To specify that a random term should have phylogenetic covariance matrix along with non-phylogenetic one, add __ (two underscores) at the end of the group variable; e.g., + (1 | sp__) will construct two random terms, one with phylogenetic covariance matrix and another with non-phylogenetic (identity) matrix. In contrast, __ in the nested terms (below) will only create a phylogenetic covariance matrix. Nested random terms have the general form (1|sp__@site__) which represents phylogenetically related species nested within correlated sites. This form can be used for bipartite questions. For example, species could be phylogenetically related pollinators and sites could be phylogenetically related plants, leading to the random effect (1|insects__@plants__). If more than one phylogeny is used, remember to add all to the argument cov_ranef = list(insects = insect_phylo, plants = plant_phylo). Phylogenetic correlations can be dropped by removing the __ underscores. Thus, the form (1|sp@site__) excludes the phylogenetic correlations among species, while the form (1|sp__@site) excludes the correlations among sites.

Note that correlated random terms are not allowed. For example, (x|g) will be the same as (0 + x|g) in the lme4::lmer syntax. However, (x1 + x2|g) won't work, so instead use (x1|g) + (x2|g).

data

A data.frame containing the variables named in formula. Rows where the response variable is NA are dropped before fitting; this is equivalent to removing those rows from data manually before calling pglmm. As a result, pglmm(data_with_NAs) and pglmm(data[!is.na(data$y), ]) produce identical estimates.

family

Either "gaussian" for a Linear Mixed Model, or "binomial" or "poisson" for Generalized Linear Mixed Models. "family" should be specified as a character string (i.e., quoted). For binomial and Poisson data, we use the canonical logit and log link functions, respectively. Binomial data can be either presence/absence, or a two-column array of 'successes' and 'failures'. For both binomial and Poisson data, we add an observation-level random term by default via add.obs.re = TRUE. If bayes = TRUE there are two additional families available: "zeroinflated.binomial", and "zeroinflated.poisson", which add a zero inflation parameter; this parameter gives the probability that the response is a zero. The rest of the parameters of the model then reflect the "non-zero" part part of the model. Note that "zeroinflated.binomial" only makes sense for success/failure response data.

cov_ranef

A named list of covariance matrices of random terms. The names should be the group variables that are used as random terms with specified covariance matrices (without the two underscores, e.g. list(sp = tree1, site = tree2)). The actual object can be either a phylogeny with class "phylo" or a prepared covariance matrix. If it is a phylogeny, pglmm will prune it and then convert it to a covariance matrix assuming Brownian motion evolution. pglmm will also standardize all covariance matrices to have determinant of one (unless standardize_cov = FALSE), so the estimated variances of these terms are on the scale of the standardized matrices; use scale_factors of the fitted model to rescale them (see "Extracting the variances of random terms" in Details). Group variables will be converted to factors and all covariance matrices will be rearranged so that rows and columns are in the same order as the levels of their corresponding group variables.

random.effects

Optional pre-build list of random effects. If NULL (the default), the function prep_dat_pglmm will prepare the random effects for you from the information in formula, data, and cov_ranef. random.effect allows a list of pre-generated random effects terms to increase flexibility; for example, this makes it possible to construct models with both phylogenetic correlation and spatio-temporal autocorrelation. In preparing random.effect, make sure that the orders of rows and columns of covariance matrices in the list are the same as their corresponding group variables in the data. Also, this should be a list of lists, e.g. random.effects = list(re1 = list(matrix_a), re2 = list(1, sp = sp, covar = Vsp)).

REML

Whether REML or ML is used for model fitting the random effects. Ignored if bayes = TRUE. For binomial and poisson models with method = "Laplace", REML = TRUE integrates the fixed effects out of the likelihood with the Laplace approximation too (as glmmTMB(REML = TRUE)); use REML = FALSE for maximum likelihood estimates, comparable with lme4::glmer() and glmmTMB().

optimizer

Optimizer to use. Options: "lbfgs" (L-BFGS with analytic gradient; default for Gaussian, also available for binomial/Poisson), "nelder-mead-nlopt" (default for binomial/Poisson), "bobyqa", "Nelder-Mead", or "subplex". "Nelder-Mead" is from the stats package; all others are from the nloptr package. With sparse = TRUE, the default (and "lbfgs", as there is no gradient) is "subplex", "nelder-mead-nlopt" and "Nelder-Mead" both use the Nelder-Mead algorithm of nloptr, and the optimizer is restarted from its solution until the likelihood does not improve (for gaussian models; for binomial and poisson models, each PQL iteration already starts the optimizer from the previous solution). Ignored if bayes = TRUE or method = "Laplace".

repulsion

When there are nested random terms specified, repulsion = FALSE tests for phylogenetic underdispersion while repulsion = TRUE tests for overdispersion. This argument is a logical vector of length either 1 or >1. If its length is 1, it applies to the phylogenies of species only (the variable before @, e.g. sp in sp__@site and sp__@site__): their covariance matrices are either inverted (overdispersion) or not, while the phylogenies of sites (after @) are never inverted. This follows Ives and Helmus (2011, Appendix A), where repulsion arises from competition among closely related species. If it has more than one element, then you can select which covariance matrix in the nested terms to be inverted. Make sure to get the length right: for all the terms with @, count the number of "__" to determine the length of repulsion. For example, sp__@site and sp@site__ will each require one element of repulsion, while sp__@site__ will take two elements (repulsion for sp and repulsion for site). Therefore, if your nested terms are (1|sp__@site) + (1|sp@site__) + (1|sp__@site__), then you should set the repulsion to be something like c(TRUE, FALSE, TRUE, TRUE) (length of 4).

add.obs.re

Whether to add an observation-level random term for binomial or Poisson distributions. Normally it would be a good idea to add this to account for overdispersion, so add.obs.re = TRUE by default.

verbose

If TRUE, the model deviance and running estimates of s2 and B are plotted each iteration during optimization.

cpp

Whether to use C++ function for optim. Default is TRUE. Ignored if bayes = TRUE.

bayes

Whether to fit a Bayesian version of the PGLMM using r-inla.

s2.init

An array of initial estimates of s2 for each random effect that scales the variance. If s2.init is not provided for family="gaussian", these are estimated using lm assuming no phylogenetic signal. A better approach might be to run link[lme4:lmer]{lmer} and use the output random effects for s2.init. If s2.init is not provided for family = "binomial", these are set to 0.25. For family = "gaussian" and bayes = FALSE, the model is parameterized with the variances of random terms relative to the residual variance (see ss in the Value section), and s2.init gives the starting values of these ratios.

B.init

Initial estimates of BB, a matrix containing regression coefficients in the model for the fixed effects. This matrix must have dim(B.init) = c(p + 1, 1), where p is the number of predictor (independent) variables; the first element of B corresponds to the intercept, and the remaining elements correspond in order to the predictor (independent) variables in the formula. If B.init is not provided, these are estimated using lm or glm assuming no phylogenetic signal. A better approach might be to run lmer and use the output fixed effects for B.init. When bayes = TRUE, initial values are estimated using the maximum likelihood fit unless ML.init = FALSE, in which case the default INLA initial values will be used.

reltol

A control parameter dictating the relative tolerance for convergence in the optimization; see optim. With sparse = TRUE, the default is 1e-8 (for each run of the optimizer, including each PQL iteration of binomial and poisson models). With method = "Laplace", the relative tolerance of nlminb() (default 1e-10); maxit is then its maximum number of iterations and evaluations.

maxit

A control parameter dictating the maximum number of iterations in the optimization; see optim.

tol.pql

A control parameter dictating the tolerance for convergence in the PQL estimates of the mean components of the GLMM. Ignored if family = "gaussian", bayes = TRUE, or method = "Laplace".

maxit.pql

A control parameter dictating the maximum number of iterations in the PQL estimates of the mean components of the GLMM. Ignored if family = "gaussian" or bayes = TRUE.

marginal.summ

Summary statistic to use for the estimate of coefficients when doing a Bayesian PGLMM (when bayes = TRUE). Options are: "mean", "median", or "mode", referring to different characterizations of the central tendency of the Bayesian posterior marginal distributions. Ignored if bayes = FALSE.

calc.DIC

Should the Deviance Information Criterion be calculated and returned when doing a Bayesian PGLMM? Ignored if bayes = FALSE.

calc.WAIC

Should the WAIC be calculated and returned when doing a Bayesian PGLMM? Ignored if bayes = FALSE.

prior

Which type of default prior should be used by pglmm? Only used if bayes = TRUE. There are currently four options: "inla.default", which uses the default INLA priors; "pc.prior.auto", which uses a complexity penalizing prior (as described in Simpson et al. (2017)) designed to automatically choose good parameters (only available for gaussian and binomial responses); "pc.prior", which allows the user to set custom parameters on the "pc.prior" prior, using the prior_alpha and prior_mu parameters (Run INLA::inla.doc("pc.prec") for details on these parameters); and "uninformative", which sets a very uninformative prior (nearly uniform) by using a very flat exponential distribution. The last option is generally not recommended but may in some cases give estimates closer to the maximum likelihood estimates. "pc.prior.auto" is only implemented for family = "gaussian" and family = "binomial" currently.

prior_alpha

Only used if bayes = TRUE and prior = "pc.prior", in which case it sets the alpha parameter of INLA's complexity penalizing prior for the random effects. The prior is an exponential distribution where prob(sd > mu) = alpha, where sd is the standard deviation of the random effect.

prior_mu

Only used if bayes = TRUE and prior = "pc.prior", in which case it sets the mu parameter of INLA's complexity penalizing prior for the random effects. The prior is an exponential distribution where prob(sd > mu) = alpha, where sd is the standard deviation of the random effect.

ML.init

Only relevant if bayes = TRUE. Should maximum likelihood estimates be calculated and used as initial values for the Bayesian model fit? Sometimes this can be helpful, but it may not help; thus, we set the default to FALSE. Also, it does not work with the zero-inflated families.

tree

A phylogeny for column sp, with "phylo" class, or a covariance matrix for sp. Make sure to have all species in the matrix; if the matrix is not standardized, (i.e., det(tree) != 1), pglmm will try to standardize it for you. No longer used: keep here for compatibility.

tree_site

A second phylogeny for "site". This is required only if the site column contains species instead of sites. This can be used for bipartitie questions; tree_site can also be a covariance matrix. Make sure to have all sites in the matrix; if the matrix is not standardized (i.e., det(tree_site) != 1), pglmm' will try to standardize it for you. No longer used: keep here for compatibility.

sp

No longer used: keep here for compatibility.

site

No longer used: keep here for compatibility.

bayes_options

Additional options to pass to INLA when bayes = TRUE. A named list where the names correspond to parameters in the inla function. One special option is diagonal: if an element in the list is named diagonal, INLA adds its value to the diagonal of every random-effects precision matrix, which can help with numerical stability when the model is ill-conditioned (try list(diagonal = 1e-4) if you see many warnings). To use multiple CPU cores, pass list(num.threads = 4) (or however many cores are available); this is often the single most effective way to speed up INLA. Any control.compute entries supplied here override the defaults set by posterior.sample and return.fitted.marginals.

bayes_nested_matrix_as_list

For bayes = TRUE, prepare the nested terms as a list of length 4 as the old way?

posterior.sample

Logical (default TRUE). Only used when bayes = TRUE. When TRUE, INLA stores the full joint posterior configuration (control.compute = list(config = TRUE)), which is required for simulate to work. Set to FALSE to skip this storage and speed up fitting when posterior simulation is not needed.

return.fitted.marginals

Logical (default TRUE). Only used when bayes = TRUE. When TRUE, INLA computes and returns the marginal posterior distributions of all fitted values (control.compute = list(return.marginals.predictor = TRUE)), which is required for simulate with full = FALSE. Set to FALSE to skip this computation and speed up fitting when simulation is not needed. If both posterior.sample and return.fitted.marginals are FALSE, INLA runs at maximum speed but simulate() will not work on the fitted model.

sparse

Logical (default FALSE). If TRUE, fit the model with the sparse precision matrix of the phylogeny (which includes its internal nodes) and a sparse Cholesky decomposition, instead of the dense phylogenetic covariance matrix. This gives the same likelihood, but the time and memory needed grow about linearly with the number of species, so that models with thousands of species can be fitted. Nested terms (e.g. (1 | sp__@site), (1 | sp@site__), (1 | sp__@site__), (1 | sp@site)) use the precision matrix of the Kronecker product of the two covariance matrices; their time grows about linearly with the number of species and somewhat faster than linearly with the number of sites. With repulsion = TRUE, the precision matrix of the phylogeny becomes its (dense) covariance matrix, which is written with the internal nodes as auxiliary variables, and a sparse LDL′LDL' decomposition of a larger (indefinite) matrix is used instead. Binomial and poisson models are fitted with the same penalized quasi-likelihood (PQL) iterations as with sparse = FALSE (same updates and convergence rules, tol.pql and maxit.pql); at each iteration, the working weights change only the values of the sparse matrix, and the observation-level term 1|obs is folded into the weights. Only available with bayes = FALSE, and phylogenies (class phylo) in cov_ranef. The default optimizer is then "subplex" (see optimizer), with reltol = 1e-8.

The sparse precision matrix exists because the trait evolves along the branches as a Markov process (the value at a node depends only on its parent). This is not limited to Brownian motion: any model that is Brownian motion on a tree with transformed branch lengths can be used by passing the transformed phylogeny in cov_ranef, e.g. an Ornstein-Uhlenbeck (OU) model with a fixed α\alpha (phylolm::transf.branch.lengths(tree, model = "OUfixedRoot", parameters = list(alpha = a))$tree or geiger::rescale(tree, "OU", alpha = a)), Pagel's λ\lambda, κ\kappa, or δ\delta, or early burst. As with sparse = FALSE, the parameters of these models (e.g. α\alpha) are not estimated by pglmm(); they can be chosen by fitting the model over a grid of values and comparing the log-likelihoods, which is fast with sparse = TRUE. With standardize_cov = TRUE, the overall scale of the transformed tree (e.g. σ2\sigma^2 of the OU model) has no effect. The OU transformation is exact for ultrametric trees; for non-ultrametric trees, check that it matches the assumption about the root. Covariance matrices that cannot be written as a tree with non-negative branch lengths (e.g. an arbitrary similarity matrix) need sparse = FALSE.

standardize_cov

Logical (default TRUE). Whether to standardize the covariance matrices of cov_ranef to have a determinant of one (a phylogeny is first converted to its covariance matrix, which is divided by its largest element). If FALSE, the matrices are used as given: a covariance matrix is used as it is, and a phylogeny gives ape::vcv(tree), on the scale of its branch lengths. The variances of the random terms (s2r, s2n) are then on the scale of these matrices, so that, e.g., the variance of 1|sp__ with a phylogenetic correlation matrix (ape::vcv(tree, corr = TRUE)) or an ultrametric tree with a height of one is directly comparable with the variance of 1|sp and with software that does not standardize the matrices. The likelihood, the fixed effects and the predictions do not depend on this choice; only the scale of the variances (and of s2.init) does. Not used when random.effects is given.

method

For binomial and poisson models with bayes = FALSE, the approximation of the likelihood: "PQL" (default) for penalized quasi-likelihood, as in earlier versions, or "Laplace" for the Laplace approximation of the marginal likelihood, as in lme4::glmer() (with nAGQ = 1) and glmmTMB. PQL is known to underestimate the variances of random terms, and to shrink the fixed effects towards zero, for binary data and counts with small means; the Laplace approximation is much less biased, and its log-likelihood approximates the marginal likelihood of the model, so that it can be used for likelihood ratio tests (pglmm_profile_LRT()) and AIC (the log-likelihood of PQL is that of a gaussian model of the working response). Ignored for gaussian models (their likelihood is exact) and with bayes = TRUE.

With "Laplace", the model is always fitted with the precision matrices used by sparse = TRUE, whatever the value of sparse: a phylogeny gives the sparse precision matrix of all its nodes, and a covariance matrix in cov_ranef its (dense) inverse. The time to fit a model thus grows about linearly with the number of species, and nested terms and repulsion are supported. The random terms must be given in the formula (random.effects is not supported). The mode of the random effects (including the observation-level term 1|obs) is found by Newton iterations. The variances of the random terms are estimated first with the fixed effects at the mode (as glmer(nAGQ = 0)); this is the final fit with REML = TRUE, where the fixed effects are integrated out (as glmmTMB(REML = TRUE)) and their covariance matrix is conditional on the variances. With REML = FALSE, the fixed effects and the variances are then estimated jointly (as glmer(nAGQ = 1) and glmmTMB), and the covariance matrix of the fixed effects is from the inverse of the (numerical) Hessian of the log-likelihood over the fixed effects and the standard deviations of the random terms, as in these packages. The optimizer is nlminb(), on the scale of the variances (with a lower bound of zero), with gradients by finite differences; optimizer, tol.pql and maxit.pql are not used. ranef() gives the conditional modes of the random effects, and condVar = TRUE their conditional standard deviations from the Hessian of the Laplace approximation (conditional on the estimates of the parameters). pglmm_iV() is not available for these models.

Choosing between them:

  • "PQL" (default): fastest (about 3–4 times faster than "Laplace"), supports every model of pglmm() (including random.effects and pglmm_iV()), and gives the same estimates as earlier versions of phyr. But its estimates are biased for binary data: compared with "Laplace" (and glmer()/glmmTMB), the fixed effects were about 5–10% closer to zero and the variances of random terms about 10–30% smaller in our comparisons. For counts, the differences were small (variances a few percent smaller). Its log-likelihood is not that of the model, so AIC and likelihood ratio tests (including tests for phylogenetic signal with pglmm_profile_LRT()) are only rough approximations.

  • "Laplace": gives the same estimates and log-likelihood as lme4::glmer() and glmmTMB (to optimizer tolerance), much less biased estimates (about unbiased fixed effects with REML = FALSE, and the least biased phylogenetic variance with REML = TRUE), and a log-likelihood that can be used for AIC and likelihood ratio tests. Still much faster than glmmTMB for large phylogenies (e.g. 1 s versus about 60 s for 2000 species). Use it when the variances of random terms, tests of phylogenetic signal, or model comparisons matter, especially for binary data. It is an approximation too: for binary data with few observations per species, the variances (especially the phylogenetic one) remain underestimated with REML = FALSE, as with any maximum likelihood fit; REML = TRUE reduces this bias.

Details

For Gaussian data, pglmm analyzes the phylogenetic linear mixed model

Y=β0+β1x+b0+b1xY = \beta_0 + \beta_1x + b_0 + b_1x

b0 Gaussian(0,σ02Isp)b_0 ~ Gaussian(0, \sigma_0^2I_{sp})

b1 Gaussian(0,σ02Vsp)b_1 ~ Gaussian(0, \sigma_0^2V_{sp})

η Gaussian(0,σ2)\eta ~ Gaussian(0,\sigma^2)

where β0\beta_0 and β1\beta_1 are fixed effects, and VspV_{sp} is a variance-covariance matrix derived from a phylogeny (typically under the assumption of Brownian motion evolution). Here, the variation in the mean (intercept) for each species is given by the random effect b0b_0 that is assumed to be independent among species. Variation in species' responses to predictor variable xx is given by a random effect b0b_0 that is assumed to depend on the phylogenetic relatedness among species given by VspV_{sp}; if species are closely related, their specific responses to xx will be similar. This particular model would be specified as

z <- pglmm(Y ~ X + (1|sp__), data = data, family = "gaussian", cov_ranef = list(sp = phy))

Or you can prepare the random terms manually (not recommended for simple models but may be necessary for complex models):

re.1 <- list(1, sp = dat$sp, covar = diag(nspp))

re.2 <- list(dat$X, sp = dat$sp, covar = Vsp)

z <- pglmm(Y ~ X, data = data, family = "gaussian", random.effects = list(re.1, re.2))

By default (standardize_cov = TRUE), the covariance matrix VV is standardized to have determinant equal to 1 before fitting. Specifically, for an n×nn \times n covariance matrix VV, pglmm uses Vstd=V/det⁡(V)1/nV_{\rm std} = V / \det(V)^{1/n}, which has det⁡(Vstd)=1\det(V_{\rm std}) = 1. This ensures that the variance parameter σ2\sigma^2 has a consistent scale regardless of the absolute magnitude of VV.

Extracting the variances of random terms. Two things are easy to get wrong when the estimated variances are reported, or compared with those of other software (e.g. glmmTMB, MCMCglmm, brms) or with the values used to simulate data:

  1. Use s2r, s2n and s2resid (or VarCorr()), not ss^2. For gaussian models fitted with bayes = FALSE, ss holds the standard deviations of the random terms relative to the residual standard deviation (s2r = s2resid * ss^2), so ss^2 is not a variance; it is too large by a factor of 1 / s2resid (see ss in Value).

  2. The variance of a term with a covariance matrix is on the scale of the standardized matrix. The model is fitted as σ2Vstd\sigma^2 V_{\rm std}, so s2r and s2n are relative to VstdV_{\rm std}, not to the matrix (or phylogeny) given in cov_ranef. Standardizing a phylogenetic correlation matrix (diagonal of 1) to a determinant of one inflates its diagonal (often several-fold, more with more species), whereas the identity matrix of a non-phylogenetic term such as 1|sp is unchanged. As a result, the s2r of 1|sp and 1|sp__ are not on the same scale, and the s2r of 1|sp__ is much smaller than the phylogenetic variance on the scale of the correlation matrix. To put a term on the scale of an average level (for a correlation matrix or an ultrametric tree, the scale of the original matrix), multiply it by the mean diagonal of the standardized matrix:

    σobs2=σstd2×diag‾(Vstd)\sigma^2_{\rm obs} = \sigma^2_{\rm std} \times \overline{\rm diag}(V_{\rm std})

    The fitted model returns these factors as scale_factors (1 for terms without a covariance matrix and for the residual): fit$s2r * fit$scale_factors[names(fit$s2r)] and fit$s2n * fit$scale_factors[names(fit$s2n)]. Do this before comparing the variances of different terms (e.g. to calculate the proportion of the variance among species that is phylogenetic) or comparing them with other software. Alternatively, fit the model with standardize_cov = FALSE, so that the variances are on the scale of the matrices as given (with a phylogeny, on the scale of its branch lengths).

The estimates of fixed effects, the likelihood, and the group-level estimates of ranef() do not depend on the standardization.

Although mathematically this is not required, it is a very good idea to standardize the predictor (independent) variables to have mean 0 and variance 1. This will make the function more robust and improve the interpretation of the regression coefficients. For categorical (factor) predictor variables, you will need to construct 0-1 dummy variables, and these should not be standardized (for obvious reasons).

For binary generalized linear mixed models (family = 'binomial'), the function estimates parameters for the model of the form, for example,

y=β0+β1x+b0+b1xy = \beta_0 + \beta_1x + b_0 + b_1x

Y=logit−1(y)Y = logit^{-1}(y)

b0 Gaussian(0,σ02Isp)b_0 ~ Gaussian(0, \sigma_0^2I_{sp})

b1 Gaussian(0,σ02Vsp)b_1 ~ Gaussian(0, \sigma_0^2V_{sp})

where β0\beta_0 and β1\beta_1 are fixed effects, and VspV_{sp} is a variance-covariance matrix derived from a phylogeny (typically under the assumption of Brownian motion evolution).

z <- pglmm(Y ~ X + (1|sp__), data = data, family = "binomial", cov_ranef = list(sp = phy))

As with the linear mixed model, it is a very good idea to standardize the predictor (independent) variables to have mean 0 and variance 1. This will make the function more robust and improve the interpretation of the regression coefficients.

Value

An object (list) of class communityPGLMM with the following elements:

formula

the formula for fixed effects

formula_original

the formula for both fixed effects and random effects

data

the dataset

family

gaussian, binomial, or poisson depending on the model fit

random.effects

the list of random effects

B

estimates of the regression coefficients

B.se

approximate standard errors of the fixed effects regression coefficients. This is set to NULL if bayes = TRUE.

B.ci

approximate Bayesian credible interval of the fixed effects regression coefficients. This is set to NULL if bayes = FALSE

B.cov

approximate covariance matrix for the fixed effects regression coefficients

B.zscore

approximate Z scores for the fixed effects regression coefficients. This is set to NULL if bayes = TRUE

B.pvalue

approximate tests for the fixed effects regression coefficients being different from zero. This is set to NULL if bayes = TRUE

ss

the parameters that are optimized when fitting the model, one for each random term (non-nested terms first, then nested terms). Their meaning depends on the model:

  • For gaussian models with bayes = FALSE, they are the standard deviations of the random terms relative to the residual standard deviation, i.e. σi/σresid\sigma_i / \sigma_{resid}; the residual standard deviation itself is listed last. The residual variance is profiled out of the likelihood, so only these ratios are optimized (this is the same parameterization as theta of lme4 for a term such as (1 | g)). The variances are s2r = s2resid * ss^2 and s2n = s2resid * ss^2 for the corresponding elements.

  • For binomial and poisson models with bayes = FALSE, and for all models with bayes = TRUE, they are the standard deviations σi\sigma_i of the random terms themselves (ss^2 equals s2r and s2n); for gaussian models with bayes = TRUE the residual standard deviation is listed last.

In all cases, the covariance contribution of the ith term is σi2Vi,std\sigma_i^2 V_{i,\rm std}, where Vi,stdV_{i,\rm std} is the det=1 standardized covariance matrix (see Details), so these are not standard deviations on the original covariance scale. For variance inference use s2r, s2n, or s2resid (or VarCorr()); do not use ss^2 as a variance estimate for gaussian models.

s2r

variance parameters σi2\sigma_i^2 for non-nested random effects, relative to the det=1 standardized covariance matrices (see Details). These are the recommended output for variance inference. To obtain the effective per-observation variance on a scale comparable across all random effects (including non-phylogenetic terms), multiply by scale_factors: s2r * scale_factors[names(s2r)].

s2n

variance parameters for nested random effects; same scale as s2r. Use s2n * scale_factors[names(s2n)] for the comparable per-observation variance.

s2resid

for linear mixed models, the residual variance. The residual always uses an identity covariance matrix (scale_factor = 1), so s2resid is directly interpretable without any rescaling.

scale_factors

named numeric vector with one entry per random effect term. Each value is mean(diag(V_std)), the mean diagonal of the det=1 standardized covariance matrix for that term (averaged over its levels, not over observations); with standardize_cov = FALSE, the mean diagonal of the matrix as given. For identity-based (non-phylogenetic) terms this equals 1, meaning s2r is already on an interpretable scale. For a phylogenetic term from an ultrametric tree or a correlation matrix, this equals 1/det⁡(Vorig)1/n1 / \det(V_{\rm orig})^{1/n} and is typically much larger than 1. Multiplying s2r[i] * scale_factors[i] gives the variance of the ith random effect for an average level, comparable across all terms in the model and with software that does not standardize the covariance matrices (see Details).

s2r.ci

Bayesian credible interval for random effects variances for non-nested random effects. This is set to NULL if bayes = FALSE

s2n.ci

Bayesian credible interval for random effects variances for nested random effects. This is set to NULL if bayes = FALSE

s2resid.ci

Bayesian credible interval for linear mixed models, the residual variance. This is set to NULL if bayes = FALSE

logLik

the log-likelihood, restricted (REML = TRUE) or not (REML = FALSE). For binomial and poisson models fitted with method = "PQL", it is an approximation from the gaussian model of the working response; with method = "Laplace", it is the Laplace approximation of the (restricted) marginal log-likelihood, the same as that of glmer() and glmmTMB(). If bayes = TRUE, this is the marginal log-likelihood of INLA

AIC

the AIC calculated with logLik (bayes = FALSE)

BIC

the BIC calculated with logLik (bayes = FALSE)

method

for binomial and poisson models with bayes = FALSE, the approximation of the likelihood, "PQL" or "Laplace" (see the argument method)

DIC

for Bayesian PGLMM, this is the Deviance Information Criterion metric of model fit. This is set to NULL if bayes = FALSE.

REML

whether or not REML is used (TRUE or FALSE).

bayes

whether or not a Bayesian model was fit.

standardize_cov

the value of the argument standardize_cov.

marginal.summ

The specified summary statistic used to summarize the Bayesian marginal distributions. Only present if bayes = TRUE

s2.init

the user-provided initial estimates of s2

B.init

the user-provided initial estimates of B

Y

the response (dependent) variable returned in matrix form

size

the number of trials of each observation for binomial models (it is one for binary data, and for poisson models). This is NULL for gaussian models, and for models with bayes = TRUE unless the response is specified with the numbers of successes and failures.

X

the predictor (independent) variables returned in matrix form (including 1s in the first column)

H

the residuals. For linear mixed models, this does not account for random terms, i.e. it is similar to Y - predict(merMod, re.form = NA) for models fitted with lme4. To get residuals after accounting for both fixed and random terms, use residuals(). For the generalized linear mixed model, these are the predicted residuals in the logit -1 space.

mu

predicted mean values for the generalized linear mixed model (i.e., similar to fitted(merMod)). Set to NULL for linear mixed models, for which we can use fitted().

nested

matrices used to construct the nested design matrix. This is set to NULL if bayes = TRUE

Zt

the design matrix for random effects. This is set to NULL if bayes = TRUE

St

diagonal matrix that maps the random effects variances onto the design matrix

convcode

the convergence code provided by optim. This is set to NULL if bayes = TRUE

niter

number of iterations performed by optim. This is set to NULL if bayes = TRUE

inla.model

Model object fit by underlying inla function. Only returned if bayes = TRUE

Speed

Models with bayes = FALSE spend most of their time in linear algebra (BLAS and LAPACK), so the BLAS library that R uses matters a lot for large data sets. The reference BLAS that R uses by default on some systems is much slower than optimized ones. On a Mac, R comes with a version that uses Apple's Accelerate; R can be switched to it by running, in a terminal, ⁠ln -sf libRblas.vecLib.dylib libRblas.dylib⁠ in the folder given by R.home("lib"), and restarting R (see the section about BLAS in the manual 'R Installation and Administration'). pglmm() shows a message once per session when a model with at least 1000 observations is fitted on a Mac with the reference BLAS; use options(phyr.blas.hint = FALSE) to turn it off. extSoftVersion()["BLAS"] shows the BLAS library that R uses.

Comparative data

A phylogenetic term such as (1 | sp__) also adds the non-phylogenetic term (1 | sp). With comparative data (one row per species), that term is confounded with the residual variance (or with the observation-level term 1|obs); use pglmm_compare(), which fits the model with the phylogenetic term only. pglmm() shows a message once per session when each level of the grouping variable of a (non-nested) phylogenetic term has only one row; use options(phyr.compare.hint = FALSE) to turn it off.

Author(s)

Anthony R. Ives, Daijiang Li, Russell Dinnage

References

Ives, A. R. and M. R. Helmus. 2011. Generalized linear mixed models for phylogenetic analyses of community structure. Ecological Monographs 81:511-525.

Ives A. R. 2018. Mixed and phylogenetic models: a conceptual introduction to correlated data. https://leanpub.com/correlateddata.

Rafferty, N. E., and A. R. Ives. 2013. Phylogenetic trait-based analyses of ecological networks. Ecology 94:2321-2333.

Simpson, Daniel, et al. 2017. Penalising model component complexity: A principled, practical approach to constructing priors. Statistical science 32(1): 1-28.

Li, D., Ives, A. R., & Waller, D. M. 2017. Can functional traits account for phylogenetic signal in community composition? New Phytologist, 214(2), 607-618.

Examples

## Structure of examples:
# First, a (brief) description of model types, and how they are specified
# - these are *not* to be run 'as-is'; they show how models should be organised
# Second, a run-through of how to simulate, and then analyse, data
# - these *are* to be run 'as-is'; they show how to format and work with data


#############################################
### Brief summary of models and their use ###
#############################################
## Model structures from Ives & Helmus (2011)
if (FALSE) {
  # dat = data set for regression (note: must have a column "sp" and a column "site")
  # phy = phylogeny of class "phylo"
  # repulsion = to test phylogenetic repulsion or not

  # Model 1 (Eq. 1)
  z <- pglmm(freq ~ sp + (1 | site) + (1 | sp__@site),
    data = dat, family = "binomial",
    cov_ranef = list(sp = phy), REML = TRUE, verbose = TRUE, s2.init = .1
  )

  # Model 2 (Eq. 2)
  z <- pglmm(freq ~ sp + X + (1 | site) + (X | sp__),
    data = dat, family = "binomial",
    cov_ranef = list(sp = phy), REML = TRUE, verbose = TRUE, s2.init = .1
  )

  # Model 3 (Eq. 3)
  z <- pglmm(freq ~ sp * X + (1 | site) + (1 | sp__@site),
    data = dat, family = "binomial",
    cov_ranef = list(sp = phy), REML = TRUE, verbose = TRUE, s2.init = .1
  )

  ## Model structure from Rafferty & Ives (2013) (Eq. 3)
  # dat = data set
  # phyPol = phylogeny for pollinators (pol)
  # phyPlt = phylogeny for plants (plt)

  z <- pglmm(
    freq ~ pol * X + (1 | pol__) + (1 | plt__) + (1 | pol__@plt) +
      (1 | pol@plt__) + (1 | pol__@plt__),
    data = dat, family = "binomial",
    cov_ranef = list(pol = phyPol, plt = phyPlt),
    REML = TRUE, verbose = TRUE, s2.init = .1
  )
}

#####################################################
### Detailed analysis showing covariance matrices ###
#####################################################

# This is the example from section 4.3 in Ives, A. R. (2018) Mixed
# and phylogenetic models: a conceptual introduction to correlated data.

library(ape)
library(mvtnorm)

# Investigating covariance matrices for different types of model structure
nspp <- 6
nsite <- 4

# Simulate a phylogeny that has a lot of phylogenetic signal (power = 1.3)
phy <- compute.brlen(rtree(n = nspp), method = "Grafen", power = 1.3)

# Simulate species means
sd.sp <- 1
mean.sp <- rTraitCont(phy, model = "BM", sigma = sd.sp^2)

# Replicate values of mean.sp over sites
Y.sp <- rep(mean.sp, times = nsite)

# Simulate site means
sd.site <- 1
mean.site <- rnorm(nsite, sd = sd.site)

# Replicate values of mean.site over sp
Y.site <- rep(mean.site, each = nspp)

# Compute a covariance matrix for phylogenetic attraction
sd.attract <- 1
Vphy <- vcv(phy)

# Standardize the phylogenetic covariance matrix to have determinant = 1.
# (For an explanation of this standardization, see subsection 4.3.1 in Ives (2018))
Vphy <- Vphy / (det(Vphy)^(1 / nspp))

# Construct the overall covariance matrix for phylogenetic attraction.
# (For an explanation of Kronecker products, see subsection 4.3.1 in the book)
V <- kronecker(diag(nrow = nsite, ncol = nsite), Vphy)
Y.attract <- array(t(rmvnorm(n = 1, sigma = sd.attract^2 * V)))

# Simulate residual errors
sd.e <- 1
Y.e <- rnorm(nspp * nsite, sd = sd.e)

# Construct the dataset
d <- data.frame(
  sp = rep(phy$tip.label, times = nsite),
  site = rep(1:nsite, each = nspp)
)

# Simulate abundance data
d$Y <- Y.sp + Y.site + Y.attract + Y.e

# Analyze the model
pglmm(Y ~ 1 + (1 | sp__) + (1 | site) + (1 | sp__@site), data = d, cov_ranef = list(sp = phy))

# Display random effects: the function `pglmm_plot_ranef()` does what
# the name implies. You can set `show.image = TRUE` and `show.sim.image = TRUE`
# to see the matrices and simulations.
re <- pglmm_plot_ranef(Y ~ 1 + (1 | sp__) + (1 | site) + (1 | sp__@site),
  data = d,
  cov_ranef = list(sp = phy), show.image = FALSE,
  show.sim.image = FALSE
)

#################################################
### Example of a bipartite phylogenetic model ###
#################################################

# Investigating covariance matrices for different types of model structure
nspp <- 20
nsite <- 15

# Simulate a phylogeny that has a lot of phylogenetic signal (power = 1.3)
phy.sp <- compute.brlen(rtree(n = nspp), method = "Grafen", power = 1.3)
phy.site <- compute.brlen(rtree(n = nsite), method = "Grafen", power = 1.3)

# Simulate species means
mean.sp <- rTraitCont(phy.sp, model = "BM", sigma = 1)

# Replicate values of mean.sp over sites
Y.sp <- rep(mean.sp, times = nsite)

# Simulate site means
mean.site <- rTraitCont(phy.site, model = "BM", sigma = 1)

# Replicate values of mean.site over sp
Y.site <- rep(mean.site, each = nspp)

# Generate covariance matrix for phylogenetic attraction among species
sd.sp.attract <- 1
Vphy.sp <- vcv(phy.sp)
Vphy.sp <- Vphy.sp / (det(Vphy.sp)^(1 / nspp))
V.sp <- kronecker(diag(nrow = nsite, ncol = nsite), Vphy.sp)
Y.sp.attract <- array(t(rmvnorm(n = 1, sigma = sd.sp.attract^2 * V.sp)))

# Generate covariance matrix for phylogenetic attraction among sites
sd.site.attract <- 1
Vphy.site <- vcv(phy.site)
Vphy.site <- Vphy.site/(det(Vphy.site)^(1/nsite))
V.site <- kronecker(Vphy.site, diag(nrow = nspp, ncol = nspp))
Y.site.attract <- array(t(rmvnorm(n = 1, sigma = sd.site.attract^2*V.site)))

# Generate covariance matrix for phylogenetic attraction of species:site interaction
sd.sp.site.attract <- 1
V.sp.site <- kronecker(Vphy.site, Vphy.sp)
Y.sp.site.attract <- array(t(rmvnorm(n = 1, sigma = sd.sp.site.attract^2*V.sp.site)))

# Simulate residual error
sd.e <- 0.5
Y.e <- rnorm(nspp*nsite, sd = sd.e)

# Construct the dataset
d <- data.frame(sp = rep(phy.sp$tip.label, times = nsite),
                site = rep(phy.site$tip.label, each = nspp))

# Simulate abundance data
d$Y <- Y.sp + Y.site + Y.sp.attract + Y.site.attract + Y.sp.site.attract + Y.e

# Plot random effects covariance matrices and then add phylogenies
# Note that, if show.image and show.sim are not specified, pglmm_plot_ranef() shows
# the covariance matrices if nspp * nsite < 200 and shows simulations
# if nspp * nsite > 100
re <- pglmm_plot_ranef(Y ~ 1 + (1|sp__) + (1|site__) + (1|sp__@site) +
                    (1|sp@site__) + (1|sp__@site__),
                    data=d, cov_ranef = list(sp = phy.sp, site = phy.site))

# This flips the phylogeny to match to covariance matrices
rot.phy.site <- phy.site
for(i in (nsite+1):(nsite+Nnode(phy.site)))
   rot.phy.site <- rotate(rot.phy.site, node = i)

plot(phy.sp, main = "Species", direction = "upward")
plot(rot.phy.site, main = "Site")

# Analyze the simulated data and compute a P-value for the (1|sp__@site__)
# random effect using a LRT. It is often better to fit the reduced model before
# the full model, because it s numerically easier to fit the reduced model,
# and then the parameter estimates from the reduced model can be given to the
# full model. In this case, I have used the estimates of the random effects
# from the reduce model, mod.r$ss, as the initial estimates for the same
# parameters in the full model in the statement s2.init=c(mod.r$ss, 0.01)^2.
# The final 0.01 is for the last random effect in the full model, (1|sp__@site__).
# Note also that the output of the random effects from communityPGLMM(), mod.r$ss,
# are the standard deviations, so they have to be squared for use as initial
# values of variances in mod.f.

mod.r <- pglmm(Y ~ 1 + (1|sp__) + (1|site__) + (1|sp__@site) + (1|sp@site__),
                        data = d, cov_ranef = list(sp = phy.sp, site = phy.site))
mod.f <- pglmm(Y ~ 1 + (1|sp__) + (1|site__) + (1|sp__@site) + (1|sp@site__) +
               (1|sp__@site__), data = d,
               cov_ranef = list(sp = phy.sp, site = phy.site),
               s2.init = c(mod.r$ss, 0.01)^2)
mod.f
pvalue <- pchisq(2*(mod.f$logLik - mod.r$logLik), df = 1, lower.tail = FALSE)
pvalue

Phylogenetic Generalized Linear Mixed Model for Comparative Data

Description

pglmm_compare performs linear regression for Gaussian, binomial and Poisson phylogenetic data, estimating regression coefficients with approximate standard errors. It simultaneously estimates the strength of phylogenetic signal in the residuals and gives an approximate conditional likelihood ratio test for the hypothesis that there is no signal (returned as LRT, see Details). Therefore, when applied without predictor (independent) variables, it gives a test for phylogenetic signal. pglmm_compare is a wrapper for pglmm tailored for comparative data in which each value of the response (dependent) variable corresponds to a single tip on a phylogenetic tree. If there are multiple measures for each species, pglmm will be helpful.

Usage

pglmm_compare(
  formula,
  family = "gaussian",
  data = list(),
  phy,
  REML = TRUE,
  optimizer = NULL,
  add.obs.re = TRUE,
  verbose = FALSE,
  cpp = TRUE,
  bayes = FALSE,
  reltol = 10^-6,
  maxit = 500,
  tol.pql = 10^-6,
  maxit.pql = 200,
  marginal.summ = "mean",
  calc.DIC = TRUE,
  prior = "inla.default",
  prior_alpha = 0.1,
  prior_mu = 1,
  ML.init = FALSE,
  s2.init = 1,
  B.init = NULL,
  calc.WAIC = TRUE,
  bayes_options = NULL,
  posterior.sample = TRUE,
  return.fitted.marginals = TRUE,
  sparse = FALSE,
  standardize_cov = TRUE,
  method = c("PQL", "Laplace")
)

## S3 method for class 'pglmm_compare'
predict(object, newdata = NULL, ...)

Arguments

formula

A two-sided linear formula object describing the fixed-effects of the model; for example, Y ~ X. Binomial data can be either presence/absence, or a two-column array of 'successes' and 'failures'. The phylogenetic random term is added automatically; the formula must not have random terms.

family

Either "gaussian" for a Linear Mixed Model, or "binomial" or "poisson" for Generalized Linear Mixed Models. family should be specified as a character string (i.e., quoted). For binomial and Poisson data, we use the canonical logit and log link functions, respectively. Binomial data can be either presence/absence, or a two-column array of 'successes' and 'failures'. If bayes = TRUE there are two additional families available: "zeroinflated.binomial", and "zeroinflated.poisson", which add a zero inflation parameter; this parameter gives the probability that the response is a zero. The rest of the parameters of the model then reflect the "non-zero" part of the model. Note that "zeroinflated.binomial" only makes sense for success/failure response data.

data

A data frame containing the variables named in formula. It must has the tip labels of the phylogeny as row names; if they are not in the same order, the data frame will be arranged so that row names match the order of tip labels.

phy

A phylogenetic tree as an object of class "phylo".

REML

Whether REML or ML is used for model fitting the random effects. Ignored if bayes = TRUE. For binomial and poisson models with method = "Laplace", REML = TRUE integrates the fixed effects out of the likelihood with the Laplace approximation too (as glmmTMB(REML = TRUE)); use REML = FALSE for maximum likelihood estimates, comparable with lme4::glmer() and glmmTMB().

optimizer

Optimizer to use. Options: "lbfgs" (L-BFGS with analytic gradient; default for Gaussian, also available for binomial/Poisson), "nelder-mead-nlopt" (default for binomial/Poisson), "bobyqa", "Nelder-Mead", or "subplex". "Nelder-Mead" is from the stats package; all others are from the nloptr package. With sparse = TRUE, the default (and "lbfgs", as there is no gradient) is "subplex", "nelder-mead-nlopt" and "Nelder-Mead" both use the Nelder-Mead algorithm of nloptr, and the optimizer is restarted from its solution until the likelihood does not improve (for gaussian models; for binomial and poisson models, each PQL iteration already starts the optimizer from the previous solution). Ignored if bayes = TRUE or method = "Laplace".

add.obs.re

Whether to add an observation-level random term 1|obs for Poisson data and binomial data with more than one trial (a non-phylogenetic variance, which accounts for overdispersion). The default is TRUE, as in pglmm(): without it, overdispersion is absorbed by the phylogenetic variance, which inflates the phylogenetic signal and its test. It is not used for gaussian data (the residual variance plays this role) or binary data. Earlier versions ignored this argument, so set add.obs.re = FALSE to get their estimates.

verbose

If TRUE, the model deviance and running estimates of s2 and B are plotted each iteration during optimization.

cpp

Whether to use C++ function for optim. Default is TRUE. Ignored if bayes = TRUE.

bayes

Whether to fit a Bayesian version of the PGLMM using r-inla. We recommend against Bayesian fitting for non-Gaussian data unless sample sizes are large (>1000), because the phylogenetic variance tends to get trapped near zero.

reltol

A control parameter dictating the relative tolerance for convergence in the optimization; see optim. With sparse = TRUE, the default is 1e-8 (for each run of the optimizer, including each PQL iteration of binomial and poisson models). With method = "Laplace", the relative tolerance of nlminb() (default 1e-10); maxit is then its maximum number of iterations and evaluations.

maxit

A control parameter dictating the maximum number of iterations in the optimization; see optim.

tol.pql

A control parameter dictating the tolerance for convergence in the PQL estimates of the mean components of the GLMM. Ignored if family = "gaussian", bayes = TRUE, or method = "Laplace".

maxit.pql

A control parameter dictating the maximum number of iterations in the PQL estimates of the mean components of the GLMM. Ignored if family = "gaussian" or bayes = TRUE.

marginal.summ

Summary statistic to use for the estimate of coefficients when doing a Bayesian PGLMM (when bayes = TRUE). Options are: "mean", "median", or "mode", referring to different characterizations of the central tendency of the Bayesian posterior marginal distributions. Ignored if bayes = FALSE.

calc.DIC

Should the Deviance Information Criterion be calculated and returned when doing a Bayesian PGLMM? Ignored if bayes = FALSE.

prior

Which type of default prior should be used by pglmm? Only used if bayes = TRUE. There are currently four options: "inla.default", which uses the default INLA priors; "pc.prior.auto", which uses a complexity penalizing prior (as described in Simpson et al. (2017)) designed to automatically choose good parameters (only available for gaussian and binomial responses); "pc.prior", which allows the user to set custom parameters on the "pc.prior" prior, using the prior_alpha and prior_mu parameters (Run INLA::inla.doc("pc.prec") for details on these parameters); and "uninformative", which sets a very uninformative prior (nearly uniform) by using a very flat exponential distribution. The last option is generally not recommended but may in some cases give estimates closer to the maximum likelihood estimates. "pc.prior.auto" is only implemented for family = "gaussian" and family = "binomial" currently.

prior_alpha

Only used if bayes = TRUE and prior = "pc.prior", in which case it sets the alpha parameter of INLA's complexity penalizing prior for the random effects. The prior is an exponential distribution where prob(sd > mu) = alpha, where sd is the standard deviation of the random effect.

prior_mu

Only used if bayes = TRUE and prior = "pc.prior", in which case it sets the mu parameter of INLA's complexity penalizing prior for the random effects. The prior is an exponential distribution where prob(sd > mu) = alpha, where sd is the standard deviation of the random effect.

ML.init

Only relevant if bayes = TRUE. Should maximum likelihood estimates be calculated and used as initial values for the Bayesian model fit? Sometimes this can be helpful, but it may not help; thus, we set the default to FALSE. Also, it does not work with the zero-inflated families.

s2.init

Initial estimate of s2 (default 1; NULL uses the defaults of pglmm()).

B.init

Initial estimates of BB, a matrix containing regression coefficients in the model for the fixed effects. This matrix must have dim(B.init) = c(p + 1, 1), where p is the number of predictor (independent) variables; the first element of B corresponds to the intercept, and the remaining elements correspond in order to the predictor (independent) variables in the formula. If B.init is not provided, these are estimated using lm or glm assuming no phylogenetic signal. A better approach might be to run lmer and use the output fixed effects for B.init. When bayes = TRUE, initial values are estimated using the maximum likelihood fit unless ML.init = FALSE, in which case the default INLA initial values will be used.

calc.WAIC

Should the WAIC be calculated and returned when doing a Bayesian PGLMM? Ignored if bayes = FALSE.

bayes_options

Additional options to pass to INLA when bayes = TRUE. A named list where the names correspond to parameters in the inla function. One special option is diagonal: if an element in the list is named diagonal, INLA adds its value to the diagonal of every random-effects precision matrix, which can help with numerical stability when the model is ill-conditioned (try list(diagonal = 1e-4) if you see many warnings). To use multiple CPU cores, pass list(num.threads = 4) (or however many cores are available); this is often the single most effective way to speed up INLA. Any control.compute entries supplied here override the defaults set by posterior.sample and return.fitted.marginals.

posterior.sample

Logical (default TRUE). Only used when bayes = TRUE. When TRUE, INLA stores the full joint posterior configuration (control.compute = list(config = TRUE)), which is required for simulate to work. Set to FALSE to skip this storage and speed up fitting when posterior simulation is not needed.

return.fitted.marginals

Logical (default TRUE). Only used when bayes = TRUE. When TRUE, INLA computes and returns the marginal posterior distributions of all fitted values (control.compute = list(return.marginals.predictor = TRUE)), which is required for simulate with full = FALSE. Set to FALSE to skip this computation and speed up fitting when simulation is not needed. If both posterior.sample and return.fitted.marginals are FALSE, INLA runs at maximum speed but simulate() will not work on the fitted model.

sparse

Logical (default FALSE). If TRUE, fit the model with the sparse precision matrix of the phylogeny, which is much faster for large phylogenies (see Details and pglmm()). Only with bayes = FALSE.

standardize_cov

Logical (default TRUE). Whether to standardize the covariance matrices of cov_ranef to have a determinant of one (a phylogeny is first converted to its covariance matrix, which is divided by its largest element). If FALSE, the matrices are used as given: a covariance matrix is used as it is, and a phylogeny gives ape::vcv(tree), on the scale of its branch lengths. The variances of the random terms (s2r, s2n) are then on the scale of these matrices, so that, e.g., the variance of 1|sp__ with a phylogenetic correlation matrix (ape::vcv(tree, corr = TRUE)) or an ultrametric tree with a height of one is directly comparable with the variance of 1|sp and with software that does not standardize the matrices. The likelihood, the fixed effects and the predictions do not depend on this choice; only the scale of the variances (and of s2.init) does. Not used when random.effects is given.

method

For binomial and poisson data, "PQL" (default) or "Laplace": see Details and pglmm().

object

A fitted model with class pglmm_compare.

newdata

An optional data frame of species to predict for, as for predict.communityPGLMM(). The species are the row names of newdata (or its column sp), which must be tip labels of phy; with re.form = NA, they are not needed.

...

Additional arguments passed to predict.communityPGLMM().

Details

pglmm_compare in the package phyr is similar to binaryPGLMM in the package ape, although it has much broader functionality, including accepting more than just binary data, implementing Bayesian analyses, etc.

For non-Gaussian data, the function estimates parameters for the model

Pr(Y=1)=θPr(Y = 1) = \theta

θ=inverse.link(b0+b1∗x1+b2∗x2+⋯+ϵ)\theta = inverse.link(b0 + b1 * x1 + b2 * x2 + \dots + \epsilon)

ϵ Gaussian(0,s2∗V)\epsilon ~ Gaussian(0, s2 * V)

where VV is a covariance matrix derived from a phylogeny (typically under the assumption of Brownian motion evolution). Although mathematically there is no requirement for VV to be ultrametric, forcing VV into ultrametric form can aide in the interpretation of the model. This is especially true for binary data, because in regression for binary dependent variables, only the off-diagonal elements (i.e., covariances) of matrix VV are biologically meaningful (see Ives & Garland 2014). The function converts a phylo tree object into a covariance matrix, and further standardizes this matrix to have determinant = 1 (unless standardize_cov = FALSE). This in effect standardizes the interpretation of the scalar s2. Although mathematically not required, it is a very good idea to standardize the predictor (independent) variables to have mean 0 and variance 1. This will make the function more robust and improve the interpretation of the regression coefficients.

For Gaussian data, the function estimates parameters for the model

Y=b0+b1∗x1+b2∗x2+⋯+ϵ)Y = b0 + b1 * x1 + b2 * x2 + \dots + \epsilon)

ϵ Gaussian(0,s2∗V+s2resid∗I)\epsilon ~ Gaussian(0, s2 * V + s2resid * I)

where s2resid∗Is2resid * I gives the non-phylogenetic residual variance. Note that this is equivalent to a model with Pagel's lambda transformation.

pglmm_compare(Y ~ X, data = data, phy = phy) fits the same model as pglmm(Y ~ X + (1 | sp__), data = data, cov_ranef = list(sp = phy)) with a column sp of species (the row names of data), but without the non-phylogenetic random term (1 | sp) that pglmm() adds with (1 | sp__): with one row per species, that term would be confounded with the residual variance (gaussian data) or with the observation-level random term (binomial and poisson data). The phylogenetic random term is named 1|sp__ in the output of methods such as VarCorr() and ranef(). (If data already has a column sp that is not the species, the column species or .sp is used instead; its name is in sp_var.)

The returned object has class c("pglmm_compare", "communityPGLMM"), so the methods for models fitted by pglmm() can be used: fixef(), ranef() (the estimates of the phylogenetic random effect of each species, with condVar = TRUE for their standard deviations), VarCorr(), fitted(), residuals(), predict() (with newdata, the species are the row names of newdata), simulate(), logLik() and AIC() (bayes = FALSE), and pglmm_profile_LRT(). With sparse = TRUE, pglmm_iV() is not available (nor with method = "Laplace").

Test of phylogenetic signal. For models fitted with bayes = FALSE, the element LRT is pglmm_profile_LRT(fit, re.number = 1): a likelihood ratio test of the hypothesis that the phylogenetic variance s2 is zero, conditional on the other estimates (the log-likelihood is compared with the one obtained by setting s2 to zero, without re-estimating the other parameters). As s2 = 0 is on the boundary of the parameter space, the p-value Pr is half of the p-value of a chi-square distribution with one degree of freedom. For binomial and poisson data, the log-likelihood is the approximate log-likelihood of the penalized quasi-likelihood fit (with method = "PQL", the default) or the Laplace approximation of the log-likelihood (with method = "Laplace"). It is printed by summary().

Binary and count data. With method = "Laplace", binomial and poisson models are fitted with the Laplace approximation of the likelihood instead of penalized quasi-likelihood (PQL), which underestimates the phylogenetic variance (and with it the phylogenetic signal) for binary data; see the argument method of pglmm(). The estimates are then the same as those of glmmTMB() with a phylogenetic covariance matrix (propto()), with REML = FALSE.

Large phylogenies. With sparse = TRUE, the model is fitted with the sparse precision matrix of the phylogeny (including its internal nodes) instead of the dense covariance matrix of the species; the likelihood is the same, but time and memory grow about linearly with the number of species, so data with tens of thousands of species can be fitted. See the argument sparse of pglmm() for details. The covariance matrix vcv.phy is then not formed (it is NULL); the same with method = "Laplace".

Value

An object of class c("pglmm_compare", "communityPGLMM"): all the elements returned by pglmm() (see its Value section), and:

formula

the formula for fixed effects, as given

phy

the phylogeny, with the tips not in the data dropped

vcv.phy

a list with the (standardized) covariance matrix of the species in the order of the rows of the data, covar; NULL with sparse = TRUE

LRT

for bayes = FALSE, the test of phylogenetic signal: a list with the likelihood ratio LR, df, and the p-value Pr (see Details)

sp_var

the name of the column of species added to the data

The elements most often used are:

B, B.se, B.cov, B.zscore, B.pvalue

estimates of the regression coefficients, their approximate standard errors, covariance matrix, Z scores and p-values (B.se, B.zscore and B.pvalue are NULL if bayes = TRUE)

B.ci

credible intervals of the regression coefficients if bayes = TRUE

s2n

the phylogenetic variance s2 (and the variance of 1|obs if add.obs.re = TRUE)

s2resid

for gaussian data, the residual variance

s2n.ci, s2resid.ci

credible intervals of the variances if bayes = TRUE

logLik, AIC, BIC

the (restricted, if REML = TRUE) log-likelihood and the information criteria; with bayes = TRUE, logLik is the marginal log-likelihood, and DIC and WAIC are returned

H, mu, Y, X

residuals, predicted mean values (binomial and poisson data), response and design matrix, as in pglmm()

convcode, niter

convergence code and number of iterations of the optimizer

inla.model

the model fitted by inla, if bayes = TRUE

Author(s)

Anthony R. Ives

References

Ives, A. R. and Helmus, M. R. (2011) Generalized linear mixed models for phylogenetic analyses of community structure. Ecological Monographs, 81, 511–525.

Ives, A. R. and Garland, T., Jr. (2014) Phylogenetic regression for binary dependent variables. Pages 231–261 in L. Z. Garamszegi, editor. Modern Phylogenetic Comparative Methods and Their Application in Evolutionary Biology. Springer-Verlag, Berlin Heidelberg.

See Also

pglmm; package ape and its function binaryPGLMM; package phylolm and its function phyloglm; package MCMCglmm

Examples

## Illustration of `pglmm_compare` with simulated data

# Generate random phylogeny

library(ape)

n <- 100
phy <- compute.brlen(rtree(n=n), method = "Grafen", power = 1)

# Generate random data and standardize to have mean 0 and variance 1
X1 <- rTraitCont(phy, model = "BM", sigma = 1)
X1 <- (X1 - mean(X1))/var(X1)

# Simulate binary Y
sim.dat <- data.frame(Y = array(0, dim = n), X1 = X1, row.names = phy$tip.label)
sim.dat$Y <- ape::binaryPGLMM.sim(Y ~ X1, phy = phy, data=sim.dat, s2 = 1,
                             B = matrix(c(0, .25), nrow = 2, ncol = 1), 
                             nrep = 1)$Y

# Fit model
fit <- pglmm_compare(Y ~ X1, family = "binomial", phy = phy, data = sim.dat)
fit

# test of phylogenetic signal (also printed above)
fit$LRT
# methods of pglmm() models
fixef(fit)
VarCorr(fit)
head(ranef(fit, condVar = TRUE)[["1|sp__"]])
predict(fit, newdata = sim.dat[1:3, ], type = "response")

# the same model fitted with the sparse precision matrix of the phylogeny,
# much faster for large phylogenies
fit_sparse <- pglmm_compare(Y ~ X1, family = "binomial", phy = phy, data = sim.dat,
                            sparse = TRUE)
cbind(dense = fit$B, sparse = fit_sparse$B)

# the Laplace approximation of the likelihood (less biased than PQL for
# binary data), with maximum likelihood estimates
fit_laplace <- pglmm_compare(Y ~ X1, family = "binomial", phy = phy, data = sim.dat,
                             method = "Laplace", REML = FALSE)
fit_laplace

# Compare with `binaryPGLMM`
ape::binaryPGLMM(Y ~ X1, phy = phy, data = sim.dat)

# Compare with `phyloglm`
summary(phylolm::phyloglm(Y ~ X1, phy = phy, data = sim.dat))

# Compare with `glm` that does not account for phylogeny
summary(glm(Y ~ X1, data = sim.dat, family = "binomial"))

# Compare with logistf() that does not account
# for phylogeny but is less biased than glm()
logistf::logistf(Y ~ X1, data = sim.dat)

## Fit model with bayes = TRUE
# pglmm_compare(Y ~ X1, family = "binomial", phy = phy, data = sim.dat, 
#               bayes = TRUE, calc.DIC = TRUE)

# Compare with `MCMCglmm`

V <- vcv(phy)
V <- V/max(V)
detV <- exp(determinant(V)$modulus[1])
V <- V/detV^(1/n)

invV <- Matrix::Matrix(solve(V),sparse = TRUE)
sim.dat$species <- phy$tip.label
rownames(invV) <- sim.dat$species

nitt <- 43000
thin <- 10
burnin <- 3000

prior <- list(R=list(V=1, fix=1), G=list(G1=list(V=1, nu=1000, alpha.mu=0, alpha.V=1)))
# commented out to save time
# summary(MCMCglmm::MCMCglmm(Y ~ X1, random = ~species, ginvers = list(species = invV),
#     data = sim.dat, slice = TRUE, nitt = nitt, thin = thin, burnin = burnin,
#    family = "categorical", prior = prior, verbose = FALSE))

Inverse of the covariance matrix of a fitted PGLMM

Description

Calculate the inverse of the marginal covariance matrix (iV) of the data for a model fitted with bayes = FALSE. Since version 1.3.0, this n by n matrix is no longer returned by pglmm(), because it needs a lot of memory and time for large data sets, and no function of the package needs it.

Usage

pglmm_iV(x)

Arguments

x

A fitted model with class communityPGLMM (with bayes = FALSE).

Value

A matrix with as many rows and columns as the number of observations used to fit the model. For gaussian models, it includes the residual variance. For binomial and poisson models, it is the inverse of the covariance matrix of the working response of the penalized quasi-likelihood fit.

Examples

dat <- data.frame(
  site = rep(rownames(comm_a), times = ncol(comm_a)),
  sp = rep(colnames(comm_a), each = nrow(comm_a)),
  freq = unlist(comm_a, use.names = FALSE)
)
phy <- ape::keep.tip(phylotree, unique(dat$sp))
fit <- pglmm(freq ~ 1 + (1 | sp__) + (1 | site), data = dat, cov_ranef = list(sp = phy))
iV <- pglmm_iV(fit)
dim(iV)

pglmm_matrix_structure produces the entire covariance matrix structure (V) when you specify random effects.

Description

pglmm_matrix_structure produces the entire covariance matrix structure (V) when you specify random effects.

Usage

pglmm_matrix_structure(
  formula,
  data = list(),
  family = "binomial",
  cov_ranef,
  repulsion = FALSE,
  ss = 1,
  cpp = TRUE
)

communityPGLMM.matrix.structure(
  formula,
  data = list(),
  family = "binomial",
  cov_ranef,
  repulsion = FALSE,
  ss = 1,
  cpp = TRUE
)

Arguments

formula

A two-sided linear formula object describing the mixed effects of the model.

To specify that a random term should have phylogenetic covariance matrix along with non-phylogenetic one, add __ (two underscores) at the end of the group variable; e.g., + (1 | sp__) will construct two random terms, one with phylogenetic covariance matrix and another with non-phylogenetic (identity) matrix. In contrast, __ in the nested terms (below) will only create a phylogenetic covariance matrix. Nested random terms have the general form (1|sp__@site__) which represents phylogenetically related species nested within correlated sites. This form can be used for bipartite questions. For example, species could be phylogenetically related pollinators and sites could be phylogenetically related plants, leading to the random effect (1|insects__@plants__). If more than one phylogeny is used, remember to add all to the argument cov_ranef = list(insects = insect_phylo, plants = plant_phylo). Phylogenetic correlations can be dropped by removing the __ underscores. Thus, the form (1|sp@site__) excludes the phylogenetic correlations among species, while the form (1|sp__@site) excludes the correlations among sites.

Note that correlated random terms are not allowed. For example, (x|g) will be the same as (0 + x|g) in the lme4::lmer syntax. However, (x1 + x2|g) won't work, so instead use (x1|g) + (x2|g).

data

A data.frame containing the variables named in formula. Rows where the response variable is NA are dropped before fitting; this is equivalent to removing those rows from data manually before calling pglmm. As a result, pglmm(data_with_NAs) and pglmm(data[!is.na(data$y), ]) produce identical estimates.

family

Either "gaussian" for a Linear Mixed Model, or "binomial" or "poisson" for Generalized Linear Mixed Models. "family" should be specified as a character string (i.e., quoted). For binomial and Poisson data, we use the canonical logit and log link functions, respectively. Binomial data can be either presence/absence, or a two-column array of 'successes' and 'failures'. For both binomial and Poisson data, we add an observation-level random term by default via add.obs.re = TRUE. If bayes = TRUE there are two additional families available: "zeroinflated.binomial", and "zeroinflated.poisson", which add a zero inflation parameter; this parameter gives the probability that the response is a zero. The rest of the parameters of the model then reflect the "non-zero" part part of the model. Note that "zeroinflated.binomial" only makes sense for success/failure response data.

cov_ranef

A named list of covariance matrices of random terms. The names should be the group variables that are used as random terms with specified covariance matrices (without the two underscores, e.g. list(sp = tree1, site = tree2)). The actual object can be either a phylogeny with class "phylo" or a prepared covariance matrix. If it is a phylogeny, pglmm will prune it and then convert it to a covariance matrix assuming Brownian motion evolution. pglmm will also standardize all covariance matrices to have determinant of one (unless standardize_cov = FALSE), so the estimated variances of these terms are on the scale of the standardized matrices; use scale_factors of the fitted model to rescale them (see "Extracting the variances of random terms" in Details). Group variables will be converted to factors and all covariance matrices will be rearranged so that rows and columns are in the same order as the levels of their corresponding group variables.

repulsion

When there are nested random terms specified, repulsion = FALSE tests for phylogenetic underdispersion while repulsion = TRUE tests for overdispersion. This argument is a logical vector of length either 1 or >1. If its length is 1, it applies to the phylogenies of species only (the variable before @, e.g. sp in sp__@site and sp__@site__): their covariance matrices are either inverted (overdispersion) or not, while the phylogenies of sites (after @) are never inverted. This follows Ives and Helmus (2011, Appendix A), where repulsion arises from competition among closely related species. If it has more than one element, then you can select which covariance matrix in the nested terms to be inverted. Make sure to get the length right: for all the terms with @, count the number of "__" to determine the length of repulsion. For example, sp__@site and sp@site__ will each require one element of repulsion, while sp__@site__ will take two elements (repulsion for sp and repulsion for site). Therefore, if your nested terms are (1|sp__@site) + (1|sp@site__) + (1|sp__@site__), then you should set the repulsion to be something like c(TRUE, FALSE, TRUE, TRUE) (length of 4).

ss

Which of the random.effects to produce.

cpp

Whether to use C++ function for optim. Default is TRUE. Ignored if bayes = TRUE.

Value

A design matrix.


Visualize random terms of communityPGLMMs

Description

Plot variance-cov matrix of random terms; also it is optional to simulate and visualize data based on these var-cov matrices. The input can be a communityPGLMM model (by setting argument x). If no model has been fitted, you can also specify data, formula, and family, etc. without actually fitting the model, which will save time.

Usage

pglmm_plot_ranef(
  formula = NULL,
  data = NULL,
  family = "gaussian",
  sp.var = "sp",
  site.var = "site",
  tree = NULL,
  tree_site = NULL,
  repulsion = FALSE,
  x = NULL,
  show.image = TRUE,
  show.sim.image = FALSE,
  random.effects = NULL,
  add.tree.sp = TRUE,
  add.tree.site = FALSE,
  cov_ranef = NULL,
  tree.panel.space = 0.5,
  title.space = 5,
  tree.size = 3,
  ...
)

communityPGLMM.show.re(
  formula = NULL,
  data = NULL,
  family = "gaussian",
  sp.var = "sp",
  site.var = "site",
  tree = NULL,
  tree_site = NULL,
  repulsion = FALSE,
  x = NULL,
  show.image = TRUE,
  show.sim.image = FALSE,
  random.effects = NULL,
  add.tree.sp = TRUE,
  add.tree.site = FALSE,
  cov_ranef = NULL,
  tree.panel.space = 0.5,
  title.space = 5,
  tree.size = 3,
  ...
)

pglmm_plot_re(
  formula = NULL,
  data = NULL,
  family = "gaussian",
  sp.var = "sp",
  site.var = "site",
  tree = NULL,
  tree_site = NULL,
  repulsion = FALSE,
  x = NULL,
  show.image = TRUE,
  show.sim.image = FALSE,
  random.effects = NULL,
  add.tree.sp = TRUE,
  add.tree.site = FALSE,
  cov_ranef = NULL,
  tree.panel.space = 0.5,
  title.space = 5,
  tree.size = 3,
  ...
)

communityPGLMM.plot.re(
  formula = NULL,
  data = NULL,
  family = "gaussian",
  sp.var = "sp",
  site.var = "site",
  tree = NULL,
  tree_site = NULL,
  repulsion = FALSE,
  x = NULL,
  show.image = TRUE,
  show.sim.image = FALSE,
  random.effects = NULL,
  add.tree.sp = TRUE,
  add.tree.site = FALSE,
  cov_ranef = NULL,
  tree.panel.space = 0.5,
  title.space = 5,
  tree.size = 3,
  ...
)

Arguments

formula

A two-sided linear formula object describing the mixed effects of the model.

To specify that a random term should have phylogenetic covariance matrix along with non-phylogenetic one, add __ (two underscores) at the end of the group variable; e.g., + (1 | sp__) will construct two random terms, one with phylogenetic covariance matrix and another with non-phylogenetic (identity) matrix. In contrast, __ in the nested terms (below) will only create a phylogenetic covariance matrix. Nested random terms have the general form (1|sp__@site__) which represents phylogenetically related species nested within correlated sites. This form can be used for bipartite questions. For example, species could be phylogenetically related pollinators and sites could be phylogenetically related plants, leading to the random effect (1|insects__@plants__). If more than one phylogeny is used, remember to add all to the argument cov_ranef = list(insects = insect_phylo, plants = plant_phylo). Phylogenetic correlations can be dropped by removing the __ underscores. Thus, the form (1|sp@site__) excludes the phylogenetic correlations among species, while the form (1|sp__@site) excludes the correlations among sites.

Note that correlated random terms are not allowed. For example, (x|g) will be the same as (0 + x|g) in the lme4::lmer syntax. However, (x1 + x2|g) won't work, so instead use (x1|g) + (x2|g).

data

A data.frame containing the variables named in formula. Rows where the response variable is NA are dropped before fitting; this is equivalent to removing those rows from data manually before calling pglmm. As a result, pglmm(data_with_NAs) and pglmm(data[!is.na(data$y), ]) produce identical estimates.

family

Either "gaussian" for a Linear Mixed Model, or "binomial" or "poisson" for Generalized Linear Mixed Models. "family" should be specified as a character string (i.e., quoted). For binomial and Poisson data, we use the canonical logit and log link functions, respectively. Binomial data can be either presence/absence, or a two-column array of 'successes' and 'failures'. For both binomial and Poisson data, we add an observation-level random term by default via add.obs.re = TRUE. If bayes = TRUE there are two additional families available: "zeroinflated.binomial", and "zeroinflated.poisson", which add a zero inflation parameter; this parameter gives the probability that the response is a zero. The rest of the parameters of the model then reflect the "non-zero" part part of the model. Note that "zeroinflated.binomial" only makes sense for success/failure response data.

sp.var

The variable name of "species"; y-axis of the image.

site.var

The variable name of "site"; x-axis of the image.

tree

A phylogeny for column sp, with "phylo" class, or a covariance matrix for sp. Make sure to have all species in the matrix; if the matrix is not standardized, (i.e., det(tree) != 1), pglmm will try to standardize it for you. No longer used: keep here for compatibility.

tree_site

A second phylogeny for "site". This is required only if the site column contains species instead of sites. This can be used for bipartitie questions; tree_site can also be a covariance matrix. Make sure to have all sites in the matrix; if the matrix is not standardized (i.e., det(tree_site) != 1), pglmm' will try to standardize it for you. No longer used: keep here for compatibility.

repulsion

When there are nested random terms specified, repulsion = FALSE tests for phylogenetic underdispersion while repulsion = TRUE tests for overdispersion. This argument is a logical vector of length either 1 or >1. If its length is 1, it applies to the phylogenies of species only (the variable before @, e.g. sp in sp__@site and sp__@site__): their covariance matrices are either inverted (overdispersion) or not, while the phylogenies of sites (after @) are never inverted. This follows Ives and Helmus (2011, Appendix A), where repulsion arises from competition among closely related species. If it has more than one element, then you can select which covariance matrix in the nested terms to be inverted. Make sure to get the length right: for all the terms with @, count the number of "__" to determine the length of repulsion. For example, sp__@site and sp@site__ will each require one element of repulsion, while sp__@site__ will take two elements (repulsion for sp and repulsion for site). Therefore, if your nested terms are (1|sp__@site) + (1|sp@site__) + (1|sp__@site__), then you should set the repulsion to be something like c(TRUE, FALSE, TRUE, TRUE) (length of 4).

x

A fitted model with class communityPGLMM.

show.image

Whether to show the images of random effects.

show.sim.image

Whether to show the images of simulated site by sp matrix. This can be useful to see how the phylogenetic information were included.

random.effects

Optional pre-build list of random effects. If NULL (the default), the function prep_dat_pglmm will prepare the random effects for you from the information in formula, data, and cov_ranef. random.effect allows a list of pre-generated random effects terms to increase flexibility; for example, this makes it possible to construct models with both phylogenetic correlation and spatio-temporal autocorrelation. In preparing random.effect, make sure that the orders of rows and columns of covariance matrices in the list are the same as their corresponding group variables in the data. Also, this should be a list of lists, e.g. random.effects = list(re1 = list(matrix_a), re2 = list(1, sp = sp, covar = Vsp)).

add.tree.sp

Whether to add a phylogeny of species at the top of the simulated site by sp matrix plot, default is TRUE.

add.tree.site

Whether to add a phylogeny of sites at the right of the simulated site by sp matrix plot, default is FALSE.

cov_ranef

A named list of covariance matrices of random terms. The names should be the group variables that are used as random terms with specified covariance matrices (without the two underscores, e.g. list(sp = tree1, site = tree2)). The actual object can be either a phylogeny with class "phylo" or a prepared covariance matrix. If it is a phylogeny, pglmm will prune it and then convert it to a covariance matrix assuming Brownian motion evolution. pglmm will also standardize all covariance matrices to have determinant of one (unless standardize_cov = FALSE), so the estimated variances of these terms are on the scale of the standardized matrices; use scale_factors of the fitted model to rescale them (see "Extracting the variances of random terms" in Details). Group variables will be converted to factors and all covariance matrices will be rearranged so that rows and columns are in the same order as the levels of their corresponding group variables.

tree.panel.space

The number of lines between the phylogeny and the matrix plot, if add.tree is TRUE.

title.space

The number of lines between the title and the matrix plot, if add.tree is TRUE.

tree.size

The height of the phylogeny to be plotted (number of lines), if add.tree is TRUE.

...

Additional arguments for Matrix::image() or lattice::levelplot(). Common ones are:

  • useAbs whether to use absolute values of the matrix; if no negative values, this will be set to TRUE if not specified. When useAbs = TRUE the color scheme will be black-white, otherwise, it will be red/blue.

  • colorkey whether to draw the scale legend at the right side of each plot?

Value

A hidden list, including the covariance matrices and simulated site by species matrices. Individual plots are saved as plt_re_list and plt_sim_list. If show.image or show.sim.image is TRUE, the corresponding final plot (plt_re_all_in_one or plt_sim_all_in_one) can be saved as external file using ggplot2::ggsave as it is a grid object.


Predicted values of PGLMM

Description

pglmm_predicted_values calculates the predicted values of Y. By default, they are on the scale of the linear predictor (i.e. in the transformed space for the generalized linear mixed models with family %in% c("binomial","poisson")).

Usage

pglmm_predicted_values(
  x,
  cpp = TRUE,
  gaussian.pred = c("nearest_node", "tip_rm"),
  re.form = NULL,
  type = c("link", "response"),
  ...
)

communityPGLMM.predicted.values(
  x,
  cpp = TRUE,
  gaussian.pred = c("nearest_node", "tip_rm")
)

Arguments

x

A fitted model with class communityPGLMM.

cpp

Not used anymore.

gaussian.pred

When family is gaussian and bayes = FALSE, which type of prediction to calculate? Option nearest_node (default) gives the fitted values conditional on the estimated random effects (i.e. Xb + Zu, with u from ranef()), which is the same as fitted() or predict() of lme4. Option tip_rm gives leave-one-out predictions: each data point is removed, then predicted with the remaining ones (i.e. Xb plus the prediction of its residual given the residuals of all other data points).

re.form

(formula, NULL, or NA) specify which random effects to condition on when predicting. If NULL, include all random effects (i.e Xb + Zu); if NA or ~0, include no random effects (i.e. Xb).

type

Whether the predicted values are on the scale of the linear predictor ("link", default) or of the response ("response").

...

Optional additional parameters. None are used at present.

Value

A data frame with column Y_hat (predicted values accounting for both fixed and random terms, unless re.form is NA or ~0).

Examples

# community data: abundance of each species at each site
dat <- data.frame(
  site = rep(rownames(comm_a), times = ncol(comm_a)),
  sp = rep(colnames(comm_a), each = nrow(comm_a)),
  freq = unlist(comm_a, use.names = FALSE)
)
dat$shade <- envi$shade[match(dat$site, envi$site)]
phy <- ape::keep.tip(phylotree, unique(dat$sp))
fit <- pglmm(freq ~ shade + (1 | sp__) + (1 | site),
  data = dat, cov_ranef = list(sp = phy)
)

# fitted values conditional on the estimates of random effects: Xb + Zu
head(pglmm_predicted_values(fit))
# leave-one-out predictions
head(pglmm_predicted_values(fit, gaussian.pred = "tip_rm"))
# without random effects: Xb
head(pglmm_predicted_values(fit, re.form = NA))

# binomial model: scale of the linear predictor (logit) or of the response
dat$pa <- as.numeric(dat$freq > 0)
fit_pa <- pglmm(pa ~ shade + (1 | sp__) + (1 | site),
  data = dat, family = "binomial", cov_ranef = list(sp = phy)
)
head(pglmm_predicted_values(fit_pa))
head(pglmm_predicted_values(fit_pa, type = "response"))

Testing statistical significance of random effect

Description

pglmm_profile_LRT tests statistical significance of the phylogenetic random effect using profile likelihoods when bayes = F. The resulting p-values are conditional on the fixed estimates of the other parameters, in contrast to a standard likelihood ratio test.

Usage

pglmm_profile_LRT(x, re.number = 0, cpp = TRUE)

communityPGLMM.profile.LRT(x, re.number = 0, cpp = TRUE)

Arguments

x

A fitted model with class communityPGLMM with bayes = FALSE.

re.number

Which random term to test? Can be a vector with length >1.

cpp

Whether to use C++ function for optim. Default is TRUE. Ignored if bayes = TRUE.

Details

For binomial and poisson models fitted with method = "Laplace", the log-likelihoods are the Laplace approximations of the (restricted) marginal log-likelihood (for REML = FALSE, with the fixed effects at their estimates; for REML = TRUE, integrated out).

Value

A list of likelihood, df, and p-value.


Example phylogeny

Description

A phylogeny with more species than the community data.

Usage

phylotree

Format

Newick format.


plot_bayes generic

Description

plot_bayes generic

Usage

plot_bayes(x, ...)

Arguments

x

A communityPGLMM object fit with bayes = TRUE.

...

Further arguments to pass to or from other methods.

Value

A ggplot object


Plot the original dataset and predicted values (optional)

Description

Plots a representation of the marginal posterior distribution of model parameters. Note this function requires the packages ggplot2 and ggridges to be installed.

Usage

plot_data(
  x,
  sp.var = "sp",
  site.var = "site",
  show.sp.names = FALSE,
  show.site.names = FALSE,
  digits = max(3, getOption("digits") - 3),
  predicted = FALSE,
  ...
)

## S3 method for class 'communityPGLMM'
plot_bayes(x, n_samp = 1000, sort = TRUE, ...)

Arguments

x

A communityPGLMM object fit with bayes = TRUE.

sp.var

The variable name of "species"; y-axis of the image.

site.var

The variable name of "site"; x-axis of the image.

show.sp.names

Whether to print species names as y-axis labels.

show.site.names

Whether to print site names as x-axis labels.

digits

Not used.

predicted

Whether to plot predicted values side by side with observed ones.

...

Further arguments to pass to or from other methods.

n_samp

Number of sample from the marginal posterior to take in order to estimate the posterior density.

sort

Whether to plot different terms in the order of their estimations. Default is 'TRUE'.

Value

A ggplot object

Note

The underlying plot grid object is returned but invisible. It can be saved for later uses.


Predict Function for communityPGLMM Model Objects

Description

Predicted values of a fitted model, for the data used to fit the model or for new data.

Usage

## S3 method for class 'communityPGLMM'
predict(
  object,
  newdata = NULL,
  re.form = NULL,
  type = c("link", "response"),
  allow.new.levels = FALSE,
  ...
)

Arguments

object

A fitted model with class communityPGLMM.

newdata

An optional data frame with the predictors (and the grouping variables of random terms, unless re.form is NA or ~0) to predict with. The response is not needed. If NULL (default), predictions are for the data used to fit the model, see pglmm_predicted_values().

re.form

(formula, NULL, or NA) specify which random effects to condition on when predicting. If NULL, include all random effects (i.e Xb + Zu); if NA or ~0, include no random effects (i.e. Xb).

type

Whether the predicted values are on the scale of the linear predictor ("link", default) or of the response ("response").

allow.new.levels

Whether to allow levels of grouping variables in newdata that were not in the data used to fit the model. If TRUE, their random effects are set to zero; if FALSE (default), they give an error. Only used with newdata.

...

Additional arguments passed to pglmm_predicted_values() when newdata is NULL, e.g. gaussian.pred.

Details

With newdata, the predicted values are the fixed part (Xb) calculated with the predictors in newdata, plus (unless re.form is NA or ~0) the estimates of the random effects (see ranef()) of the levels of the grouping variables in newdata:

  • For phylogenetic terms such as (1 | sp__), the estimates of both the non-phylogenetic and the phylogenetic random terms are added.

  • For random slopes such as (x | sp), the estimates are multiplied by the values of x in newdata.

  • For nested terms such as (1 | sp__@site), the estimates are those of the combinations of levels (e.g. of sp and site) in newdata.

  • Levels (or combinations of levels for nested terms) that were not in the data used to fit the model have no estimate. They give an error, unless allow.new.levels = TRUE, in which case their random effects are set to zero (the predictions for them are then unconditional on these random terms). This also applies to species that are in the phylogeny but not in the data used to fit the model.

  • The observation-level random term (1|obs), which is added by default for poisson and binomial (with more than one trial) models, is always set to zero, as the rows of newdata are treated as new observations. As a result, for these models, predictions with newdata being the data used to fit the model are different from those without newdata.

For models fitted with bayes = TRUE, predictions with newdata are calculated in the same way, with the posterior summaries (see marginal.summ of pglmm()) of fixed and random effects. They have no credible intervals.

Predictions with newdata and random effects are only available for models with random terms specified in the formula (i.e. not via the argument random.effects of pglmm()).

Value

A matrix with one column (Y_hat) and one row for each row of the data (or of newdata). Rows of newdata with missing values in the variables needed have NA.

Examples

# community data: abundance of each species at each site
dat <- data.frame(
  site = rep(rownames(comm_a), times = ncol(comm_a)),
  sp = rep(colnames(comm_a), each = nrow(comm_a)),
  freq = unlist(comm_a, use.names = FALSE)
)
dat$shade <- envi$shade[match(dat$site, envi$site)]
phy <- ape::keep.tip(phylotree, unique(dat$sp))
fit <- pglmm(freq ~ shade + (1 | sp__) + (1 | site),
  data = dat, cov_ranef = list(sp = phy)
)

# predictions for the data used to fit the model
head(predict(fit))

# predictions for new data: the response is not needed
newdat <- data.frame(
  sp = c("Acer_rubrum", "Acer_rubrum", "Achillea_millefolium"),
  site = c("s3293", "s3294", "s3293"),
  shade = c(20, 50, 80)
)
predict(fit, newdata = newdat)
# without random effects (the grouping variables are then not needed)
predict(fit, newdata = newdat, re.form = NA)

# a site (or species) that was not in the data used to fit the model gives
# an error, unless allow.new.levels = TRUE: its random effect is then zero
newdat2 <- data.frame(sp = "Acer_rubrum", site = "a_new_site", shade = 50)
predict(fit, newdata = newdat2, allow.new.levels = TRUE)

# binomial model: predicted probabilities
dat$pa <- as.numeric(dat$freq > 0)
fit_pa <- pglmm(pa ~ shade + (1 | sp__) + (1 | site),
  data = dat, family = "binomial", cov_ranef = list(sp = phy)
)
predict(fit_pa, newdata = newdat, type = "response")

Prepare data for pglmm

Description

This function is mainly used within pglmm but can also be used independently to prepare a list of random effects, which then can be updated by users for more complex models.

Usage

prep_dat_pglmm(
  formula,
  data,
  cov_ranef = NULL,
  repulsion = FALSE,
  prep.re.effects = TRUE,
  family = "gaussian",
  add.obs.re = TRUE,
  bayes = FALSE,
  bayes_nested_matrix_as_list = FALSE,
  standardize_cov = TRUE
)

Arguments

formula

A two-sided linear formula object describing the mixed effects of the model.

To specify that a random term should have phylogenetic covariance matrix along with non-phylogenetic one, add __ (two underscores) at the end of the group variable; e.g., + (1 | sp__) will construct two random terms, one with phylogenetic covariance matrix and another with non-phylogenetic (identity) matrix. In contrast, __ in the nested terms (below) will only create a phylogenetic covariance matrix. Nested random terms have the general form (1|sp__@site__) which represents phylogenetically related species nested within correlated sites. This form can be used for bipartite questions. For example, species could be phylogenetically related pollinators and sites could be phylogenetically related plants, leading to the random effect (1|insects__@plants__). If more than one phylogeny is used, remember to add all to the argument cov_ranef = list(insects = insect_phylo, plants = plant_phylo). Phylogenetic correlations can be dropped by removing the __ underscores. Thus, the form (1|sp@site__) excludes the phylogenetic correlations among species, while the form (1|sp__@site) excludes the correlations among sites.

Note that correlated random terms are not allowed. For example, (x|g) will be the same as (0 + x|g) in the lme4::lmer syntax. However, (x1 + x2|g) won't work, so instead use (x1|g) + (x2|g).

data

A data.frame containing the variables named in formula. Rows where the response variable is NA are dropped before fitting; this is equivalent to removing those rows from data manually before calling pglmm. As a result, pglmm(data_with_NAs) and pglmm(data[!is.na(data$y), ]) produce identical estimates.

cov_ranef

A named list of covariance matrices of random terms. The names should be the group variables that are used as random terms with specified covariance matrices (without the two underscores, e.g. list(sp = tree1, site = tree2)). The actual object can be either a phylogeny with class "phylo" or a prepared covariance matrix. If it is a phylogeny, pglmm will prune it and then convert it to a covariance matrix assuming Brownian motion evolution. pglmm will also standardize all covariance matrices to have determinant of one (unless standardize_cov = FALSE), so the estimated variances of these terms are on the scale of the standardized matrices; use scale_factors of the fitted model to rescale them (see "Extracting the variances of random terms" in Details). Group variables will be converted to factors and all covariance matrices will be rearranged so that rows and columns are in the same order as the levels of their corresponding group variables.

repulsion

When there are nested random terms specified, repulsion = FALSE tests for phylogenetic underdispersion while repulsion = TRUE tests for overdispersion. This argument is a logical vector of length either 1 or >1. If its length is 1, it applies to the phylogenies of species only (the variable before @, e.g. sp in sp__@site and sp__@site__): their covariance matrices are either inverted (overdispersion) or not, while the phylogenies of sites (after @) are never inverted. This follows Ives and Helmus (2011, Appendix A), where repulsion arises from competition among closely related species. If it has more than one element, then you can select which covariance matrix in the nested terms to be inverted. Make sure to get the length right: for all the terms with @, count the number of "__" to determine the length of repulsion. For example, sp__@site and sp@site__ will each require one element of repulsion, while sp__@site__ will take two elements (repulsion for sp and repulsion for site). Therefore, if your nested terms are (1|sp__@site) + (1|sp@site__) + (1|sp__@site__), then you should set the repulsion to be something like c(TRUE, FALSE, TRUE, TRUE) (length of 4).

prep.re.effects

Whether to prepare random effects for users.

family

Either "gaussian" for a Linear Mixed Model, or "binomial" or "poisson" for Generalized Linear Mixed Models. "family" should be specified as a character string (i.e., quoted). For binomial and Poisson data, we use the canonical logit and log link functions, respectively. Binomial data can be either presence/absence, or a two-column array of 'successes' and 'failures'. For both binomial and Poisson data, we add an observation-level random term by default via add.obs.re = TRUE. If bayes = TRUE there are two additional families available: "zeroinflated.binomial", and "zeroinflated.poisson", which add a zero inflation parameter; this parameter gives the probability that the response is a zero. The rest of the parameters of the model then reflect the "non-zero" part part of the model. Note that "zeroinflated.binomial" only makes sense for success/failure response data.

add.obs.re

Whether to add an observation-level random term for binomial or Poisson distributions. Normally it would be a good idea to add this to account for overdispersion, so add.obs.re = TRUE by default.

bayes

Whether to fit a Bayesian version of the PGLMM using r-inla.

bayes_nested_matrix_as_list

For bayes = TRUE, prepare the nested terms as a list of length 4 as the old way?

standardize_cov

Logical (default TRUE). Whether to standardize the covariance matrices of cov_ranef to have a determinant of one (a phylogeny is first converted to its covariance matrix, which is divided by its largest element). If FALSE, the matrices are used as given: a covariance matrix is used as it is, and a phylogeny gives ape::vcv(tree), on the scale of its branch lengths. The variances of the random terms (s2r, s2n) are then on the scale of these matrices, so that, e.g., the variance of 1|sp__ with a phylogenetic correlation matrix (ape::vcv(tree, corr = TRUE)) or an ultrametric tree with a height of one is directly comparable with the variance of 1|sp and with software that does not standardize the matrices. The likelihood, the fixed effects and the predictions do not depend on this choice; only the scale of the variances (and of s2.init) does. Not used when random.effects is given.

Value

A list with updated formula, random.effects, and updated cov_ranef.


Print summary information of fitted model

Description

Print summary information of fitted model

Usage

## S3 method for class 'communityPGLMM'
print(x, digits = max(3, getOption("digits") - 3), ...)

Arguments

x

A fitted communityPGLMM model.

digits

Minimal number of significant digits for printing, as in print.default.

...

Additional arguments, currently ignored.


Print summary information of fitted model

Description

Print summary information of fitted model

Usage

## S3 method for class 'pglmm_compare'
print(x, digits = max(3, getOption("digits") - 3), ...)

Arguments

x

A fitted pglmm_compare.

digits

Minimal number of significant digits for printing, as in print.default.

...

Additional arguments, currently ignored.


Phylogenetic Species Diversity Metrics

Description

Calculate the bounded phylogenetic biodiversity metrics: phylogenetic species variability, richness, evenness and clustering for one or multiple communities.

Usage

psv(
  comm,
  tree,
  compute.var = TRUE,
  scale.vcv = TRUE,
  prune.tree = FALSE,
  cpp = TRUE
)

psr(
  comm,
  tree,
  compute.var = TRUE,
  scale.vcv = TRUE,
  prune.tree = FALSE,
  cpp = TRUE
)

pse(comm, tree, scale.vcv = TRUE, prune.tree = FALSE, cpp = TRUE)

psc(comm, tree, scale.vcv = TRUE, prune.tree = FALSE)

psv.spp(comm, tree, scale.vcv = TRUE, prune.tree = FALSE, cpp = TRUE)

psd(
  comm,
  tree,
  compute.var = TRUE,
  scale.vcv = TRUE,
  prune.tree = FALSE,
  cpp = TRUE
)

Arguments

comm

Community data matrix, site as rows and species as columns, site names as row names.

tree

A phylo tree object with class "phylo" or a phylogenetic covariance matrix.

compute.var

Logical, default is TRUE, computes the expected variances for PSV and PSR for each community.

scale.vcv

Logical, default is TRUE, scale the phylogenetic covariance matrix to bound the metric between 0 and 1 (i.e. correlations).

prune.tree

Logical, default is FALSE, prune the phylogeny before converting to var-cov matrix? Pruning and then converting VS converting then subsetting may have different var-cov matrix resulted.

cpp

Logical, default is TRUE, whether to use cpp for internal calculations.

Details

Phylogenetic species variability (PSV) quantifies how phylogenetic relatedness decreases the variance of a hypothetical unselected/neutral trait shared by all species in a community. The expected value of PSV is statistically independent of species richness, is one when all species in a community are unrelated (i.e., a star phylogeny) and approaches zero as species become more related. PSV is directly related to mean phylogenetic distance, except except calculated on a scaled phylogenetic covariance matrix. The expected variance around PSV for any community of a particular species richness can be approximated. To address how individual species contribute to the mean PSV of a data set, the function psv.spp gives signed proportions of the total deviation from the mean PSV that occurs when all species are removed from the data set one at a time. The absolute values of these “species effects” tend to positively correlate with species prevalence.

Value

Returns a dataframe of the respective phylogenetic species diversity metric values

Note

These metrics are bounded either between zero and one (PSV, PSE, PSC) or zero and species richness (PSR); but the metrics asymptotically approach zero as relatedness increases. Zero can be assigned to communities with less than two species, but conclusions drawn from assigning communities zero values need be carefully explored for any data set. The data sets need not be species-community data sets but may be any community data set with an associated phylogeny.

Author(s)

Matthew Helmus [email protected]

References

Helmus M.R., Bland T.J., Williams C.K. & Ives A.R. 2007. Phylogenetic measures of biodiversity. American Naturalist, 169, E68-E83

Examples

psv(comm = comm_a, tree = phylotree)

Extract group-level estimates of random effects

Description

Extract group-level estimates of random effects

Usage

## S3 method for class 'communityPGLMM'
ranef(object, condVar = FALSE, ...)

## S3 method for class 'ranef.pglmm'
print(x, n = 10L, ...)

Arguments

object

A fitted model with class communityPGLMM.

condVar

Whether to also return the conditional standard deviations of the estimates (column se), calculated conditional on the estimated fixed effects and variances of random terms, as in lme4. Only used when bayes = FALSE. This needs more computation than the estimates themselves for large data sets. Default is FALSE.

...

Ignored.

x

Output of ranef().

n

Number of rows to print for each random term.

Details

Extract the estimates of each level of each random term (e.g. one value per species for (1 | sp)) from a fitted model, similar to lme4::ranef(). To get the variances of the random terms, use VarCorr().

For models fitted by maximum likelihood (bayes = FALSE), the estimates are the conditional modes (BLUPs) of the random effects given the data and the estimated parameters, u^k=σk2CkZk′V−1(y−Xβ)\hat{u}_k = \sigma_k^2 C_k Z_k' V^{-1} (y - X\beta). For binomial and poisson models fitted with method = "PQL" (the default), they are the conditional modes of the penalized quasi-likelihood (PQL) fit, calculated with the working response; they will be close to, but not the same as, the estimates from models fitted with a Laplace approximation (e.g. lme4::glmer(), glmmTMB::glmmTMB()). With method = "Laplace", they are the conditional modes of the Laplace approximation (the same as those of glmer() and glmmTMB()), and their conditional standard deviations are from its Hessian. For Bayesian models (bayes = TRUE), the estimates are summaries of the posterior marginal distributions of the latent random effects.

All estimates are on the scale of the linear predictor. They do not depend on the standardization of the covariance matrices (e.g. to have determinant of one), because the estimated variance of the random term absorbs it.

A phylogenetic term such as (1 | sp__) is fitted as two random terms (see pglmm()): a non-phylogenetic one (1|sp) and a phylogenetic one (1|sp__). They are reported separately; their sum is the total effect of a species.

Nested terms such as (1 | sp__@site) have one value for every combination of the two grouping variables that was observed in the data. Only the levels that appear in the data have an estimate (e.g. not the species that are in the phylogeny but not in the data). Note that the levels are in the order of their first appearance in the data, not sorted alphabetically as in lme4.

Value

A named list with one data frame for each random term, in the same order as the random terms of the model. Each data frame has one row per level, with one or two columns to identify the level (named after the grouping variables), and a column estimate. For bayes = FALSE and condVar = TRUE, there is also a column se. For bayes = TRUE, there are also columns sd, lower and upper (posterior standard deviation and 95% credible interval).

See Also

VarCorr() for the variances of random terms.

Examples

# community data: abundance of each species at each site
dat <- data.frame(
  site = rep(rownames(comm_a), times = ncol(comm_a)),
  sp = rep(colnames(comm_a), each = nrow(comm_a)),
  freq = unlist(comm_a, use.names = FALSE)
)
dat$shade <- envi$shade[match(dat$site, envi$site)]
phy <- ape::keep.tip(phylotree, unique(dat$sp))
fit <- pglmm(freq ~ shade + (1 | sp__) + (1 | site),
  data = dat, cov_ranef = list(sp = phy)
)

# one data frame for each random term; (1 | sp__) is fitted as two terms
re <- ranef(fit)
names(re)
re
head(re[["1|sp__"]])

# total effect of each species: non-phylogenetic plus phylogenetic
data.frame(
  sp = re[["1|sp"]]$sp,
  estimate = re[["1|sp"]]$estimate + re[["1|sp__"]]$estimate
)

# with conditional standard deviations of the estimates
head(ranef(fit, condVar = TRUE)[["1|sp__"]])

# variances of the random terms
VarCorr(fit)

Refit bootstrap replicates that failed to converge in a call to cor_phylo

Description

This function is to be called on a cor_phylo object if one or more bootstrap replicates fail to converge. It allows the user to change parameters for the optimizer to get it to converge. One or more of the resulting cp_refits object(s) can be supplied to boot_ci along with the original cor_phylo object to calculate confidence intervals from only bootstrap replicates that converged.

Usage

refit_boots(cp_obj, inds = NULL, ...)

## S3 method for class 'cp_refits'
print(x, digits = max(3, getOption("digits") - 3), ...)

Arguments

cp_obj

The original cor_phylo object that was bootstrapped.

inds

Vector of indices indicating the bootstraps you want to refit. This is useful if you want to try refitting only a portion of bootstrap replicates. By passing NULL, it refits all bootstrap replicates present in cp_obj$bootstrap$mats. If, in the original call to cor_phylo, keep_boots was set to "fail", then any successful replicates cannot be refit here. An error will be thrown if you use inds to request a successful rep to be refit when keep_boots was set to "fail". Any bootstrap replicates not present in inds will have NA in the output object. Defaults to NULL.

...

Arguments that should be changed from the original call to cor_phylo. The boot argument is always set to 0 for refits because you don't want to bootstrap your bootstraps.

x

an object of class cp_refits.

digits

the number of digits to be printed.

Value

A cp_refits object, which is a list of cor_phylo objects corresponding to each matrix in ⁠<original cor_phylo object>$bootstrap$mats⁠.

Functions

  • print(cp_refits): prints cp_refits objects


Residuals of communityPGLMM objects

Description

Getting different types of residuals for communityPGLMM objects. The residuals are conditional on the estimated random effects, i.e. the observed values minus the fitted values (see fitted.communityPGLMM()).

Usage

## S3 method for class 'communityPGLMM'
residuals(
  object,
  type = if (object$family %in% c("binomial", "poisson")) "deviance" else "response",
  scaled = FALSE,
  ...
)

Arguments

object

A fitted model with class communityPGLMM.

type

Type of residuals, currently only "response" for gaussian pglmm; "deviance" (default) and "response" for binomial and poisson pglmm. For binomial models with more than one trial, the response is the proportion of successes.

scaled

Scale residuals by residual standard deviation for gaussian pglmm.

...

Additional arguments, ignored for method compatibility.

Value

A vector of residuals.

Examples

# community data: abundance of each species at each site
dat <- data.frame(
  site = rep(rownames(comm_a), times = ncol(comm_a)),
  sp = rep(colnames(comm_a), each = nrow(comm_a)),
  freq = unlist(comm_a, use.names = FALSE)
)
dat$shade <- envi$shade[match(dat$site, envi$site)]
phy <- ape::keep.tip(phylotree, unique(dat$sp))
fit <- pglmm(freq ~ shade + (1 | sp__) + (1 | site),
  data = dat, cov_ranef = list(sp = phy)
)

# observed values minus fitted values (conditional on random effects)
head(residuals(fit))
all.equal(residuals(fit), dat$freq - fitted(fit))
# divided by the residual standard deviation
head(residuals(fit, scaled = TRUE))

# binomial model: deviance (default) or response residuals
dat$pa <- as.numeric(dat$freq > 0)
fit_pa <- pglmm(pa ~ shade + (1 | sp__) + (1 | site),
  data = dat, family = "binomial", cov_ranef = list(sp = phy)
)
head(residuals(fit_pa))
head(residuals(fit_pa, type = "response"))

Remove site that has no observations of any species

Description

This function will remove site that has no observations in a site by species data frame.

Usage

rm_site_noobs(df, warn = FALSE)

Arguments

df

A data frame in wide form, i.e. site by species data frame, with site names as row name.

warn

Whether to warn when any site has no species? Default is FALSE.

Value

A site by species data frame.

Author(s)

Daijiang Li


Remove species that not observed in any site

Description

Remove species that not observed in any site

Usage

rm_sp_noobs(df, warn = FALSE)

Arguments

df

A data frame in wide form, i.e. site by species data frame, with site names as row name.

warn

Whether to warn when any species does not occur in at least one site? Default is FALSE.

Value

A site by species data frame.

Author(s)

Daijiang Li

This function will remove species that has no observations in any site.


Simulate from a communityPGLMM object

Description

Simulate from a communityPGLMM object

Usage

## S3 method for class 'communityPGLMM'
simulate(
  object,
  nsim = 1,
  seed = NULL,
  re.form = NULL,
  ntry = 5,
  full = FALSE,
  ...
)

Arguments

object

A fitted model object with class 'communityPGLMM'.

nsim

positive integer scalar - the number of responses to simulate.

seed

an optional seed to be used in set.seed immediately before the simulation so as to generate a reproducible sample.

re.form

(formula, NULL, or NA) specify which random effects to condition on when predicting. If NULL, include all random effects and the conditional modes of those random effects will be included in the deterministic part of the simulation (i.e Xb + Zu); if NA or ~0, condition on none of the random effects: new values of the random effects are drawn for each group with the estimated variances of random terms.

ntry

Number of times to retry simulation in the case of NA values. Only applies to models fit with bayes = TRUE. If there are still NAs after ntry times, the simulated values will be returned (with NAs) with a warning. If you keep getting NAs try rerunning with full = TRUE, which simulates in a slower but more stable way.

full

If TRUE, and the model was fit using bayes = TRUE, then the simulation will be done with an approximation of the full joint posterior (rather than the marginal posterior, which is the default). This method is much slower but is often more stable, and is technically more accurate.

...

optional additional arguments (none are used in .simulateFormula)

Examples

# community data: abundance of each species at each site
dat <- data.frame(
  site = rep(rownames(comm_a), times = ncol(comm_a)),
  sp = rep(colnames(comm_a), each = nrow(comm_a)),
  freq = unlist(comm_a, use.names = FALSE)
)
dat$shade <- envi$shade[match(dat$site, envi$site)]
phy <- ape::keep.tip(phylotree, unique(dat$sp))
fit <- pglmm(freq ~ shade + (1 | sp__) + (1 | site),
  data = dat, cov_ranef = list(sp = phy)
)

# conditional on the estimates of random effects: one column per simulation
sim <- simulate(fit, nsim = 3, seed = 1)
dim(sim)
head(sim)

# with new values of random effects, drawn with their estimated variances
sim <- simulate(fit, nsim = 3, seed = 1, re.form = NA)
head(sim)

Summary information of fitted model

Description

The variances of random terms that are printed are those of VarCorr(). For a term with a covariance matrix (e.g. 1|sp__) they are on the scale of the matrix standardized to have a determinant of one, so they are not directly comparable with the variances of other terms; multiply them by scale_factors of the fitted model first (see the Details of pglmm()).

Usage

## S3 method for class 'communityPGLMM'
summary(object, digits = max(3, getOption("digits") - 3), ...)

Arguments

object

A fitted model with class communityPGLMM.

digits

Minimal number of significant digits for printing, as in print.default.

...

Additional arguments, currently ignored.


Summary information of fitted pglmm_compare model

Description

Summary information of fitted pglmm_compare model

Usage

## S3 method for class 'pglmm_compare'
summary(object, digits = max(3, getOption("digits") - 3), ...)

Arguments

object

A fitted model with class pglmm_compare.

digits

Minimal number of significant digits for printing, as in print.default.

...

Additional arguments, currently ignored.


Example species traits data

Description

A data frame of species functional traits.

Usage

traits

Format

A data frame with 18 species and 3 variables: sla, height, and seed dispersal mode.


Extract variances of random terms

Description

Extract the variances of random terms

Usage

## S3 method for class 'communityPGLMM'
VarCorr(x, sigma = 1, ...)

Arguments

x

A fitted model with class communityPGLMM.

sigma

Ignored.

...

Ignored.

Details

Extract the estimated variances (and standard deviations) of the random terms from a fitted model. For Bayesian models, the credible intervals of the variances are also returned. Use ranef() to get the estimates for each level of the random terms.

Before version 1.3.0, this table was returned by ranef().

The variances are the elements s2r, s2n and s2resid of the fitted model. The variance of a term with a covariance matrix (e.g. a phylogenetic term such as 1|sp__) is on the scale of that matrix after it was standardized to have a determinant of one, which is usually much smaller than the scale of the phylogenetic correlation matrix, whereas terms without a covariance matrix (e.g. 1|sp) and the residual are not affected. The variances of different terms are therefore not directly comparable. Multiply them by scale_factors of the fitted model before comparing terms or comparing with other software (see "Extracting the variances of random terms" in the Details of pglmm(), and the examples below).

Value

A data frame with one row for each random term (and the residual for gaussian models), with columns Variance and Std.Dev.

See Also

ranef() for the estimates of each level of the random terms.

Examples

# community data: abundance of each species at each site
dat <- data.frame(
  site = rep(rownames(comm_a), times = ncol(comm_a)),
  sp = rep(colnames(comm_a), each = nrow(comm_a)),
  freq = unlist(comm_a, use.names = FALSE)
)
dat$shade <- envi$shade[match(dat$site, envi$site)]
phy <- ape::keep.tip(phylotree, unique(dat$sp))
fit <- pglmm(freq ~ shade + (1 | sp__) + (1 | site),
  data = dat, cov_ranef = list(sp = phy)
)

VarCorr(fit)
# variances on a comparable scale: rescale the terms whose covariance
# matrices were standardized (the phylogenetic term here)
v <- VarCorr(fit)
sf <- ifelse(rownames(v) == "residual", 1, fit$scale_factors[rownames(v)])
setNames(v$Variance * sf, rownames(v))
# proportion of the variance among species that is phylogenetic
v_sp <- v[c("1|sp", "1|sp__"), "Variance"] * fit$scale_factors[c("1|sp", "1|sp__")]
v_sp[2] / sum(v_sp)

Create phylogenetic var-cov matrix

Description

This function will convert a phylogeny to a Var-cov matrix.

Usage

vcv2(phy, corr = FALSE)

Arguments

phy

A phylogeny with "phylo" as class.

corr

Whether to return a correlation matrix instead of Var-cov matrix. Default is FALSE.

Value

A phylogenetic var-cov matrix.