auto_by {quest}

Autoregressive Coefficient by Group

Description

auto_by computes the autoregressive coefficient by group for longitudinal data where each observation within the group represents a different timepoint. The function assumes the data are already sorted by time.

Usage

auto_by(
  x,
  grp,
  n = -1L,
  how = "cor",
  cw = TRUE,
  method = "pearson",
  use = "na.or.complete",
  REML = TRUE,
  control = NULL,
  sep = "."
)

Arguments

x

numeric vector.

grp

list of atomic vector(s) and/or factor(s) (e.g., data.frame), which each have same length as x. It can also be an atomic vector or factor, which will then be made the first element of a list.

n

integer vector with length 1. Specifies the direction and magnitude of the shift. See shift for details. The default is -1L, which is a one-lag autoregressive coefficient' +2L would be a two-lead autoregressive coefficient. The sign of n only affects the results for how = "lm", "lme", or "lmer".

how

character vector of length 1 specifying how to compute the autoregressive coefficients. The options are 1) "cor" for correlation with the cor function, 2) "cov" for covariance with the cov function, 3) "lm" for the linear regression slope with the lm function, 4) "lme" for empirical Bayes estimates from a linear mixed effects model with the lme function, 5) "lmer" for empirical Bayes estimates from a linear mixed effects model with the lmer function.

cw

logical vector of length 1 specifying whether the shifted vector should be group-mean centered (TRUE) or not (FALSE). This only affects the results for how = "lme" or "lmer".

method

character vector of length 1 specifying the type of correlation or covariance to compute. Only used when how = "cor" or "cov". See cor for details.

use

character vector of length 1 specifying how to handle missing data. Only used when how = "cor" or "cov". See cor for details.

REML

logical vector of length 1 specifying whether to use restricted estimated maximum liklihood (TRUE) rather than traditional maximum likelihood (FALSE). Only used when how = "lme" or "lmer".

control

list of control parameters for lme or lmer when how = "lme" or "lmer", respectively. See lmeControl and lmerControl for details.

sep

character vector of length 1 specifying what string should separate different group values when naming the return object. This argument is only used if grp is a list of atomic vectors (e.g., data.frame).

Details

There are several different ways to estimate the autoregressive parameter. This function offers a variety of ways with the how and cw arguments. Note, that a recent simulation suggests that group-mean centering via cw is the best approach when using linear mixed effects modeling via how = "lme" or "lmer" (Hamaker & Grasman, 2015).

Value

numeric vector of autoregressive coefficients with length = length(levels(interaction(grp))) and names = pasteing of the grouping value(s) together separated by sep.

References

Hamaker, E. L., & Grasman, R. P. (2015). To center or not to center? Investigating inertia with a multilevel autoregressive model. Frontiers in Psychology, 5, 1492.

Examples

# cor
auto_by(x = airquality$"Ozone", grp = airquality$"Month", how = "cor")
auto_by(x = airquality$"Ozone", grp = airquality$"Month",
   n = -2L, how = "cor") # lag across 2 timepoints
auto_by(x = airquality$"Ozone", grp = airquality$"Month",
   n = +1L, how = "cor") # lag and lead identical for cor
auto_by(x = airquality$"Ozone", grp = airquality$"Month", how = "cor",
   cw = FALSE) # centering within-person identical for cor

# cov
auto_by(x = airquality$"Ozone", grp = airquality$"Month", how = "cov")
auto_by(x = airquality$"Ozone", grp = airquality$"Month",
   n = -2L, how = "cov") # lag across 2 timepoints
auto_by(x = airquality$"Ozone", grp = airquality$"Month",
   n = +1L, how = "cov") # lag and lead identical for cov
auto_by(x = airquality$"Ozone", grp = airquality$"Month", how = "cov",
   cw = FALSE) # centering within-person identical for cov

# lm
auto_by(x = airquality$"Ozone", grp = airquality$"Month", how = "lm")
auto_by(x = airquality$"Ozone", grp = airquality$"Month",
   n = -2L, how = "lm") # lag across 2 timepoints
auto_by(x = airquality$"Ozone", grp = airquality$"Month",
   n = +1L, how = "lm") # lag and lead NOT identical for lm
auto_by(x = airquality$"Ozone", grp = airquality$"Month", how = "lm",
   cw = FALSE) # centering within-person identical for lm

# lme
chick_weight <- as.data.frame(ChickWeight)
auto_by(x = chick_weight$"weight", grp = chick_weight$"Chick", how = "lme")
control_lme <- nlme::lmeControl(maxIter = 250L, msMaxIter = 250L,
   tolerance = 1e-3, msTol = 1e-3) # custom controls
auto_by(x = chick_weight$"weight", grp = chick_weight$"Chick", how = "lme",
   control = control_lme)
auto_by(x = chick_weight$"weight", grp = chick_weight$"Chick",
   n = -2L, how = "lme") # lag across 2 timepoints
auto_by(x = chick_weight$"weight", grp = chick_weight$"Chick",
   n = +1L, how = "lme") # lag and lead NOT identical for lme
auto_by(x = chick_weight$"weight", grp = chick_weight$"Chick", how = "lme",
   cw = FALSE) # centering within-person NOT identical for lme

# lmer
bryant_2016 <- as.data.frame(lmeInfo::Bryant2016)
## Not run: 
auto_by(x = bryant_2016$"outcome", grp = bryant_2016$"case", how = "lmer")
control_lmer <- lme4::lmerControl(check.conv.grad = lme4::.makeCC("stop",
   tol = 2e-3, relTol = NULL), check.conv.singular = lme4::.makeCC("stop",
   tol = formals(lme4::isSingular)$"tol"), check.conv.hess = lme4::.makeCC(action = "stop",
   tol = 1e-6)) # custom controls
auto_by(x = bryant_2016$"outcome", grp = bryant_2016$"case", how = "lmer",
   control = control_lmer) # TODO: for some reason lmer doesn't like this
   # and is not taking into account the custom controls
auto_by(x = bryant_2016$"outcome", grp = bryant_2016$"case",
   n = -2L, how = "lmer") # lag across 2 timepoints
auto_by(x = bryant_2016$"outcome", grp = bryant_2016$"case",
   n = +1L, how = "lmer") # lag and lead NOT identical for lmer
auto_by(x = bryant_2016$"outcome", grp = bryant_2016$"case", how = "lmer",
   cw = FALSE) # centering within-person NOT identical for lmer

## End(Not run)