TElmem: Linear mixed-effects model with nonlinear time random effects

In akcochrane/TEfits: Time-evolving model fits

Linear mixed-effects model with nonlinear time random effects

Description

Fits a lmer linear mixed-effects model with the random effects of timeVar for each level of groupingVar. Provides estimates of time-related change (i.e., attempts to answer the question "how different was the start than the end?").

Usage

TElmem(
  formIn,
  dat,
  timeVar,
  groupingVar,
  nRuns = 5,
  startingOffset = T,
  silent = F
)

Arguments

formIn	model formula, as in lmer
dat	model data, as in lmer
timeVar	String. Indicates which variable in datIn corresponds to time (i.e., should be transformed). Must be numeric and positive.
groupingVar	String. Indicates which variable in datIn should have a time=related random effect.
nRuns	Number of times to run optimization of the rate (i.e., fitting nonlinear transformations of timeVar)
startingOffset	By default (if T) time is coded to start at 1 and saturate to 0. If startingOffset is F, time starts at 0 and saturates to 1. May assist in interpreting interactions with other variables, etc.
silent	Progress is printed by default. silent=T to suppress

Details

First uses TElm to find a rate parameter for each level of groupingVar, with the formula extracted using tef_getRanefForm. These rate parameters are used to transform the corresponding timeVar into a exponentially saturating variable (see TElm). After finding an initial set of rate parameters using TElm, TElmem attempts to optimize the vector of rate parameters in conjunction with the full lmer model.

May be used, with nRuns=0, to simply use rate estimates from independent groupingVar-level TElm models, extracting the corresponding transformed time variables, and using them in a LMEM.

Value

A list including:

lmerMod

lmer model fit with transformed time variable

rates

Named vector of rates [50-percent-of-change time constants]

timeDat

Data frame with original and transformed time variable

groupMods

List of fit TElm models, and the corresponding transformed time variable and named vector of rates

Note

Random effects and rate estimates may be unstable, and optimization may take a very long time to run. The primary purpose of this function is to allow for by-groupingVar detrending of time-related changes in data (i.e., to estimate and test fixed effects at asymptotic time, or to estimate and test the magnitude of time-related effects). If reliable by-groupingVar parameters are desired, especially of rate, it is highly recommended to use TEbrm.

The formIn must include a random effect of timeVar by groupingVar (e.g., (time_variable | grouping_variable))

Examples

## Not run: 
m_TElmem <- TElmem(acc ~ trialNum + (trialNum || subID), anstrain, timeVar = 'trialNum',groupingVar = 'subID')
# Typical lmer model:
summary(m_TElmem$lmerMod) # On average, starting accuracy was .137 worse than asymptotic accuracy
# Participant-level rate parameters:
m_TElmem$rates

## End(Not run)

akcochrane/TEfits documentation built on June 12, 2025, 11:10 a.m.