Description Usage Arguments Details Value Author(s) References See Also Examples
This function fits mixed models and latent class mixed models for different
types of outcomes. It handles continuous longitudinal outcomes (Gaussian or
nonGaussian) as well as bounded quantitative, discrete and ordinal
longitudinal outcomes. The different types of outcomes are taken into
account using parameterized nonlinear link functions between the observed
outcome and the underlying latent process of interest it measures. At the
latent process level, the model estimates a standard linear mixed model or a
latent class linear mixed model when heterogeneity in the population is
investigated (in the same way as in function hlme
). It should be
noted that the program also works when no randomeffect is included.
Parameters of the nonlinear link function and of the latent process mixed
model are estimated simultaneously using a maximum likelihood method.
1 2 3 4 5 6  lcmm(fixed, mixture, random, subject, classmb, ng = 1, idiag = FALSE,
nwg = FALSE, link = "linear", intnodes = NULL, epsY = 0.5,
cor = NULL, data, B, convB = 1e04, convL = 1e04, convG = 1e04,
maxiter = 100, nsim = 100, prior, range = NULL, subset = NULL,
na.action = 1, posfix = NULL, partialH = FALSE, verbose = TRUE,
returndata = FALSE)

fixed 
a twosided linear formula object for specifying the
fixedeffects in the linear mixed model at the latent process level. The
response outcome is on the left of 
mixture 
a onesided formula object for the classspecific fixed
effects in the latent process mixed model (to specify only for a number of
latent classes greater than 1). Among the list of covariates included in

random 
an optional onesided formula for the randomeffects in the
latent process mixed model. Covariates with a randomeffect are separated by

subject 
name of the covariate representing the grouping structure. 
classmb 
an optional onesided formula describing the covariates in
the classmembership multinomial logistic model. Covariates included are
separated by 
ng 
number of latent classes considered. If 
idiag 
optional logical for the variancecovariance structure of the
randomeffects. If 
nwg 
optional logical of classspecific variancecovariance of the
randomeffects. If 
link 
optional family of link functions to estimate. By default,
"linear" option specifies a linear link function leading to a standard
linear mixed model (homogeneous or heterogeneous as estimated in

intnodes 
optional vector of interior nodes. This argument is only required for a Isplines link function with nodes entered manually. 
epsY 
optional definite positive real used to rescale the marker in (0,1) when the beta link function is used. By default, epsY=0.5. 
cor 
optional brownian motion or autoregressive process modeling the correlation between the observations. "BM" or "AR" should be specified, followed by the time variable between brackets. By default, no correlation is added. 
data 
optional data frame containing the variables named in

B 
optional specification for the initial values for the parameters.
Three options are allowed: (1) a vector of initial values is entered (the
order in which the parameters are included is detailed in 
convB 
optional threshold for the convergence criterion based on the parameter stability. By default, convB=0.0001. 
convL 
optional threshold for the convergence criterion based on the loglikelihood stability. By default, convL=0.0001. 
convG 
optional threshold for the convergence criterion based on the derivatives. By default, convG=0.0001. 
maxiter 
optional maximum number of iterations for the Marquardt iterative algorithm. By default, maxiter=100. 
nsim 
number of points used to plot the estimated link function. By default, nsim=100. 
prior 
name of the covariate containing the prior on the latent class membership. The covariate should be an integer with values in 0,1,...,ng. When there is no prior, the value should be 0. When there is a prior for the subject, the value should be the number of the latent class (in 1,...,ng). 
range 
optional vector indicating the range of the outcome (that is the minimum and maximum). By default, the range is defined according to the minimum and maximum observed values of the outcome. The option should be used only for Beta and Splines transformations. 
subset 
optional vector giving the subset of observations in

na.action 
Integer indicating how NAs are managed. The default is 1 for 'na.omit'. The alternative is 2 for 'na.fail'. Other options such as 'na.pass' or 'na.exclude' are not implemented in the current version. 
posfix 
Optional vector specifying the indices in vector B of the parameters that should not be estimated. Default to NULL, all parameters are estimated. 
partialH 
optional logical for Beta or Splines link functions only. Indicates whether the parameters of the link functions can be dropped from the Hessian matrix to define convergence criteria. 
verbose 
logical indicating if information about computation should be reported. Default to TRUE. 
returndata 
logical indicating if data used for computation should be returned. Default to FALSE, data are not returned. 
A. THE PARAMETERIZED LINK FUNCTIONS
lcmm
function estimates mixed models and latent class mixed models
for different types of outcomes by assuming a parameterized link function
for linking the outcome Y(t) with the underlying latent process L(t) it
measures. To fix the latent process dimension, we chose to constrain the
(first) intercept of the latent class mixed model at the latent process
level at 0 and the standard error of the gaussian error of measurement at 1.
These two parameters are replaced by additional parameters in the
parameterized link function :
1. With the "linear" link function, 2 parameters are required that correspond directly to the intercept and the standard error: (Y  b1)/b2 = L(t).
2. With the "beta" link function, 4 parameters are required for the following transformation: [ h(Y(t)',b1,b2)  b3]/b4 where h is the Beta CDF with canonical parameters c1 and c2 that can be derived from b1 and b2 as c1=exp(b1)/[exp(b2)*(1+exp(b1))] and c2=1/[exp(b2)*(1+exp(b1))], and Y(t)' is the rescaled outcome i.e. Y(t)'= [ Y(t)  min(Y(t)) + epsY ] / [ max(Y(t))  min(Y(t)) +2*epsY ].
3. With the "splines" link function, n+2 parameters are required for the following transformation b_1 + b_2*I_1(Y(t)) + ... + b_n+2 I_n+1(Y(t)), where I_1,...,I_n+1 is the basis of quadratic Isplines. To constraint the parameters to be positive, except for b_1, the program estimates b_k^* (for k=2,...,n+2) so that b_k=(b_k^*)^2.
4. With the "thresholds" link function for an ordinal outcome in levels 0,...,C. A maximumn of C parameters are required for the following transformation: Y(t)=c <=> b_c < L(t) <= b_c+1 with b_0 =  infinity and b_C+1=+infinity. The number of parameters is reduced if some levels do not have any information. For example, if a level c is not observed in the dataset, the corresponding threshold b_c+1 is constrained to be the same as the previous one b_c. The number of parameters in the link function is reduced by 1.
To constraint the parameters to be increasing, except for the first parameter b_1, the program estimates b_k^* (for k=2,...C) so that b_k=b_k1+(b_k^*)^2.
Details of these parameterized link functions can be found in the referred papers.
B. THE VECTOR OF PARAMETERS B
The parameters in the vector of initial values B
or in the vector of
maximum likelihood estimates best
are included in the following
order: (1) ng1 parameters are required for intercepts in the latent class
membership model, and if covariates are included in classmb
, ng1
paramaters should be entered for each one; (2) for all covariates in
fixed
, one parameter is required if the covariate is not in
mixture
, ng paramaters are required if the covariate is also in
mixture
; When ng=1, the intercept is not estimated and no parameter
should be specified in B
. When ng>1, the first intercept is not
estimated and only ng1 parameters should be specified in B
; (3) the
variance of each randomeffect specified in random
(including the
intercept) if idiag=TRUE
and the inferior triangular
variancecovariance matrix of all the randomeffects if idiag=FALSE
;
(4) only if nwg=TRUE
, ng1 parameters for classspecific proportional
coefficients for the variance covariance matrix of the randomeffects; (5)
In contrast with hlme, due to identifiability purposes, the standard error
of the Gaussian error is not estimated (fixed at 1), and should not be
specified in B
; (6) The parameters of the link function: 2 for
"linear", 4 for "beta", n+2 for "splines" with n nodes and the number of
levels minus one for "thresholds".
C. CAUTIONS REGARDING THE USE OF THE PROGRAM
Some caution should be made when using the program. convergence criteria are very strict as they are based on derivatives of the loglikelihood in addition to the parameter and loglikelihood stability. In some cases, the program may not converge and reach the maximum number of iterations fixed at 100. In this case, the user should check that parameter estimates at the last iteration are not on the boundaries of the parameter space. If the parameters are on the boundaries of the parameter space, the identifiability of the model is critical. This may happen especially with splines parameters that may be too close to 0 (lower boundary) or classmb parameters that are too high or low (perfect classification). When identifiability of some parameters is suspected, the program can be run again from the former estimates by fixing the suspected parameters to their value with option posfix. This usually solves the problem. An alternative is to remove the parameters of the Beta of Splines link function from the inverse of the Hessian with option partialH. If not, the program should be run again with other initial values, with a higher maximum number of iterations or less strict convergence tolerances.
Specifically when investigating heterogeneity (that is with ng>1): (1) As
the loglikelihood of a latent class model can have multiple maxima, a
careful choice of the initial values is crucial for ensuring convergence
toward the global maximum. The program can be run without entering the
vector of initial values (see point 2). However, we recommend to
systematically enter initial values in B
and try different sets of
initial values. (2) The automatic choice of initial values we provide
requires the estimation of a preliminary linear mixed model. The user should
be aware that first, this preliminary analysis can take time for large
datatsets and second, that the generated initial values can be very not
likely and even may converge slowly to a local maximum. This is the reason
why several alternatives exist. The vector of initial values can be directly
specified in B
the initial values can be generated (automatically or
randomly) from a model with ng=
. Finally, function gridsearch
performs an automatic grid search.
D. NUMERICAL INTEGRATION WITH THE THRESHOLD LINK FUNCTION
With exception for the threshold link function, maximum likelihood estimation implemented in lcmm does not require any numerical integration over the randomeffects so that the estimation procedure is relatively fast. See Proust et al. (2006) for more details on the estimation procedure.
However, with the threshold link function and when at least one randomeffect is specified, a numerical integration over the randomeffects distribution is required in each computation of the individual contribution to the likelihood which complicates greatly the estimation procedure. For the moment, we do not allow any option regarding the numerical integration technics used. 1. When a single randomeffect is specified, we use a standard nonadaptive Gaussian quadrature with 30 points. 2. When at least two randomeffects are specified, we use a multivariate nonadaptive Gaussian quadrature implemented by Genz (1996) in HRMSYM Fortran subroutine.
Further developments should allow for adaptive technics and more options regarding the numerical integration technic.
E. POSTERIOR DISCRETE LIKELIHOOD
Models involving nonlinear continuous link functions assume the continuous data while the model with a threshold model assumes discrete data. As a consequence, comparing likelihoods or criteria based on the likelihood (as AIC) for these models is not possible as the former are based on a Lebesgue measure and the latter on a counting measure. To make the comparison possible, we compute the posterior discrete likelihood for all the models with a nonlinear continuous link function. This posterior likelihood considers the data as discrete; it is computed at the MLE (maximum likelihood estimates) using the counting measure so that models with threshold or continuous link functions become comparable. Further details can be found in ProustLima, Amieva, JacqminGadda (2012).
In addition to the Akaike information criterion based on the discrete posterior likelihood, we also compute a universal approximate crossvalidation criterion to compare models based on a different measure. See Commenges, ProustLima, Samieri, Liquet (2015) for further details.
The list returned is:
ns 
number of grouping units in the dataset 
ng 
number of latent classes 
loglik 
loglikelihood of the model 
best 
vector of parameter estimates in the same order as
specified in 
V 
vector containing the upper triangle matrix of variancecovariance
estimates of 
gconv 
vector of convergence criteria: 1. on the parameters, 2. on the likelihood, 3. on the derivatives 
conv 
status of convergence: =1 if the convergence criteria were satisfied, =2 if the maximum number of iterations was reached, =4 or 5 if a problem occured during optimisation 
call 
the matched call 
niter 
number of Marquardt iterations 
dataset 
dataset 
N 
internal information used in related functions 
idiag 
internal information used in related functions 
pred 
table of individual predictions and residuals in the underlying latent process scale; it includes marginal predictions (pred_m), marginal residuals (resid_m), subjectspecific predictions (pred_ss) and subjectspecific residuals (resid_ss) averaged over classes, the transformed observations in the latent process scale (obs) and finally the classspecific marginal and subjectspecific predictions (with the number of the latent class: pred_m_1,pred_m_2,...,pred_ss_1,pred_ss_2,...). This output is not available yet when specifying a thresholds transformation. 
pprob 
table of posterior classification and posterior individual classmembership probabilities 
Xnames 
list of covariates included in the model 
predRE 
table containing individual predictions of the randomeffects : a column per randomeffect, a line per subject. This output is not available yet when specifying a thresholds transformation. 
cholesky 
vector containing the estimates of the Cholesky transformed parameters of the variancecovariance matrix of the randomeffects 
estimlink 
table containing the simulated values of the marker and corresponding estimated link function 
epsY 
definite positive real used to rescale the marker in (0,1) when the beta link function is used. By default, epsY=0.5. 
linktype 
indicator of link function type: 0 for linear, 1 for beta, 2 for splines and 3 for thresholds 
linknodes 
vector of nodes useful only for the 'splines' link function 
data 
the original data set (if returndata is TRUE) 
Cecile ProustLima, Amadou Diakite, Benoit Liquet and Viviane Philipps
ProustLima C, Philipps V, Liquet B (2017). Estimation of Extended Mixed Models Using Latent Classes and Latent Processes: The R Package lcmm. Journal of Statistical Software, 78(2), 156. doi:10.18637/jss.v078.i02
Genz and Keister (1996). Fully symmetric interpolatory rules for multiple integrals over infinite regions with gaussian weight. Journal of Computational and Applied Mathematics 71: 299309.
Proust and JacqminGadda (2005). Estimation of linear mixed models with a mixture of distribution for the randomeffects. Comput Methods Programs Biomed 78: 16573.
Proust, JacqminGadda, Taylor, Ganiayre, and Commenges (2006). A nonlinear model with latent process for cognitive evolution using multivariate longitudinal data. Biometrics 62: 101424.
ProustLima, Dartigues and JacqminGadda (2011). Misuse of the linear mixed model when evaluating risk factors of cognitive decline. Amer J Epidemiol 174(9): 107788.
ProustLima, Amieva and JacqminGadda (2013). Analysis of multivariate mixed longitudinal data : a flexible latent process approach, British Journal of Mathematical and Statistical Psychology 66(3): 47087.
Commenges, ProustLima, Samieri, Liquet (2015). A universal approximate crossvalidation criterion for regular risk functions. Int J Biostat. 2015 May;11(1):5167
postprob
, plot.lcmm
, plot.predict
,
hlme
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88  ## Not run:
#### Estimation of homogeneous mixed models with different assumed link
#### functions, a quadratic mean trajectory for the latent process and
#### correlated random intercept and slope (the random quadratic slope
#### was removed as it did not improve the fit of the data).
####  comparison of linear, Beta and 3 different splines link functions 
# linear link function
m10<lcmm(Ydep2~Time+I(Time^2),random=~Time,subject='ID',ng=1,
data=data_lcmm,link="linear")
summary(m10)
# Beta link function
m11<lcmm(Ydep2~Time+I(Time^2),random=~Time,subject='ID',ng=1,
data=data_lcmm,link="beta")
summary(m11)
plot(m11,which="linkfunction",bty="l")
# Isplines with 3 equidistant nodes
m12<lcmm(Ydep2~Time+I(Time^2),random=~Time,subject='ID',ng=1,
data=data_lcmm,link="3equisplines")
summary(m12)
# Isplines with 5 nodes at quantiles
m13<lcmm(Ydep2~Time+I(Time^2),random=~Time,subject='ID',ng=1,
data=data_lcmm,link="5quantsplines")
summary(m13)
# Isplines with 5 nodes, and interior nodes entered manually
m14<lcmm(Ydep2~Time+I(Time^2),random=~Time,subject='ID',ng=1,
data=data_lcmm,link="5manualsplines",intnodes=c(10,20,25))
summary(m14)
plot(m14,which="linkfunction",bty="l")
# Thresholds
# Especially for the threshold link function, we recommend to estimate
# models with increasing complexity and use estimates of previous ones
# to specify plausible initial values (we remind that estimation of
# models with threshold link function involves a computationally demanding
# numerical integration here of size 3)
m15<lcmm(Ydep2~Time+I(Time^2),random=~Time,subject='ID',ng=1
,data=data_lcmm,link="thresholds",maxiter=100,
B=c(0.8379, 0.1103, 0.3832, 0.3788 , 0.4524, 7.3180, 0.5917, 0.7364,
0.6530, 0.4038, 0.4290, 0.6099, 0.6014 , 0.5354 , 0.5029 , 0.5463,
0.5310 , 0.5352, 0.6498, 0.6653, 0.5851, 0.6525, 0.6701 , 0.6670 ,
0.6767 , 0.7394 , 0.7426, 0.7153, 0.7702, 0.6421))
summary(m15)
plot(m15,which="linkfunction",bty="l")
#### Plot of estimated different link functions:
#### (applicable for models that only differ in the "link function" used.
#### Otherwise, the latent process scale is different and a rescaling
#### is necessary)
plot(m10,which="linkfunction",col=1,xlab="latent process",ylab="marker",
bty="l",xlim=c(10,5),legend=NULL)
plot(m11,which="linkfunction",add=TRUE,col=2,legend=NULL)
plot(m12,which="linkfunction",add=TRUE,col=3,legend=NULL)
plot(m13,which="linkfunction",add=TRUE,col=4,legend=NULL)
plot(m14,which="linkfunction",add=TRUE,col=5,legend=NULL)
plot(m15,which="linkfunction",add=TRUE,col=6,legend=NULL)
legend(x="bottomright",legend=c("linear","beta","spl_3e","spl_5q","spl_5m","thresholds"),
col=1:6,lty=1,inset=.02,box.lty=0)
#### Estimation of 2latent class mixed models with different assumed link
#### functions with individual and class specific linear trend
#### for illustration, only default initial values where used but other
#### sets of initial values should also be tried to ensure convergence
#### towards the golbal maximum
# Linear link function
m20<lcmm(Ydep2~Time,random=~Time,subject='ID',mixture=~Time,ng=2,
idiag=TRUE,data=data_lcmm,link="linear",B=c(0.98,0.79,2.09,
0.81,0.19,0.55,24.49,2.24))
summary(m20)
postprob(m20)
# Beta link function
m21<lcmm(Ydep2~Time,random=~Time,subject='ID',mixture=~Time,ng=2,
idiag=TRUE,data=data_lcmm,link="beta",B=c(0.1,0.56,0.4,1.77,
0.53,0.14,0.6,0.83,0.73,0.09))
summary(m21)
postprob(m21)
# Isplines link function (and 5 nodes at quantiles)
m22<lcmm(Ydep2~Time,random=~Time,subject='ID',mixture=~Time,ng=2,
idiag=TRUE,data=data_lcmm,link="5quantsplines",B=c(0.12,0.63,
1.76,0.39,0.51,0.13,7.37,1.05,1.28,1.96,1.3,0.93,1.05))
summary(m22)
postprob(m22)
data < data_lcmm[data_lcmm$ID==193,]
plot(predictL(m22,var.time="Time",newdata=data,bty="l")
## End(Not run)

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.