nlive.smm {nlive}

Automated Estimation of the Sigmoidal Mixed Model

Description

The nlive.smm() function allows to fit a Sigmoidal Mixed Model with 4 parameters in the context of longitudinal Gaussian outcomes. This function was designed to be intuitive enough to the less sophisticated users, while using recent developments such as the stochastic approximation expectation-maximization (SAEM) algorithm for efficient estimation. It was designed to optimize the initial values of the main parameters and help interpretation of the output by providing different features such as annotated outputs and graphs.

Usage

nlive.smm(
  dataset,
  ID,
  outcome,
  time,
  var.all = NULL,
  var.first.level = NULL,
  var.last.level = NULL,
  var.midpoint = NULL,
  var.Hslope = NULL,
  start = NULL,
  plot.xlabel = NULL,
  plot.ylabel = NULL,
  traj.marg = FALSE,
  traj.marg.group = NULL,
  traj.marg.title = NULL,
  traj.marg.group.title = NULL,
  traj.marg.group.val = NULL
)

Arguments

dataset

data frame containing the variables ID, outcome, time, var.all, and all other var. arguments.

ID

name of the variable representing the grouping structure specified with " (e.g., "ID" representing the unique identifier of participants).

outcome

name of the time-varying variable representing the longitudinal outcome specified with " (e.g., "outcome").

time

name of the variable representing the timescale specified with " (e.g., "time"), which can be negative or positive.

var.all

optional vector indicating the name of the variable(s) that the four main parameters of the model will be adjusted to (e.g. var.all=c("X1","X2")). Default to NULL.

var.first.level

optional vector indicating the name of the variable(s) that the first level parameter of the model will be adjusted to (e.g. var.first.level=c("X1","X2")). Default to NULL.

var.last.level

optional vector indicating the name of the variable(s) that the last level parameter of the model of interest will be adjusted to (e.g. var.last.level=c("X1","X2")). Default to NULL.

var.midpoint

optional vector indicating the name of the variable(s) that the third main parameter of the model of interest will be adjusted to (e.g. var.midpoint=c("X1","X2"). Default to NULL.

var.Hslope

optional vector indicating the name of the variable(s) that the fourth main parameter of the model of interest will be adjusted to (e.g. var.Hslope=c("X1","X2")). Default to NULL.

start

optional vector to override the specification of the four initial values for the main parameters - values must be included in the following order: last level, initial level, midpoint, Hill slope. Default to NULL.

plot.xlabel

optional text for the title of the x-axis of all plots

plot.ylabel

optional text for the title of the y-axis of all plots

traj.marg

optional logical indicating if the marginal estimated trajectory should be plotted for the most common profile of covariates, if any. Default to FALSE.

traj.marg.group

optional name of the grouping variable listed in one of the predictor arguments to plot and contrast the estimated marginal trajectories between two specific groups, specified with " (e.g., traj.marg.group="X1"). If the variable is binary, the trajectories are contrasted between the two groups of interest. If the variable is continuous, the 10th and 90th percentile values will automatically be considered. The default value is NULL.

traj.marg.title

optional text for the title of the marginal estimated trajectory

traj.marg.group.title

optional text for the title of the marginal estimated trajectories contrasted between groups

traj.marg.group.val

optional vector that can be used when traj.marg.group receives a quantitative variable and that allows to manually specify two percentile values to be considered for contrasting the traj.marg.group. The two values must be between 0 and 1 (e.g., traj.marg.group.val=c(0.2,0.8); for percentiles 20th and 80th). Default to 10th and 90th percentiles (i.e., traj.marg.group.val=c(0.1,0.9)).

Details

CAUTIONS REGARDING THE USE OF THE FUNCTION

traj.marg: if "TRUE", this argument automatically plots the estimated marginal trajectories of the longitudinal outcome for the most common profile of covariates, if any (i.e., ref "1" for binary variables and mean values for continuous variables). Thus, users must ensure that continuous variables are centered on the mean.

Value

An object of class SaemixObject (from the existing saemix R package) containing the results of the fit of the data by the SMM. The nlive.smm function automatically provides the standard saemix output, including the fixed effects estimates, the variance of random effects, and Likelihood of the fitted model. The outputs are printed on the terminal and the numerical and graphical outputs are stored in a directory.

Author(s)

Maude Wagner, Ana W. Capuano, Emmanuelle Comets

[e-mail]

References

Capuano AW, Wagner M. nlive: an R package to facilitate the application of the sigmoidal and random changepoint mixed models. BMC Medical Research Methodology. 2023;23(1):257. van den Hout A, Muniz-Terrera G, Matthews F. Smooth random change point models. Statistics in Medicine. 2011;30(6):599-610. Comets E, Lavenu A, Lavielle MM. Parameter estimation in nonlinear mixed effect models using saemix, an R implementation of the SAEM algorithm. Journal of Statistical Software. 2017;80(3):1-41.

Examples

#### Fitting a sigmoidal mixed model - with no covariate
## Not run: 
head(dataCog)
requireNamespace('nlraa')
smm.fit = nlive.smm(dataset=dataCog, ID="ID", outcome="cognition", time="time")

## End(Not run)
#### plot(smm.fit): diagnostic plots to assess the goodness-of-fit of smm.fit
#### psi(smm.fit): estimates of individual parameters