nlmer {lme4}  R Documentation 
Fitting Nonlinear MixedEffects Models
Description
Fit a nonlinear mixedeffects model (NLMM) to data, via maximum likelihood.
Usage
nlmer(formula, data = NULL, control = nlmerControl(),
start = NULL, verbose = 0L, nAGQ = 1L, subset, weights, na.action,
offset, contrasts = NULL, devFunOnly = FALSE)
Arguments
formula 
a threepart “nonlinear mixed model” formula, of
the form 
data 
an optional data frame containing the variables named in

control 
a list (of correct class, resulting from

start 
starting estimates for the nonlinear model parameters, as a named numeric vector or as a list with components

verbose 
integer scalar. If 
nAGQ 
integer scalar  the number of points per axis for evaluating the adaptive GaussHermite approximation to the loglikelihood. Defaults to 1, corresponding to the Laplace approximation. Values greater than 1 produce greater accuracy in the evaluation of the loglikelihood at the expense of speed. A value of zero uses a faster but less exact form of parameter estimation for GLMMs by optimizing the random effects and the fixedeffects coefficients in the penalized iteratively reweighted least squares (PIRLS) step. 
subset 
an optional expression indicating the subset of the rows
of 
weights 
an optional vector of ‘prior weights’ to be used
in the fitting process. Should be 
na.action 
a function that indicates what should happen when the
data contain 
offset 
this can be used to specify an a priori known
component to be included in the linear predictor during fitting.
This should be 
contrasts 
an optional 
devFunOnly 
logical  return only the deviance evaluation function. Note that because the deviance function operates on variables stored in its environment, it may not return exactly the same values on subsequent calls (but the results should always be within machine tolerance). 
Details
Fit nonlinear mixedeffects models, such as those used in population pharmacokinetics.
Note
Adaptive GaussHermite quadrature (nAGQ > 1
) is not
currently implemented for nlmer
. Several other
methods, such as simulation or prediction with new data,
are unimplemented or very lightly tested.
A method
argument was used in earlier versions of the lme4
package. Its functionality has been replaced by the nAGQ
argument.
Examples
## nonlinear mixed models  3part formulas 
## 1. basic nonlinear fit. Use stats::SSlogis for its
## implementation of the 3parameter logistic curve.
## "SS" stands for "selfstarting logistic", but the
## "selfstarting" part is not currently used by nlmer ... 'start' is
## necessary
startvec < c(Asym = 200, xmid = 725, scal = 350)
(nm1 < nlmer(circumference ~ SSlogis(age, Asym, xmid, scal) ~ AsymTree,
Orange, start = startvec))
## 2. rerun with "quick and dirty" PIRLS step
(nm1a < update(nm1, nAGQ = 0L))
## 3. Fit the same model with a userbuilt function:
## a. Define formula
nform < ~Asym/(1+exp((xmidinput)/scal))
## b. Use deriv() to construct function:
nfun < deriv(nform,namevec=c("Asym","xmid","scal"),
function.arg=c("input","Asym","xmid","scal"))
nm1b < update(nm1,circumference ~ nfun(age, Asym, xmid, scal) ~ Asym  Tree)
## 4. Userbuilt function without using deriv():
## derivatives could be computed more efficiently
## by precomputing components, but these are essentially
## the gradients as one would derive them by hand
nfun2 < function(input, Asym, xmid, scal) {
value < Asym/(1+exp((xmidinput)/scal))
grad < cbind(Asym=1/(1+exp((xmidinput)/scal)),
xmid=Asym/(1+exp((xmidinput)/scal))^2*1/scal*
exp((xmidinput)/scal),
scal=Asym/(1+exp((xmidinput)/scal))^2*
(xmidinput)/scal^2*exp((xmidinput)/scal))
attr(value,"gradient") < grad
value
}
stopifnot(all.equal(attr(nfun(2,1,3,4),"gradient"),
attr(nfun(2,1,3,4),"gradient")))
nm1c < update(nm1,circumference ~ nfun2(age, Asym, xmid, scal) ~ Asym  Tree)