Documentation 
Nonlinear mixedeffects estimation
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)
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, or a cell array of strings. 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 of X.
k = n_{i} if XFUN contains the rows of X for a single group of size n_{i}.
k = n if XFUN contains all rows of X.
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 group I.
If V is empty, nlmefit calls modelfun 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 model
logl — The maximized loglikelihood for the fitted model
rmse — The square root of the estimated error variance (computed on the log scale for the exponential error model)
errorparam — The estimated parameters of the error variance model
aic — The Akaike information criterion, calculated as aic = 2 * logl + 2 * numParam, where numParam 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, and logl is a field in the stats structure
bic — The Bayesian information criterion, calculated as bic = –2*logl + log(M) * numParam
M is the number of groups.
numParam and logl are defined as in aic.
Note that some literature suggests that the computation of bic should be , bic = –2*logl + log(N) * numParam, where N is the number of observations.
covb — The estimated covariance matrix of the parameter estimates
sebeta — The standard errors for beta
ires — The population residuals (yy_population), where y_population is the individual predicted values
pres — The population residuals (yy_population), where y_population is the population predicted values
iwres — The individual weighted residuals
pwres — The population weighted residuals
cwres — 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,'Name',value) specifies one or more optional parameter name/value pairs. Specify 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 PHI include a fixed effect, given as a numeric vector of indices from 1 to p or as a 1byp logical vector. If q is the specified number of elements, then the model includes q fixed effects. 
FEConstDesign  A pbyq design matrix ADESIGN, where ADESIGN*beta are the fixed components of the p elements of PHI. 
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 PHI include a random effect, given as a numeric vector of indices from 1 to p or as a 1byp logical vector. The model includes r random effects, where r is the specified number of elements. 
REConstDesign  A pbyr design matrix BDESIGN, where BDESIGN*B are the random components of the p elements of PHI. 
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 nlmefit makes an initial refinement of beta0 by first fitting modelfun without random effects and replacing beta0 with beta. Choices are 'on' and 'off'. The default value is 'on'. 
ErrorModel  A string specifying the form of the error term. Default is 'constant'. Each model defines the error using a standard normal (Gaussian) variable e, the function value f, and one or two parameters a and b. Choices are:
If this parameter is given, the output stats.errorparam field has the value

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

Vectorization  Indicates acceptable sizes for the PHI, XFUN, and VFUN input arguments to modelfun. Choices are:

CovParameterization  Specifies the parameterization used internally for the scaled covariance matrix. Choices are 'chol' for the Cholesky factorization or 'logm' the matrix logarithm. The default is 'logm'. 
CovPattern  Specifies an rbyr logical or numeric matrix P that defines the pattern of the randomeffects covariance matrix PSI. nlmefit estimates the variances along the diagonal of PSI and the covariances specified by nonzeros in the offdiagonal elements of P. Covariances corresponding to zero offdiagonal elements in P are constrained to be zero. If P does not specify a rowcolumn permutation of a block diagonal matrix, nlmefit adds nonzero elements to P as needed. The default value of P is eye(r), corresponding to uncorrelated random effects. Alternatively, P may be a 1byr vector containing values in 1:r, with equal values specifying groups of random effects. In this case, nlmefit estimates covariances only within groups, and constrains covariances across groups to be zero. 
ParamTransform  A vector of pvalues specifying a transformation function f() for each of the P parameters: XB = ADESIGN*BETA + BDESIGN*B PHI = f(XB). Each element of the vector must be one of the following integer codes specifying the transformation for the corresponding value of PHI:

Options  A structure of the form returned by statset. nlmefit uses the following statset parameters:

OptimFun  Specifies the optimization function used in maximizing the likelihood. Choices are 'fminsearch' to use fminsearch or 'fminunc' to use fminunc. The default is 'fminsearch'. You can specify 'fminunc' only if Optimization Toolbox™ software is installed. 
[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.