fit_lmms {pencal}

Step 1 of PRC-LMM (estimation of the linear mixed models)

Description

This function performs the first step for the estimation of the PRC-LMM model proposed in Signorelli et al. (2021)

Usage

fit_lmms(y.names, fixefs, ranefs, long.data, surv.data, t.from.base,
  n.boots = 0, n.cores = 1, max.ymissing = 0.2, verbose = TRUE,
  seed = 123, control = list(opt = "optim", niterEM = 500, maxIter = 500))

Arguments

y.names

character vector with the names of the response variables which the LMMs have to be fitted to

fixefs

fixed effects formula for the model, example: ~ time

ranefs

random effects formula for the model, specified using the representation of random effect structures of the R package nlme

long.data

a data frame with the longitudinal predictors, comprehensive of a variable called id with the subject ids

surv.data

a data frame with the survival data and (if relevant) additional baseline covariates. surv.data should at least contain a subject id (called id), the time to event outcome (time), and binary event variable (event)

t.from.base

name of the variable containing time from baseline in long.data

n.boots

number of bootstrap samples to be used in the cluster bootstrap optimism correction procedure (CBOCP). If 0, no bootstrapping is performed

n.cores

number of cores to use to parallelize part of the computations. If ncores = 1 (default), no parallelization is done. Pro tip: you can use parallel::detectCores() to check how many cores are available on your computer

max.ymissing

maximum proportion of subjects allowed to not have any measurement of a longitudinal response variable. Default is 0.2

verbose

if TRUE (default and recommended value), information on the ongoing computations is printed in the console

seed

random seed used for the bootstrap sampling. Default is seed = 123

control

a list of control values to be passed to lme when fitting the linear mixed models. By default, we set opt = 'optim', niterEM = 500, maxIter = 500. See ?nlme::lmeControl for all possible arguments and values

Value

A list containing the following objects:

• call.info: a list containing the following function call information: call, y.names, fixefs, ranefs;

• lmm.fits.orig: a list with the LMMs fitted on the original dataset (it should comprise as many LMMs as the elements of y.names are);

• df.sanitized: a sanitized version of the supplied long.data dataframe, without the longitudinal measurements that are taken after the event or after censoring;

• n.boots: number of bootstrap samples;

• boot.ids: a list with the ids of bootstrapped subjects (when n.boots > 0);

• lmms.fits.boot: a list of lists, which contains the LMMs fitted on each bootstrapped datasets (when n.boots > 0).

Author(s)

Mirko Signorelli

References

Signorelli, M. (2024). pencal: an R Package for the Dynamic Prediction of Survival with Many Longitudinal Predictors. To appear in: The R Journal. Preprint: arXiv:2309.15600

Signorelli, M., Spitali, P., Al-Khalili Szigyarto, C, The MARK-MD Consortium, Tsonaka, R. (2021). Penalized regression calibration: a method for the prediction of survival outcomes using complex longitudinal and high-dimensional data. Statistics in Medicine, 40 (27), 6178-6196. DOI: 10.1002/sim.9178

See Also

simulate_prclmm_data, summarize_lmms (step 2), fit_prclmm (step 3), performance_prc

Examples

# generate example data
set.seed(1234)
p = 4 # number of longitudinal predictors
simdata = simulate_prclmm_data(n = 100, p = p, p.relev = 2, 
             seed = 123, t.values = c(0, 0.2, 0.5, 1, 1.5, 2))
 
# specify options for cluster bootstrap optimism correction
# procedure and for parallel computing 
do.bootstrap = FALSE
# IMPORTANT: set do.bootstrap = TRUE to compute the optimism correction!
n.boots = ifelse(do.bootstrap, 100, 0)
more.cores = FALSE
# IMPORTANT: set more.cores = TRUE to parallelize and speed computations up!
if (!more.cores) n.cores = 1
if (more.cores) {
   # identify number of available cores on your machine
   n.cores = parallel::detectCores()
   if (is.na(n.cores)) n.cores = 8
}

# step 1 of PRC-LMM: estimate the LMMs
y.names = paste('marker', 1:p, sep = '')
step1 = fit_lmms(y.names = y.names, 
                 fixefs = ~ age, ranefs = ~ age | id, 
                 long.data = simdata$long.data, 
                 surv.data = simdata$surv.data,
                 t.from.base = t.from.base,
                 n.boots = n.boots, n.cores = n.cores)
# estimated betas and variances for the 3rd marker:
summary(step1, 'marker3', 'betas')
summary(step1, 'marker3', 'variances')
# usual T table:
summary(step1, 'marker3', 'tTable')