rptR (version 0.9.22)

rptGaussian: LMM-based Repeatability Estimation for Gaussian Data

Description

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

Usage

rptGaussian(formula, grname, data, CI = 0.95, nboot = 1000,
  npermut = 0, parallel = FALSE, ncores = NULL, ratio = TRUE,
  adjusted = TRUE, 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.

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.

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.

Value

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

call

Function call.

datatype

Response distribution (here: 'Gaussian').

CI

Coverage of the confidence interval as specified by the CI argument.

R

data.frame with point estimates for repeatabilities for each grouping factor of interest.

se

data.frame with approximate standard errors (se) for repeatabilities. Rows repsresent grouping factors of interest. Note that the distribution might not be symmetrical, in which case the se is less informative.

CI_emp

data.frame containing the (empirical) confidence intervals for the repeatabilities estiamted based parametric bootstrapping. Each row represents a grouping factor of interest.

P

data.frame with p-values based on likelihood-ratio tests (first column) and permutation tests (second column). Each row represents a grouping factor of interest.

R_boot

Vector(s) of parametric bootstrap samples for R. Each list element respesents a grouping factor.

R_permut

Vector(s) of permutation samples for R. Each list element represents a grouping factor.

LRT

list with two elements. (1) The likelihood for the full model and a data.frame called LRT_table for the reduced model(s), which includes columns for the respective grouping factor(s), the likelihood(s) logL_red, likelihood ratio(s) LR_D, p-value(s) LRT_P and degrees of freedom LRT_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.

Details

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

References

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

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

# NOT RUN {
 

data(BeetlesBody)

# Note: nboot and npermut are set to 3 for speed reasons. Use larger numbers
# for the real analysis.

# one random effect
rpt_est <- rptGaussian(BodyL ~ (1|Population), grname="Population", 
                   data=BeetlesBody, nboot=3, npermut=3, ratio = FALSE)

# two random effects
rptGaussian(BodyL ~ (1|Container) + (1|Population), grname=c("Container", "Population"), 
                   data=BeetlesBody, nboot=3, npermut=3)
                   
# unadjusted repeatabilities with fixed effects and 
# estimation of the fixed effect variance
rptGaussian(BodyL ~ Sex + Treatment + Habitat + (1|Container) + (1|Population), 
                  grname=c("Container", "Population", "Fixed"), 
                  data=BeetlesBody, nboot=3, npermut=3, adjusted=FALSE)
                  
                  
# two random effects, estimation of variance (instead repeatability)
R_est <- rptGaussian(formula = BodyL ~ (1|Population) + (1|Container), 
            grname= c("Population", "Container", "Residual"),
            data=BeetlesBody, nboot=3, npermut=3, ratio = FALSE)

# }