nlmefit
Nonlinear mixedeffects estimation
Syntax
beta = nlmefit(X,y,group,V,fun,beta0)
[beta,PSI] = nlmefit(X,y,group,V,fun,beta0)
[beta,PSI,stats] = nlmefit(X,y,group,V,fun,beta0)
[beta,PSI,stats,B] = nlmefit(X,y,group,V,fun,beta0)
[beta,PSI,stats,B] = nlmefit(X,y,group,V,fun,beta0,'Name
',value
)
Description
beta = nlmefit(X,y,group,V,fun,beta0)
fits
a nonlinear mixedeffects regression model and returns estimates of
the fixed effects in beta
. By default, nlmefit
fits
a model in which each parameter is the sum of a fixed and a random
effect, and the random effects are uncorrelated (their covariance
matrix is diagonal).
X
is an nbyh matrix
of n observations on h predictors.
y
is an nby1 vector
of responses.
group
is a grouping variable indicating m groups in the
observations. group
is a categorical variable, a numeric vector, a character
matrix with rows for group names, a string array, or a cell array of character vectors. For more
information on grouping variables, see Grouping Variables.
V
is an mbyg matrix
or cell array of g groupspecific predictors. These
are predictors that take the same value for all observations in a
group. The rows of V
are assigned to groups using grp2idx
, according to the order specified
by grp2idx(group)
. Use a cell array for V
if
group predictors vary in size across groups. Use []
for V
if
there are no groupspecific predictors.
fun
is a handle to a function that accepts
predictor values and model parameters and returns fitted values. fun
has
the form
yfit = modelfun(PHI,XFUN,VFUN)
The arguments are:
PHI
— A 1byp vector of model parameters.XFUN
— A kbyh array of predictors, where:k = 1 if
XFUN
is a single row ofX
.k = n_{i} if
XFUN
contains the rows ofX
for a single group of size n_{i}.k = n if
XFUN
contains all rows ofX
.
VFUN
— Groupspecific predictors given by one of:A 1byg vector corresponding to a single group and a single row of
V
.An nbyg array, where the jth row is V(
I
,:) if the jth observation is in groupI
.
If
V
is empty,nlmefit
callsmodelfun
with only two inputs.yfit
— A kby1 vector of fitted values
When either PHI
or VFUN
contains
a single row, it corresponds to all rows in the other two input arguments.
Note
If modelfun
can compute yfit
for
more than one vector of model parameters per call, use the 'Vectorization'
parameter
(described later) for improved performance.
beta0
is a qby1 vector
with initial estimates for q fixed effects. By
default, q is the number of model parameters p.
nlmefit
fits the model by maximizing an
approximation to the marginal likelihood with random effects integrated
out, assuming that:
Random effects are multivariate normally distributed and independent between groups.
Observation errors are independent, identically normally distributed, and independent of the random effects.
[beta,PSI] = nlmefit(X,y,group,V,fun,beta0)
also
returns PSI
, an rbyr estimated
covariance matrix for the random effects. By default, r is
equal to the number of model parameters p.
[beta,PSI,stats] = nlmefit(X,y,group,V,fun,beta0)
also
returns stats
, a structure with fields:
dfe
— The error degrees of freedom for the modellogl
— The maximized loglikelihood for the fitted modelrmse
— The square root of the estimated error variance (computed on the log scale for theexponential
error model)errorparam
— The estimated parameters of the error variance modelaic
— The Akaike information criterion, calculated asaic
= 2 *logl
+ 2 *numParam
, wherenumParam
is the number of fitting parameters, including the degree of freedom for covariance matrix of the random effects, the number of fixed effects and the number of parameters of the error model, andlogl
is a field in thestats
structurebic
— The Bayesian information criterion, calculated asbic
= –2*logl
+ log(M
) *numParam
M
is the number of groups.numParam
andlogl
are defined as inaic
.
Note that some literature suggests that the computation of
bic
should be ,bic
= –2*logl
+ log(N
) *numParam
, whereN
is the number of observations.covb
— The estimated covariance matrix of the parameter estimatessebeta
— The standard errors forbeta
ires
— The population residuals(yy_population)
, wherey_population
is the individual predicted valuespres
— The population residuals(yy_population)
, wherey_population
is the population predicted valuesiwres
— The individual weighted residualspwres
— The population weighted residualscwres
— The conditional weighted residuals
[beta,PSI,stats,B] = nlmefit(X,y,group,V,fun,beta0)
also
returns B
, an rbym matrix
of estimated random effects for the m groups. By
default, r is equal to the number of model parameters p.
[beta,PSI,stats,B] = nlmefit(X,y,group,V,fun,beta0,'
specifies
one or more optional parameter name/value pairs. Specify Name
',value
)Name
inside
single quotes.
Use the following parameters to fit a model different from the
default. (The default model is obtained by setting both FEConstDesign
and REConstDesign
to eye(p)
,
or by setting both FEParamsSelect
and REParamsSelect
to 1:p
.)
Use at most one parameter with an 'FE'
prefix
and one parameter with an 'RE'
prefix. The nlmefit
function
requires you to specify at least one fixed effect and one random effect.
Parameter  Value 

FEParamsSelect  A vector specifying which elements of the parameter vector 
FEConstDesign  A pbyq design
matrix 
FEGroupDesign  A pbyqbym array specifying a different pbyq fixedeffects design matrix for each of the m groups. 
FEObsDesign  A pbyqbyn array specifying a different pbyq fixedeffects design matrix for each of the n observations. 
REParamsSelect  A vector specifying which elements of the parameter vector 
REConstDesign  A pbyr design
matrix 
REGroupDesign  A pbyrbym array specifying a different pbyr randomeffects design matrix for each of m groups. 
REObsDesign  A pbyrbyn array specifying a different pbyr randomeffects design matrix for each of n observations. 
Use the following parameters to control the iterative algorithm for maximizing the likelihood:
Parameter  Value 

RefineBeta0  Determines whether 
ErrorModel  A character vector or string scalar specifying the form of the error term. Default is
If this parameter is given, the output

ApproximationType  The method used to approximate the likelihood of the model. Choices are:

Vectorization  Indicates acceptable sizes for the

CovParameterization  Specifies the parameterization used internally for the
scaled covariance matrix. Choices are 
CovPattern  Specifies an rbyr logical
or numeric matrix Alternatively, 
ParamTransform  A vector of pvalues specifying
a transformation function f() for each of the

Options  A structure of the form returned by

OptimFun  Optimization function for the estimation process that maximizes a likelihood function,
specified as 
Examples
References
[1] Lindstrom, M. J., and D. M. Bates. “Nonlinear mixedeffects models for repeated measures data.” Biometrics. Vol. 46, 1990, pp. 673–687.
[2] Davidian, M., and D. M. Giltinan. Nonlinear Models for Repeated Measurements Data. New York: Chapman & Hall, 1995.
[3] Pinheiro, J. C., and D. M. Bates. “Approximations to the loglikelihood function in the nonlinear mixedeffects model.” Journal of Computational and Graphical Statistics. Vol. 4, 1995, pp. 12–35.
[4] Demidenko, E. Mixed Models: Theory and Applications. Hoboken, NJ: John Wiley & Sons, Inc., 2004.