rptPoisson: GLMM-based Repeatability Estimation for Poisson-distributed...

In mastoffel/rptR: Repeatability Estimation for Gaussian and Non-Gaussian Data

Description

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

Usage

rptPoisson(formula, grname, data, link = c("log", "sqrt"), 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.
...	Other parameters for the lmer or glmer call, such as optimizers.

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: 'Poisson').
CI	Coverage of the confidence interval as specified by the CI argument.
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.
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

# load data
data(BeetlesFemale)

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

# estimating adjusted repeatabilities for two random effects
rptPoisson(Egg ~ Treatment + (1|Container) + (1|Population), 
                   grname=c("Container", "Population"), 
                   data = BeetlesFemale, nboot=0, npermut=0)

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

mastoffel/rptR documentation built on Aug. 7, 2021, 2 a.m.