Type:	Package
Title:	Multivariate Joint Modeling for Longitudinal and Time-to-Event Outcomes with 'INLA'
Version:	24.3.25
Description:	Estimation of joint models for multivariate longitudinal markers (with various distributions available) and survival outcomes (possibly accounting for competing risks) with Integrated Nested Laplace Approximations (INLA). The flexible and user friendly function joint() facilitates the use of the fast and reliable inference technique implemented in the 'INLA' package for joint modeling. More details are given in the help page of the joint() function (accessible via ?joint in the R console) and the vignette associated to the joint() function (accessible via vignette("INLAjoint") in the R console).
License:	GPL-3
URL:	https://github.com/DenisRustand/INLAjoint
BugReports:	https://github.com/DenisRustand/INLAjoint/issues
Encoding:	UTF-8
LazyData:	true
Depends:	R (≥ 3.6), utils, stats
Imports:	numDeriv, lme4, ggplot2, methods, Matrix, nlme, mvtnorm
Additional_repositories:	https://inla.r-inla-download.org/R/testing
RoxygenNote:	7.3.1
Suggests:	INLA, knitr, rmarkdown, splines, graphics, grDevices, R.rsp, survival, JMbayes2, rstanarm, frailtypack, smcure
BuildVignettes:	true
VignetteBuilder:	R.rsp
Maintainer:	Denis Rustand <INLAjoint@gmail.com>
NeedsCompilation:	no
Packaged:	2024-03-25 08:20:45 UTC; dr
Author:	Denis Rustand [cre, aut], Elias Teixeira Krainski [aut], Haavard Rue [aut], Janet van Niekerk [aut]
Repository:	CRAN
Date/Publication:	2024-03-25 19:50:02 UTC

INLAjoint

Description

INLAjoint is a package that fits joint models for multivariate longitudinal markers (with various distributions available) and survival outcomes (possibly accounting for competing risks) with Integrated Nested Laplace Approximations (INLA). The flexible and user friendly function joint() facilitates the use of the fast and reliable inference technique implemented in INLA package for joint modeling. More details are given in the help page of the joint function (accessible via ?joint in the R console), the vignette associated to the joint() function (accessible via vignette("INLAjoint") in the R console).

Contact: INLAjoint@gmail.com

Usage

INLAjoint()

Setup ginv

Description

Setup random walk input:

Usage

INLAjoint.ginv(x, tol = sqrt(.Machine$double.eps), rankdef = NULL)

Arguments

Value

ginv

Fitted joint object

Description

An object of class INLAjoint returned by the joint function that fits a joint model to multivariate longitudinal and time-to-event data. The following functions can apply to objects of this class: plot, print, summary and priors.used.

Usage

INLAjoint.object

Format

An object of class NULL of length 0.

Value

A list with the following components:

names.fixed

a vector with the name of the fixed effects of the model. The corresponding submodel is indicated by the suffix including a letter and a number ("L" for longitudinal and "S" for survival).

summary.fixed

summary statistics for the fixed effects of the model. The summary statistics sorted by longitudinal and survival components are available by applying the summary function to the INLAjoint object.

summary.fixed

marginals for the fixed effects of the model.

mlik

log marginal-likelihood.

cpo

Conditional Predictive Ordinate.

gcpo

Group-Conditional Predictive Ordinate.

po

Predictive ordinate.

waic

Widely applicable Bayesian information criterion

model.random

a vector with the name of the random parameters of the model, possibly including the following components:

RW1 model and RW2 model

Random walk of order 1 or 2 corresponding to Bayesian smoothing splines for the baseline hazard risk

IID model

Univariate random effect.

IIDKD model

Multivariate random effects.

Copy

association parameter.

summary.random

summary statistics for the random parameters of the model.

marginals.random

marginals for the random parameters of the model.

size.random

size of the random parameters of the model.

summary.linear.predictor

summary statistics of the linear predictors.

marginals.linear.predictor

marginals for the linear predictors.

summary.fitted.values

summary statistics of the fitted values.

marginals.fitted.values

marginals for the fitted values.

size.linear.predictor

size of the linear predictors.

summary.hyperpar

summary statistics for the hyperparameters of the model. The summary statistics sorted by longitudinal and survival components are available by applying the summary function to the INLAjoint object. Particularly, this is the raw output of INLA and therefore the precision of the residual errors and baseline hazard functions hyperparameters are provided. Similarly, the Cholesky matrix is given for the random-effects. The summary function can easily return either variance and covariance or standard deviations and correlations for all these hyperparameters.

marginals.hyperpar

marginals for the hyperparameters of the model.

internal.summary.hyperpar

summary of the internal hyperparameters, this is similar to the summary of the hyperparameters but here they are provided as used for the computations (logarithm scale for residual error and baseline risk hyperparameters).

internal.marginals.hyperpar

marginals for the internal hyperparameters of the model.

misc

miscellaneous (as provided in the INLA output).

dic

Deviance Information Criterion.

mode

.

joint.hyper

.

nhyper

.

version

Version of INLA.

cpu.used

Computation time of INLA.

all.hyper

.

.args

.

call

INLA call.

selection

information about parameters for sampling with inla.rjmarginal.

cureVar

informations about cure fraction submodel for mixture cure survival models.

variant

information about variant for Weibull baseline hazards.

SurvInfo

some information about survival submodels (names of event indicator and event time variables as well as baseline hazard).

famLongi

list of distributions for the longitudinal markers.

corLong

boolean indicating if random effects are correlated accross markers.

control.link

informations about link function (1=default).

longOutcome

name of longitudinal outcomes.

survOutcome

name of survival outcomes.

assoc

vector with names of all association parameters (longi-surv).

id

name of the id variable.

timeVar

name of time variable.

range

information about range of X-axis values for non-linear associations.

REstruc

names of the grouped random effects for the longitudinal markers.

mat_k

contains the list of random effects covariance matrices when they are fixed as they are not part of the estimated parameters (used for displaying them in summary).

fixRE

list of the size of number of groups of random effects, each element is a boolean indicating if the random effects of the group is fixed (TRUE) or estimated (FALSE).

lonFacChar

list of factors and character covariates included in the longitudinal submodels to keep track of modalities (used internally when doing predictions to reconstruct categorical covariates).

survFacChar

same as lonFacChar but for survival submodels.

corRE

list indicating if groups of random effects are correlated within longitudinal submodels.

basRisk

list of the baseline risk used for each survival submodel.

priors_used

informations about priors used in the model, internally used to display priors in plots (with argument priors=TRUE in the call of the plot function). Note that priors can also be displayed with the function priors.used() applied to an INLAjoint object.

dataLong

name of the longitudinal dataset.

dataSurv

name of the survival dataset.

See Also

joint.

Setup rw

Description

Setup random walk input:

Usage

INLAjoint.rw(n, order = 1L, sparse = TRUE, scale.model = FALSE, cyclic = FALSE)

Arguments

Value

random walk 1

Setup rw2

Description

Setup random walk of order 2 input:

Usage

INLAjoint.rw2(n, order = 2L, ...)

Arguments

Value

random walk 2

Setup scopy

Description

Setup weights for non-linear effects input:

Usage

INLAjoint.scopy.define(n = 5L)

Arguments

Value

Matrix with weights for scopy

Simulated univariate longitudinal dataset

Description

A simulated dataset used to illustrate joint models with univariate longitudinal and multi-state survival component (see joint longitudinal and multi-state model in INLAjoint vignette). The corresponding survival dataset is named 'SurvMS'.

Usage

LongMS

Format

## 'LongMS' A data frame with 96 rows and 7 columns:

id

Individual id

time

Visit times

X

Continuous covariate

y

Gaussian longitudinal outcome

...

Simulated multivariate longitudinal dataset

Description

A simulated dataset used to illustrate some models (e.g., example of joint() function in the documentation). The corresponding survival dataset is named 'Survsim'.

Usage

Longsim

Format

## 'Longsim' A data frame with 96 rows and 7 columns:

Id

Individual id

time

Visit times

ctsX

Continuous covariate

binX

Binary covariate

Y1, Y2, Y3

Gaussian Longitudinal outcomes

...

Simulated multi-state survival dataset

Description

A simulated dataset used to illustrate multi-state models (see multi-state model and joint longitudinal and multi-state model in INLAjoint vignette). The corresponding longitudinal dataset is named 'LongMS'.

Usage

SurvMS

Format

## 'SurvMS' A list of 3 data frames with 50 rows and 5 columns, 50 rows and 5 columns, 28 rows and 5 columns for each of the 3 transition intensities, respectively:

id

Individual id

Tstart

Beginning of the 'at-risk' period

Tstop

Event time

status

Transition indicator

X

Continuous covariate

...

Simulated competing risks survival dataset

Description

A simulated dataset used to illustrate some models (e.g., example of joint() function in the documentation). The corresponding longitudinal dataset is named 'Longsim'.

Usage

Survsim

Format

## 'Survsim' A data frame with 15 rows and 5 columns:

Id

Individual id

deathTimes

Event time

ctsX

Continuous covariate

binX

Binary covariate

Event1, Event2, Event3

Event indicator for the 3 competing risks (individual is censored when the 3 events are 0)

...

Extracts model coefficients from a given model fitted with INLAjoint

Description

This function extracts model coefficients from INLAjoint objects.

Usage

## S3 method for class 'INLAjoint'
coef(object, ...)

Arguments

Extracts family from a given model fitted with INLAjoint

Description

This function extracts family from INLAjoint objects.

Usage

## S3 method for class 'INLAjoint'
family(object, ...)

Arguments

Extracts fitted values from a given model fitted with INLAjoint

Description

This function extracts fitted values from INLAjoint objects. Values are associated to a name to keep track of the outcome related to each fitted value.

Usage

## S3 method for class 'INLAjoint'
fitted(object, ...)

Arguments

Extracts fixed effects values from a given model fitted with INLAjoint

Description

This function extracts fixed effects values from INLAjoint objects.

Usage

## S3 method for class 'INLAjoint'
fixef(object, ...)

Arguments

Extracts formula from a given model fitted with INLAjoint

Description

This function extracts formula from INLAjoint objects.

Usage

## S3 method for class 'INLAjoint'
formula(x, ...)

Arguments

Fit a multivariate joint model for longitudinal and/or survival data

Description

This function fits a multivariate joint model for longitudinal and/or survival data. The longitudinal outcomes are modeled with mixed effects models and can handle various distributions. The survival outcomes (i.e., terminal event with possibly competing risks) are modeled with Cox proportional hazards regression models. Various association structures can be specified between the longitudinal and survival outcomes. The inference is based on Integrated Nested Laplace Approximations (Rue et al., 2009).

Usage

joint(
  formSurv = NULL,
  formLong = NULL,
  dataSurv = NULL,
  dataLong = NULL,
  id = NULL,
  timeVar = NULL,
  family = "gaussian",
  link = "default",
  basRisk = "rw1",
  NbasRisk = 15,
  cutpoints = NULL,
  assoc = NULL,
  assocSurv = NULL,
  corLong = FALSE,
  corRE = TRUE,
  dataOnly = FALSE,
  longOnly = FALSE,
  control = list()
)

Arguments

Value

An object of class INLAjoint. See INLAjoint.object for details.

References

Rustand, D., van Niekerk, J., Teixeira Krainski, E., Rue, H. and Proust-Lima, C. (2023). Fast and flexible inference for joint models of multivariate longitudinal and survival data using integrated nested Laplace approximations. Biostatistics, 2023, kxad019. https://doi.org/10.1093/biostatistics/kxad019 https://arxiv.org/abs/2203.06256

Rustand, D., van Niekerk, J., Rue, H., Tournigand, C., Rondeau, V. and Briollais, L. (2023). Bayesian Estimation of Two-Part Joint Models for a Longitudinal Semicontinuous Biomarker and a Terminal Event with R-INLA: Interests for Cancer Clinical Trial Evaluation. Biometrical Journal, 65, 2100322. https://doi.org/10.1002/bimj.202100322 https://arxiv.org/abs/2010.13704

Rue, H., Martino, S. and Chopin, N. (2009). Approximate Bayesian inference for latent Gaussian models by using integrated nested Laplace approximations. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 71: 319-392. https://doi.org/10.1111/j.1467-9868.2008.00700.x

Bates, D., Mächler, M., Bolker, B., & Walker, S. (2015). Fitting Linear Mixed-Effects Models Using lme4. Journal of Statistical Software, 67(1), 1–48. https://doi.org/10.18637/jss.v067.i01

Contact: INLAjoint@gmail.com

Examples

# joint model with 3 longitudinal / 3 competing risks of event
data(Longsim)
data(Survsim)
f1 <- function(x) x^2 # quadratic function of time for first marker
Nsplines <- splines::ns(Longsim$time, knots=2) # 2 ns splines for second marker
f2 <- function(x) predict(Nsplines, x)[,1]
f3 <- function(x) predict(Nsplines, x)[,2]

if(requireNamespace("INLA")){
 JMINLA <- joint(
  formLong = list(Y1 ~ time + f1(time) + ctsX + binX + (1 + time + f1(time) | Id),
                  Y2 ~ time + f2(time) + f3(time) + ctsX + binX + (1 | Id),
                  Y3 ~ time + ctsX + binX + (1 | Id)),
  formSurv = list(INLA::inla.surv(deathTimes, Event1) ~ binX + ctsX,
                  INLA::inla.surv(deathTimes, Event2) ~ binX,
                  INLA::inla.surv(deathTimes, Event3) ~ ctsX),
  dataLong = Longsim, dataSurv=Survsim, id = "Id", timeVar = "time", corLong=TRUE,
  family = c("gaussian", "poisson", "binomial"), basRisk = c("rw1", "rw1", "rw1"),
  assoc = list(c("CV", "CS", ""),  c("CV", "", "SRE"), c("", "CV", "")),
  control=list(int.strategy="eb"))

 summary(JMINLA)
 # 'sdcor' to switch from variance-covariance to standard
 # deviation-correlation and 'hazr' to switch parameters
 # in survival submodels from mean to hazard ratios (exp(mean)).
 summary(JMINLA, sdcor=TRUE, hazr=TRUE)
}

Rerun a model fitted with INLAjoint

Description

Reruns inla() for an object of class INLAjoint returned by the joint function. The rerun starts with posterior values from previous run and can sometimes improve the model fit (for very complex models or unstable parameter estimates due to low information in the data)

Usage

joint.rerun(model, ...)

Arguments

Value

An object of class INLAjoint containing a model fitted with the joint() function.

See Also

joint.

Extracts log-likelihood value from a given model fitted with INLAjoint

Description

This function extracts log-likelihood value from INLAjoint objects.

Usage

## S3 method for class 'INLAjoint'
logLik(object, ...)

Arguments

Extracts number of observations of each composant from a given model fitted with INLAjoint

Description

This function extracts number of observations of each composant from INLAjoint objects.

Usage

## S3 method for class 'INLAjoint'
nobs(object, ...)

Arguments

Plot the output from a multivariate joint model for longitudinal and/or survival data

Description

This function provide plots for the output of a multivariate joint model for longitudinal and/or survival data. The output can be stored into an object and manipulated as a list of ggplot outputs, described bellow.

Usage

## S3 method for class 'INLAjoint'
plot(x, ...)

Arguments

Value

return a named list of ggplot objects containing:

Outcomes

as a list of length equal the number of longitudinal outcomes plus the number of survival outcomes, each one including the plot for the posterior marginals of the associated fixed effects and residual or baseline variance (or standard error). Each element contains the plot for the posterior marginal.

Covariances

the plots for the posterior marginal distribution of the covariance parameters.

Associations

the plots for the posterior marginal distribution of the association parameters.

Random

The plot for the fitted baseline risk functions as shown as the posterior mean and credible interval.

Computes predictions for a given model fitted with INLAjoint

Description

This function allows to compute predictions for a given model fitted with INLAjoint, the default behavior (without arguments) returns fitted values for each component of the model. It is also possible to supply a dataset for which predictions are required, this dataset must have the same structure as the dataset used for the model fitting (i.e., same columns). The default returned predictions corresponds to the linear predictors for each outcomes.

Usage

## S3 method for class 'INLAjoint'
predict(
  object,
  newData = NULL,
  timePoints = NULL,
  NtimePoints = 50,
  strategy = 1,
  Nsample = 300,
  NsampleRE = 50,
  loopRE = FALSE,
  id = NULL,
  Csurv = NULL,
  horizon = NULL,
  baselineHaz = "interpolation",
  return.samples = FALSE,
  survival = FALSE,
  CIF = FALSE,
  inv.link = FALSE,
  ...
)

Arguments

Prints plot the output from a multivariate joint model for longitudinal and/or survival data

Description

The plots of a model are grouped by categories, first are the fixed effects and residual error of longitudinal and survival submodels, referred to as 'Outcomes' or 'O'. Then the variance-covariance of random effects (or standard deviations and correlations when the argument 'sdcor' is set to TRUE in the call of the plot function), referred to as 'Covariances' or 'C'. Association parameters referred to as 'Associations' or 'A' for linear associations and 'NL_Associations' or 'N' for non-linear associations. Baseline hazard curves referred to as 'Baseline' or 'B' and baseline hazard related parameters referred to as 'ParamBaseline' or 'P'. It is possible to select specific plots to print by specifying the names or corresponding letters in the argument 'which'.

Usage

## S3 method for class 'plot.INLAjoint'
print(
  x,
  which = c("all", "Outcomes", "Covariances", "Associations", "Baseline"),
  ...
)

Arguments

Extracts random effects values from a given model fitted with INLAjoint

Description

This function extracts random effects values from INLAjoint objects.

Usage

## S3 method for class 'INLAjoint'
ranef(object, ...)

Arguments

Setup fixed effects part for longitudinal marker k

Description

Setup fixed effects part for longitudinal marker k (internal function) input:

Usage

setup_FE_model(formula, dataset, timeVar, k, dataOnly)

Arguments

Value

colnames(FE) names of the fixed effects (interactions are separated by ".X." instead of ":" to facilitate their manipulation)

FE values of the fixed effects

Setup random effects part for longitudinal marker k

Description

Setup random effects part for longitudinal marker k (internal function) input:

Usage

setup_RE_model(formula, dataset, k)

Arguments

Value

colnames(RE_mat) names of the random effects

RE_mat values of the random effects

Setup survival part for outcome m

Description

Setup survival part for outcome m (internal function) input:

Usage

setup_S_model(
  formula,
  formLong,
  dataSurv,
  LSurvdat,
  timeVar,
  assoc,
  id,
  m,
  K,
  M,
  NFT,
  corLong,
  dataOnly,
  SurvInfo,
  strata
)

Arguments

Value

YS_data includes the values of the survival outcome and covariates associated to this survival part, with the association parameters but the provided id are temporary and they will be updated after the cox expansion to make them unique and allow for time dependency

YSformF formula for this survival outcome (not including association parameters)

Setup outcome for longitudinal marker

Description

Setup outcome for longitudinal marker (internal function) input:

Usage

setup_Y_model(formula, dataset, family, k)

Arguments

Value

YL.name name of the outcome

YL values of the outcome