TEglmem: Generalized linear mixed-effects model with nonlinear time...

In akcochrane/TEfits: Time-evolving model fits

Generalized linear mixed-effects model with nonlinear time random effects

Description

Fits a glmer generalized 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

TEglmem(
  formIn,
  dat,
  timeVar,
  groupingVar,
  family = gaussian,
  startingOffset = T,
  nRuns = 5,
  silent = F
)

Arguments

formIn	model formula, as in glmer
dat	model data, as in glmer
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.
family	model family, as in glmer
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.
nRuns	Number of times to run optimization of the rate (i.e., fitting nonlinear transformations of timeVar)
silent	Progress is printed by default. silent=T to suppress

Details

First uses TEglm 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 TEglm). After finding an initial set of rate parameters using TEglm, TEglmem attempts to optimize the vector of rate parameters in conjunction with the full glmer model.

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

Value

A list including:

glmerMod

glmer model fit with transformed time variable

rates

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

timeDat

Data frame with original and transformed time variable

groupMods

List of fit TEglm 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, it is highly recommended to use TEbrm.

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

Although the time variable is transformed to exponentially decay from one toward zero (or, if startingOffset=F, from zero toward one), this does not necessarily mean that the model prediction involves an exponential change with time. The nonlinear change in time relates to the time-associated model coefficients.

Examples

## Not run: 
m_TEglmem <- TEglmem(resp ~ ratio + trialNum:ratio + (ratio + trialNum:ratio || subID),anstrain, timeVar = 'trialNum',groupingVar = 'subID',family=binomial)
# Typical glmer model:
summary(m_TEglmem$glmerMod)
# Participant-level rate parameters:
m_TEglmem$rates

## End(Not run)

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