rptProportion {rptR}

GLMM-based Repeatability Estimation for Proportion Data

Description

Estimates repeatability from a generalized linear mixed-effects models fitted by restricted maximum likelihood (REML).

Usage

rptProportion(formula, grname, data, link = c("logit", "probit"),
  CI = 0.95, nboot = 1000, npermut = 0, parallel = FALSE,
  ncores = NULL, ratio = TRUE, adjusted = TRUE, expect = "meanobs",
  rptObj = NULL, update = FALSE)

Arguments

formula

Formula as used e.g. by lmer. The grouping factor(s) of interest needs to be included as a random effect, e.g. '(1|groups)'. Covariates and additional random effects can be included to estimate adjusted repeatabilities.

grname

A character string or vector of character strings giving the name(s) of the grouping factor(s), for which the repeatability should be estimated. Spelling needs to match the random effect names as given in formula and terms have to be set in quotation marks. The reseved terms "Residual", "Overdispersion" and "Fixed" allow the estimation of overdispersion variance, residual variance and variance explained by fixed effects, respectively.

data

A dataframe that contains the variables included in the formula and grname arguments.

link

Link function. logit and probit are allowed, defaults to logit.

CI

Width of the required confidence interval between 0 and 1 (defaults to 0.95).

nboot

Number of parametric bootstraps for interval estimation (defaults to 1000). Larger numbers of bootstraps give a better asymtotic CI, but may be time-consuming. Bootstrapping can be switch off by setting nboot = 0. See also Details below.

npermut

Number of permutations used when calculating asymptotic p-values (defaults to 0). Larger numbers of permutations give a better asymtotic p-values, but may be time-consuming (in particular when multiple grouping factors are specified). Permutaton tests can be switch off by setting npermut = 0. See also Details below.

parallel

Boolean to express if parallel computing should be applied (defaults to FALSE). If TRUE, bootstraps and permutations will be distributed across multiple cores.

ncores

Specifying the number of cores to use for parallelization. On default, all but one of the available cores are used.

ratio

Boolean to express if variances or ratios of variance should be estimated. If FALSE, the variance(s) are returned without forming ratios. If TRUE (the default) ratios of variances (i.e. repeatabilities) are estimated.

adjusted

Boolean to express if adjusted or unadjusted repeatabilities should be estimated. If TRUE (the default), the variances explained by fixed effects (if any) will not be part of the denominator, i.e. repeatabilities are calculated after controlling for variation due to covariates. If FALSE, the varianced explained by fixed effects (if any) will be added to the denominator.

expect

A character string specifying the method for estimating the expectation in Poisson models with log link and in Binomial models with logit link (in all other cases the agrument is ignored). The only valid terms are 'meanobs' and 'latent' (and 'liability for binary and proportion data). With the default 'meanobs', the expectation is estimated as the mean of the observations in the sample. With 'latent', the expectation is estimated from estiamtes of the intercept and variances on the link scale. While this is a preferred solution, it is susceptible to the distribution of fixed effect covariates and gives appropriate results typically only when all covariances are centered to zero. With 'liability' estimates follow formulae as presented in Nakagawa & Schielzeth (2010). Liability estimates tend to be slightly higher.

rptObj

The output of a rptR function. Can be specified in combination with update = TRUE to update bootstraps and permutations

update

If TRUE, the rpt object to be updated has to be inputted with the rptObj argument. The function just updates the permutations and bootstraps, so make sure to specify all other arguments excactly like for the rpt object specified in rptObj.

Details

see details section of rpt for details on parametric bootstrapping, permutation and likelihood-ratio tests.

Value

Returns an object of class rpt that is a a list with the following elements:

call

Function call

datatype

Response distribution (here: 'Proportion').

CI

Width of the confidence interval.

R

data.frame with point estimates for repeatabilities. Columns represent grouping factors of interest. Rows show original and link scale repeatabilites (in this order).

se

data.frame with approximate standard errors (se) for repeatabilities. Columns are groups of interest. Rows are original and link scale (in this order). Note that the distribution might not be symmetrical, in which case the se is less informative.

CI_emp

list of two elements containing the confidence intervals for repeatabilities on the link and original scale, respectively. Within each list element, lower and upper CI are columns and each row for each grouping factor of interest.

P

data.frame with p-values from a significance test based on likelihood-ratios in the first column and significance test based on permutation of residuals for both the original and link scale in the second and third column. Each row represents a grouping factor of interest.

R_boot_link

Parametric bootstrap samples for R on the link scale. Each list element is a grouping factor.

R_boot_org

Parametric bootstrap samples for R on the original scale. Each list element is a grouping factor.

R_permut_link

Permutation samples for R on the link scale. Each list element is a grouping factor.

R_permut_org

Permutation samples for R on the original scale. Each list element is a grouping factor.

LRT

List of two elements. LRT_mod is the likelihood for the full model and (2) LRT_table is a data.frame for the reduced model(s) including columns for the likelihood logl_red, the likelihood ratio(s) LR_D, p-value(s)LR_P and degrees of freedom for the likelihood-ratio test(s) LR_df.

ngroups

Number of groups for each grouping level.

nobs

Number of observations.

overdisp

Overdispersion parameter. Equals the variance in the observational factor random effect

mod

Fitted model.

ratio

Boolean. TRUE, if ratios have been estimated, FALSE, if variances have been estimated

adjusted

Boolean. TRUE, if estimates are adjusted

all_warnings

list with two elements. 'warnings_boot' and 'warnings_permut' contain warnings from the lme4 model fitting of bootstrap and permutation samples, respectively.

Author(s)

Holger Schielzeth ([e-mail]), Shinichi Nakagawa ([e-mail]) & Martin Stoffel ([e-mail])

References

Carrasco, J. L. & Jover, L. (2003) Estimating the generalized concordance correlation coefficient through variance components. Biometrics 59: 849-858.

Faraway, J. J. (2006) Extending the linear model with R. Boca Raton, FL, Chapman & Hall/CRC.

Nakagawa, S. & Schielzeth, H. (2010) Repeatability for Gaussian and non-Gaussian data: a practical guide for biologists. Biological Reviews 85: 935-956

See Also

rpt

Examples

data(BeetlesMale)

# prepare proportion data
BeetlesMale$Dark <- BeetlesMale$Colour
BeetlesMale$Reddish <- (BeetlesMale$Colour-1)*-1
BeetlesColour <- aggregate(cbind(Dark, Reddish) ~ Treatment + Population + Container, 
     data=BeetlesMale, FUN=sum)

# Note: nboot and npermut are set to 0 for speed reasons. 

# repeatability with one grouping level
rptProportion(cbind(Dark, Reddish) ~ (1|Population), 
     grname=c("Population"), data=BeetlesColour, nboot=3, npermut=3)

# unadjusted repeatabilities with  fixed effects and 
# estimation of the fixed effect variance
rptProportion(cbind(Dark, Reddish) ~ Treatment + (1|Container) + (1|Population), 
     grname=c("Population", "Fixed"), 
     data=BeetlesColour, nboot=0, npermut=0, adjusted=FALSE)
                   
# variance estimation of random effects, residual and overdispersion 
rptProportion(cbind(Dark, Reddish) ~ Treatment + (1|Container) + (1|Population), 
     grname=c("Container","Population","Residual", "Overdispersion"), 
     data = BeetlesColour, nboot=0, npermut=0, ratio = FALSE)