The use of linear and non-linear mixed models in the life sciences and pharmacometrics is common practice. Estimation of the parameters of models not involving a system of differential equations is often done by the R or S-Plus software with the nonlinear mixed effects nlme package. The estimated residual error may be used for diagnosis of the fitted model, but not whether the model correctly describes the relation between response and included variables including the true covariance structure. The latter is only true if the residual error is known in advance. Therefore, it may be necessary or more appropriate to fix the residual error a priori instead of estimate its value. This can be the case if one wants to include evidence from past studies or a theoretical derivation; e.g., when using a binomial model. S-Plus has an option to fix this residual error to a constant, in contrast to R. For convenience, the nlme package was customized to offer this option as well. In this paper, we derived the log-likelihoods for the mixed models using a fixed residual error. By using some well-known examples from mixed models, we demonstrated the equivalence of R and S-Plus with respect to the estimates. The updated package has been accepted by the Comprehensive R Archive Network (CRAN) team and will be available at the CRAN website.
Life science and pharmacometric studies almost always involve an
application of linear (Laird and Ware 1982) and non-linear (Davidian and Giltinan 1995)
mixed models. In pharmacometrics, the use of nonlinear mixed effects
modelling (NONMEM) software (Beal and Sheiner 1988) for models with systems of
differential equations is predominant. Simpler pharmacokinetic (PK) or
pharmadynamic (PD) models may be based on curve fitting, for which
software such as S-Plus and R are preferred. Both programs use a similar
mixed model package, respectively,
nlme and nlme library, both
of which were originally developed by the authors Pinheiro and Bates
(Pinheiro and Bates 2001). In most cases, the estimates of the parameters are the
same at least to the third significant digit, although the same model
and data might occasionally lead to convergence problems (e.g., in R and
not in S-Plus, and vice versa), although larger differences may occur
e.g., when performing an analysis of variance with the function anova
,
as shown in 6. Typically, the estimated fixed and random
coefficients have a practical interpretation. The fixed coefficients
usually refer to the parameters of interest for the study; i.e.
treatment, gender differences, half-life of the drug substance etc.,
while the random parameters are interpreted as variation in the
population represented by the study. The residual error of the fitted
model is an important indicator for the goodness of fit. Whether the
goodness of fit is assessed by the log-likelihood ratio, the Akaike
information criterion (AIC) (Akaike 1980) or the Bayesian information
criterion (BIC) (Schwartz 1978) criteria, all criteria implicitly or
explicitly use the residual error of the fit.
For some applications, it is not appropriate to estimate the residual
error, especially when it is known in advance based on evidence from
past studies, or a theoretically derived scaling parameter. An example
of the former are meta-analyses where the standard deviation of
individual patient outcomes in each study is reported. An example of the
latter is a data transformation, implying a fixed scaling parameter;
e.g., the square root
As pointed out by an anonymous reviewer, other applications may be considered as well (Littel et al. 2006). For example simulation of new observations from the fitted model while keeping sigma constant or performing power calculations where commonly the expected error is assumed to be known and kept constant. In both cases one must bear in mind that the simulated data will not cover the whole range of possible outcomes, and in case of power calculation the actual power may be well below the nominal power one aimed at.
The fitting functions from the nlme library in S-Plus allow the residual standard error to be fixed and kept constant during the fitting process. This feature was not described in Pinheiro and Bates (Pinheiro and Bates 2001) but has been added as an argument to the respective control functions. This feature was not available in the R package nlme but is included from version 3.1.123 (released 2016-01-17) onward.
We present this feature of the control functions used in linear mixed
effects lme
, non-linear mixed effects nlme
, generalized linear least
squares gls
and generalized non-linear least squares gnls
. Utilities
as summary
, anova
, print
and intervals
have been adapted as
well.
From a coding point of view these changes were significant, as they required, among others, a change of the likelihood functions in both the R and C source codes. This paper discusses the statistical background in Section 2. In Section 3 the similarities and differences of the output of S-Plus version 8.2 are given for selected examples from Pinheiro and Bates (Pinheiro and Bates 2001) as well as a case study describing a model-based meta-analysis of outcomes in rheumatoid arthritis. In the last Section proposals for change in nlme are put forward to address some of these similarities and differences.
The mixed model is an extension of the general linear model. The extension to a mixed model allows other parameters of the general linear model to have a statistical normal distribution (Laird and Ware 1982). These models are also known as multilevel models in different fields of application, as they describe a hierarchy of levels in the data. For example, in a clinical trial, the first level might be the trial centre, the second might be the patients within the trial centre, and the third might be the time points at which the observations are acquired for an individual patient.
The reason for such a break-down of the random variation is that, within a centre, the variation between subjects may be different than between centres; e.g., differences in environment, skills of the operators, measurement devices, or the mixture of ethnicity of the patients. Variation within patients is likely to be different and correlation of longitudinal observations within a patient may be present.
The expected outcome may be linear in the design parameters, including
linear combinations of polynomials and general additive models
(Wood 2006). Similarly parameters of the non-linear models are allowed
to be linear combinations (Davidian and Giltinan 1995). General linear and mixed
linear models are fitted with gls
and lme
respectively. The
corresponding non-linear models (e.g. a Michaelis-Menten model curve)
are fitted with gnls
and nlme
.
Mixed models have two sets of parameters. The fixed parameters are often of primary interest of the study. For example, differences in treatment or gender, the half-life of a drug or factors for which one wants to control like co-medication. The random parameters are used to describe variation within respective levels of the study and are generally not controllable. For example, variation between and within a population of patients. The random parameters might be dependent on some or all of the fixed parameters or perhaps a function of the fitted values. Common statistical analysis seeks to estimate all fixed and random parameters simultaneously using the same data without prior knowledge.
In the next subsections, we describe the mathematical model extending
from the general linear to the linear mixed and non-linear mixed model
with knowledge of the residual error. The notation and the terminology
with regard to the number of hierarchical levels follows closely to that
in Pinheiro and Bates (Pinheiro and Bates 2001). Throughout the paper we will use
Greek characters to indicate the true but unknown values of the model
parameters, while the corresponding character superscripted by
The general linear model with only the basic random level of the
residuals is presented here. A comparison is made between the likelihood
for the usual model with an estimated residual error and the one with a
fixed value of the latter. For further details of the derivation see
(Pinheiro and Bates 2001). If there were
To solve model ((1)), one may reduce the model to an ordinary
least squares model by transforming both sides of the equation such that
the covariance matrices are again diagonal and equal to
The matrices
The number
The estimation of
However, if the residual variance is fixed, the profiled likelihood will
be different. To see this, one has to derive the original log likelihood
function without substitution of
Note that if
to ((4)), which will change the dependency from
If the co-variance matrix only depends on the variance
The extension of the general linear model to a mixed linear model
complicates the likelihood and subsequently, the estimation of its
parameters. The model is known as the Laird-Ware model
(Laird and Ware 1982), but the original proposal for solving the equations
is credited to Harville (Harville 1977). If
A particularity of model ((5)) is that the vectors
In the following example, the (minus) log-likelihood of the standard
mixed model for one hierarchical level (
lme
is, by
default, the restricted maximum likelihood.
The non-linear mixed model is not only more complicated, its model
structure is also different. In a linear model, the expectation of
response is directly modelled as a linear combination of the row vectors
of the design matrix gnls
.
The nlme algorithm consists of alternating between a penalized
non-linear least squares step (PNLS) and the linear mixed model step
(NLM), which is similar and explained in the linear mixed model section.
Therefore, only the consequences of fixing
gnls
for the general non-linear model analogous to the
general linear model function gls
. It uses basically the same
algorithm as nlme
by stripping the random component.
From the viewpoint of the user, the only change in a function call of
gls
, is an extra argument in the control functions glsControl
,
gnlsControl
, lmeControl
and nlmeControl
respectively. The option
is implemented exactly as the corresponding control functions in S-Plus;
for example, using a simple model and data from the S-Plus and R
libraries. The output object of the functions lme
, nlme
, gls
, and
gnls
contained a logical flag as component to signal whether print
, summary
, anova
, and intervals
. Table 1 gives an overview
of the examples used to test the new feature. The former are taken from
Pinheiro and Bates (Pinheiro and Bates 2001). All examples ran both in R and
S-Plus.
Model type | nlme Function | Data set | Model name | Model function | Reference |
Generalized linear | gls |
Orthodont | fm1Orth.gls | p. 251 | |
Non-linear | gnls |
Dialyzer | fm1Dial.gnls | SSasympOff | p. 402 |
Mixed linear | lme |
Orthodont | fm1Orth.lme | p. 147 | |
lme |
Orthodont | fm3Orth.lme | p. 177 | ||
lme |
Wafer | fm1Wafer.lme | p. 172 | ||
Mixed non-linear | nlme |
Theophylline | fm1Theo.nlme | SSfol | p. 363, 516 |
nlme |
Theophylline | fm2Theo.nlme | SSfol | p. 364, 516 | |
nlme |
Theophylline | fm3Theo.nlme | SSfol | p. 365, 516 | |
nlme |
Orange | fm1Oran.nlme | SSlogis | p. 358, 519 |
In the next subsections the output from package nlme of R and library
nlme of S-Plus are compared. Striking differences are given in the
discussion. All scripts, output and difference files- in HTML format-
are made available to the editors of the journal. Not all models
converged. They were either in both R and S-Plus or in R or S-Plus only.
The package nlme has a choice for two different optimizing algorithms
but only the default has been used as this is the only one available in
S-Plus. Thus, non-convergence in R might be caused by the use of the
default algorithm. However, this has not been tested systematically. The
same starting values have been used in both R and S-Plus, except in the
examples with the self-starting functions in nlme. For the latter,
starting values had to be supplied. The same examples for estimated
As an example, the code for the general linear and general non-linear
model are given below for fixed
fm1Orth.gls <- gls( distance ~ Sex * I( age - 11), Orthodont)
While the same model with a fixed
fm1Orth_fix.gls <- gls( distance ~ Sex * I( age - 11), Orthodont,
control = glsControl(sigma = 2)).
The default estimates sigma
to glsControl
or gnlsControl
(below) can be omitted or set to 0 or NULL. For both
estimated and fixed
fm1Dial.gnls <- gnls( rate ~ SSasympOff( pressure, Asym, lrc, c0), Dialyzer,
params = list( Asym + lrc ~ QB, c0 ~ 1),
start = c(53.6, 8.6, 0.51, -0.26, 0.225),
control = gnlsControl(sigma = NULL))
For fixed sigma
to the gnlsControl
function
should be changed to 1. The function gnls
can only produce a least
squares solution and rarely uses the C-library. Note that although the
function SSasympOff
is a self-starting function, starting values had
to be supplied in R, but not in S-Plus.
The gls
example from above was also fitted as a mixed model with the
appropriate changes in the script:
fm1Orth.lme <- lme( distance ~ I(age-11), Orthodont)
and
fm1Orth_fix.lme <- lme( distance ~ I(age-11), Orthodont,
control = lmeControl(sigma = 1))
Similar results as for the gls
model were found for the ML method.
However, both in R and S-Plus the REML estimation method for both
estimated and fixed
fm3Orth.lme <- lme( distance ~ Sex * I( age - 11), Orthodont,
weights = varIdent(form = ~ 1 | Sex))
While the same model with a fixed
fm3Orth_fix.lme <- lme( distance ~ Sex * I( age - 11), Orthodont,
weights = varIdent(form = ~ 1 | Sex),
control = list(sigma = 2)).
The ML method of estimation for both estimated and fixed
fm1Wafer.lme <- lme( current ~ voltage + I( voltage^2 ), Wafer,
random = list( Wafer = pdDiag( ~ voltage + I( voltage^2 )),
Site = pdDiag( ~ voltage + I( voltage^2 )) ),
control = lmeControl( sigma = NULL))
For fixed sigma
of lmeControl
. Similar results are found in the two previous
examples. But notable differences in the confidence limits of the random
effects were seen when using the REML method with fixed
The nlme
function for solving a non-linear problem defaults to the ML
method as opposed to lme
. During testing it was discovered that the
option of the restricted maximum produced exactly the same estimates as
for ML, with and without estimation of
fm1Theo.nlme<-nlme(conc ~ SSfol(Dose, Time, lKe, lKa, lCl),
Theoph, fixed = lKe + lKa + lCl ~ 1,
start=c( -2.4, 0.45, -3.2),
control = nlmeControl( sigma = NULL))
Fitting SSfol
was supposed to be self-starting. The
next example from Table 1 is an extension of the above and the code is:
fm2Theo.nlme<-nlme(conc ~ SSfol(Dose, Time, lKe, lKa, lCl),
Theoph, fixed = lKe + lKa + lCl ~ 1,
start=c( -2.4, 0.45, -3.2),
control = nlmeControl( sigma = NULL),
random = pdDiag( lKe + lKa + lCl ~ 1))
The estimates of the fixed coefficients are equal to the second or third
place in all cases. In contrast differences between the random
parameters for ML, REML, and estimated and fixed lKe
to be near infinity. In S-Plus, the covariance matrix of the REML
random estimates was not estimated at all due to singularity of the
Hessian matrix. This may indicate that the parametrization of model is
not correct, probably for parameter lKe
. The next example uses the
same data set but omits lKe
from the random parameter list:
fm2Theo.nlme<-nlme(conc ~ SSfol(Dose, Time, lKe, lKa, lCl),
Theoph, fixed = lKe + lKa + lCl ~ 1,
start=c( -2.4, 0.45, -3.2),
control = nlmeControl( sigma = NULL),
random = pdDiag( lKa + lCl ~ 1))
Now the outcomes of all the models are in better agreement, and the covariance of the random effects is available for S-Plus. There are still differences from the third digit onwards for the random effects confidence limits, especially for the REML method.
Note that for all of the above models we have changed the degrees of
freedom of the log likelihood in case
A summary clinical outcome dataset including clinical outcome data from
14 randomized controlled trials of 4 drugs was extracted from the
Quantify RA clinical database developed by Quantitative Solutions (drug
and trial names blinded). Three endpoints were included describing the
proportion of patients with ACR20, ACR50, and ACR70 responses. These
endpoints are based on the American College of Rheumatology (ACR)
criteria used to assess improvement in tender or swollen joint counts
and improvement in three of the following five parameters: acute phase
reactant (such as sedimentation rate), patient and physician assessment,
pain scale, and a disability/functional questionnaire. For ACR20
response, a 20 percent improvement in tender or swollen joint counts as
well as 20 percent improvement in three of the other five criteria is
required. Similarly, for ACR50 and ACR70, a 50 and 70 percent
improvement is required, respectively. Outcomes were available up to 6
months (24 weeks) after the start of treatment with one of the drugs, up
to 12 weeks with the two other drugs, while the last drug was only
observed in a 4-week trial. The analysis dataset was analyzed using two
non-linear regression models and a mixed effects model with random
effects on the level of trial assuming binomial distributed data. The
probability of ACR20/50/70 response is confined to the interval between
zero and one. In this example, the logit transformation was used as a
link function between the probability of response gnls
model including a constant placebo model across trials and
visits; i.e. gnls
model including an
unstructured placebo model estimating a non-parametric placebo response
at each visit in each trial;
Parameter | Estimate (%RSE) | Estimate (%RSE) |
Estimated |
Fixed |
|
-1.06 (10%) | -1.11 (4%) | |
-1.05 (5%) | -1.07 (3%) | |
-1.97 (3%) | -2.00 (2%) | |
2.02 (10%) | 2.06 (4%) | |
log |
2.22 (63%) | 2.14 (31%) |
log |
1.75 (20%) | 1.68 (9%) |
log |
4.11 (16%) | 4.04 (8%) |
log |
1.22 (36%) | 1.22 (15%) |
Res. error | 1.924 | 1 (fixed) |
Parameter | Estimate (%RSE) | Estimate (%RSE) |
Estimated |
Fixed |
|
Mean |
-1.16 | -1.22 |
-1.08 (3%) | -1.09 (3%) | |
-2.05 (2%) | -2.06 (2%) | |
2.24 (8%) | 2.26 (5%) | |
log |
2.87 (69%) | 2.80 (50%) |
log |
1.94 (13%) | 1.92 (9%) |
log |
4.47 (21%) | 4.42 (15%) |
log |
1.66 (28%) | 1.44 (22%) |
Res. error | 1.313 | 1 (fixed) |
Parameter | Estimate (%RSE) | Estimate (%RSE) |
Estimated |
Fixed |
|
Mean |
-1.28 | -1.26 |
-1.08 (8%) | -1.08 (8%) | |
-2.08 (5%) | -2.08 (5%) | |
2.34 (11%) | 2.33 (11%) | |
log |
2.97 (50%) | 2.99 (54%) |
log |
1.78 (10%) | 1.76 (11%) |
log |
4.66 (16%) | 4.67 (17%) |
log |
1.59 (33%) | 1.71 (32%) |
sd |
0.260 | 0.257 |
sd |
0.351 | 0.344 |
sd |
0.761 | 0.745 |
Res. error | 0.938 | 1 (fixed) |
Model | df | AIC | BIC | logLik | L.Ratio | p-value |
---|---|---|---|---|---|---|
model 1 free |
10 | -740.2 | -700.1 | 380.1 | ||
model 1 fix |
9 | -271.1 | -235.0 | 144.5 | 471.2 | <.0001 |
Model | df | AIC | BIC | logLik | L.Ratio | p-value |
---|---|---|---|---|---|---|
model 2 free |
43 | -1100.5 | -928.0 593.3 | |||
model 2 fix |
42 | -1076.8 | -908.4 | 580.4 | 25.7 | <.0001 |
Model | df | AIC | BIC | logLik | L.Ratio | p-value |
---|---|---|---|---|---|---|
model 3 free |
46 | -1215.8 | -1031.3 | 653.9 | ||
model 3 fix |
45 | -1215.8 | -1035.3 | 652.9 | 2.0 | 0.16 |
It is interesting to note that comparison with anova
showed
significant differences between free estimated and fixed
The estimates of the fixed coefficients of S-Plus and R are often
identical to three significant digits, except in the case of
over-parameterized models, which may cause non-convergence and
inaccurate estimation of the covariance matrix of the random parameters.
Differences might occur even for the default model with estimation of
There are some differences between R and S-Plus in the code of the functions. As the code of the C-functions in S-Plus is not public, differences in the code itself could not be checked. The R functions, in particular the interaction between the R-code and the C-functions were fragile in the sense that input was often changed within a function and then used as output. Thus, a small change in code in one part could have unexpected results in other parts of the output.
The code of the nlme package is far from modular; e.g., parts of both
user-accessible and hidden functions of lme
were used in nlme
or
gls
causing lack of transparency. For example, within the function
print.summary.gls
, at some point the function print.summary.lme
was
used, which caused difficulties with passing the right degrees of
freedom of the likelihood. Different definitions of the likelihood
functions coded in C were used in the R-code of the same parent
functions, amongst others in lme
. Another critical point is that
utilities as print
, summary
or print.summary
functions tend to
recalculate again some statistics such as the likelihood, AIC or BIC.
For these reasons, debugging has been time consuming and given the
complexity of the nlme package the number of tests provided by CRAN is
simply too small. Thus, the warning ‘the use of free software comes with
no guarantee’ in the code of each of the functions must be taken in
earnest.
A general drawback of the algorithm used in nlme is that it is
completely geared to the use of the normal distribution. The latter
makes it difficult - though not impossible - to adapt the algorithm for
other distributions such as binomial or Poisson. The CRAN-library
already contains the package nlme4 allowing non-normal distributions,
but at this time lacks the feature of the use of correlated
observations. Perhaps a future update will be available that contains on
option for fixing the scale parameter
In the nlme
library of S-Plus the degrees of freedom for residual
error and consequently, the t-tests, are not properly adapted for fixed
anova
, the degrees of freedom has
been changed in S-Plus to allow comparison between models with and
without fixed
When comparing the output of nlme
between R and S-Plus, a flaw became
apparent in the output of anova
if used with a single object. The
F-tests for the (grouped) parameters differed between both programs. The
F-values from R can be made equivalent to those from S-Plus by
multiplying the F-values by nlme
in R, that there is no difference between ML and
REML estimation is remarkable and may be due to an error in the code or
to a compelling reason by the maintainer of the package.
From a statistical point of view, a warning should be issued on the use
of the likelihood ratio test when comparing two models; one with a fixed
and one with an estimated
Special thanks go to Martin Maechler for critically looking at the added code, running the CRAN tests independently and fine tuning our coding. We are greatly indebted to Mrs. Flowers Lovern for scrutinizing the English text, both on syntax and idiom.
Starting from a normal model with correlated errors, it is shown below
that this model can be converted into a model with independent errors
and equal variance. Let
A
ChemPhys, Econometrics, Environmetrics, Finance, MixedModels, OfficialStatistics, Psychometrics, Spatial, SpatioTemporal
This article is converted from a Legacy LaTeX article using the texor package. The pdf version is the official version. To report a problem with the html, refer to CONTRIBUTE on the R Journal homepage.
Text and figures are licensed under Creative Commons Attribution CC BY 4.0. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".
For attribution, please cite this work as
Heisterkamp, et al., "Update of the nlme Package to Allow a Fixed Standard Deviation of the Residual Error", The R Journal, 2017
BibTeX citation
@article{RJ-2017-010, author = {Heisterkamp, S.H. and Willigen, E. van and Diderichsen, P.M and Maringwa, J.}, title = {Update of the nlme Package to Allow a Fixed Standard Deviation of the Residual Error}, journal = {The R Journal}, year = {2017}, note = {https://rjournal.github.io/}, volume = {9}, issue = {1}, issn = {2073-4859}, pages = {239-251} }