CorrMixed (version 1.0)

WS.Corr.Mixed: Estimate within-subject correlations (reliabilities) based on a mixed-effects model.

Description

This function allows for the estimation of the within-subject correlations using a general and flexible modeling approach that allows at the same time to capture hierarchies in the data, the presence of covariates, and the derivation of correlation estimates. Non-parametric bootstrap-based confidence intervals can be requested.

Usage

WS.Corr.Mixed(Dataset, Fixed.Part=" ", Random.Part=" ", 
Correlation=" ", Id, Time=Time, Model=1, 
Number.Bootstrap=100, Alpha=.05, Seed=1)

Arguments

Dataset

A data.frame that should consist of multiple lines per subject ('long' format).

Fixed.Part

The outcome and fixed-effect part of the mixed-effects model to be fitted. The model should be specified in agreement with the lme function requirements of the nlme package. See examples below.

Random.Part

The random-effect part of the mixed-effects model to be fitted (specified in line with the lme function requirements). See examples below.

Correlation

An optional object describing the within-group correlation structure (specified in line with the lme function requirements). See examples below.

Id

The subject indicator.

Time

The time indicator. Default Time=Time.

Model

The type of model that should be fitted. Model=1: random intercept model, Model=2: random intercept and Gaussian serial correlation, and Model=3: random intercept, slope, and Gaussian serial correlation. Default Model=1.

Number.Bootstrap

The number of bootstrap samples to be used to estimate the Confidence Intervals around \(R\). Default Number.Bootstrap=100. As an alternative to obtain confidence intervals, the Delta method can be used (see WS.Corr.Mixed.SAS).

Alpha

The \(\alpha\)-level to be used in the bootstrap-based Confidence Interval for \(R\). Default \(Alpha=0.05\)

Seed

The seed to be used in the bootstrap. Default \(Seed=1\).

Value

Model

The type of model that was fitted (model \(1\), \(2\), or \(3\).)

D

The \(D\) matrix of the fitted model.

Tau2

The \(\tau^2\) component of the fitted model. This component is only obtained when serial correlation is requested (Model \(2\) or \(3\)), \(\varepsilon_{2} \sim N(0, \tau^2 H_{i}))\).

Rho

The \(\rho\) component of the fitted model which determines the matrix \(H_{i}\), \(\rho(|t_{ij}-t_{ik}|)\). This component is only obtained when serial correlation is considered (Model \(2\) or \(3\)).

Sigma2

The residual variance.

AIC

The AIC value of the fitted model.

LogLik

The log likelihood value of the fitted model.

R

The estimated reliabilities.

CI.Upper

The upper bounds of the bootstrapped confidence intervals.

CI.Lower

The lower bounds of the bootstrapped confidence intervals.

Alpha

The \(\alpha\) level used in the estimation of the confidence interval.

Coef.Fixed

The estimated fixed-effect parameters.

Std.Error.Fixed

The standard errors of the fixed-effect parameters.

Time

The time values in the dataset.

Fitted.Model

A fitted model of class lme.

Details

Warning 1

To avoid problems with the lme function, do not specify powers directly in the function call. For example, rather than specifying Fixed.Part=ZSV ~ Time + Time**2 in the function call, first add Time**2 to the dataset (Dataset$TimeSq <- Dataset$Time ** 2) and then use the new variable name in the call: Fixed.Part=ZSV ~ Time + TimeSq

Warning 2 To avoid problems with the lme function, specify the Random.Part and Correlation arguments like e.g., Random.Part = ~ 1| Subject and Correlation=corGaus(form= ~ Time, nugget = TRUE)

not like e.g., Random.Part = ~ 1| Subject and Correlation=corGaus(form= ~ Time| Subject, nugget = TRUE)

(i.e., do not use Time| Subject)

References

Van der Elst, W., Molenberghs, G., Hilgers, R., & Heussen, N. (2015). Estimating the reliability of repeatedly measured endpoints based on linear mixed-effects models. A tutorial. Submitted.

See Also

Explore.WS.Corr, WS.Corr.Mixed.SAS

Examples

# NOT RUN {
# open data
data(Example.Data)

# Make covariates used in mixed model
Example.Data$Time2 <- Example.Data$Time**2
Example.Data$Time3 <- Example.Data$Time**3
Example.Data$Time3_log <- (Example.Data$Time**3) * (log(Example.Data$Time))

# model 1: random intercept model
Model1 <- WS.Corr.Mixed(
Fixed.Part=Outcome ~ Time2 + Time3 + Time3_log + as.factor(Cycle) 
+ as.factor(Condition), Random.Part = ~ 1|Id, 
Dataset=Example.Data, Model=1, Id="Id", Number.Bootstrap = 50, 
Seed = 12345)

  # summary of the results
summary(Model1)
  # plot the results
plot(Model1)

# }
# NOT RUN {
time-consuming code parts
# model 2: random intercept + Gaussian serial corr
Model2 <- WS.Corr.Mixed(
Fixed.Part=Outcome ~ Time2 + Time3 + Time3_log + as.factor(Cycle) 
+ as.factor(Condition), Random.Part = ~ 1|Id, 
Correlation=corGaus(form= ~ Time, nugget = TRUE),
Dataset=Example.Data, Model=2, Id="Id", Seed = 12345)

  # summary of the results
summary(Model2)

  # plot the results
    # estimated corrs as a function of time lag (default plot)
plot(Model2)
    # estimated corrs for all pairs of time points
plot(Model2, All.Individual = T)

# model 3
Model3 <- WS.Corr.Mixed(
  Fixed.Part=Outcome ~ Time2 + Time3 + Time3_log + as.factor(Cycle) 
  + as.factor(Condition), Random.Part = ~ 1 + Time|Id, 
  Correlation=corGaus(form= ~ Time, nugget = TRUE),
  Dataset=Example.Data, Model=3, Id="Id", Seed = 12345)

  # summary of the results
summary(Model3)

  # plot the results
    # estimated corrs for all pairs of time points
plot(Model3)
    # estimated corrs as a function of time lag
# }