MarcoThiel/MMAMixedEffects | Paclet Repository

MarcoThiel`MMAMixedEffects`

NonlinearMixedEffectsModelFit

NonlinearMixedEffectsModelFit[data,model,starts,{randomParameters,group},vars]
	fits nonlinear parameters with grouped Gaussian variation.

NonlinearMixedEffectsModelFit[data,model,starts,{{random1,group1},{random2,group2},...},vars]
	fits crossed or nested nonlinear random effects.

Details and Options

▪

fits nonlinear Gaussian mixed-effects models from Wolfram expressions.

▪

model is an ordinary Wolfram expression involving covariates and parameter symbols identified by starts.

▪

The model is y_i = f(x_i,beta,b_i) + epsilon_i. Random effects perturb named nonlinear parameters rather than adding directly to the response.

▪

Symbolic first and second derivatives are generated with D. The conditional Hessian includes the residual-times-second-derivative term, not only a Gauss-Newton approximation.

▪

model should be twice differentiable over the fitted parameter region. Nonsmooth constructs such as Abs, Clip, UnitStep, or branch points can make the symbolic Hessian discontinuous and should be replaced by a scientifically appropriate smooth formulation.

▪

The conditional-mode objective is pure: evaluating one outer parameter point does not depend on evaluation order or a cached mode from another point.

▪

Laplace and adaptive Gauss-Hermite integration include Gaussian normalization and residual-whitening determinants.

▪

Multiple random parameter blocks can be crossed, nested, correlated within a block, or independent across blocks.

▪

Weights, offsets, missing-row handling, residual correlations, and variance functions share their Gaussian linear semantics.

▪

Fixed-effect covariance is calculated from curvature of the optimized marginal objective.

▪

Good starting values and sensible parameter scaling remain important for nonlinear models; ConvergenceReport records the numerical evidence.

▪

Known-group prediction adds conditional parameter offsets. MarginalPredictedResponse integrates the nonlinear function over random effects.

▪

Long nonlinear fits report their current stage and objective-evaluation count in a temporary notebook panel unless ProgressReporting is False.

▪

The following options can be given:

Method	"ML"	Use "ML", "Laplace", or "AdaptiveGaussHermite" as convenient method aliases.
LikelihoodApproximation	"Laplace"	Use "Laplace" or "AdaptiveGaussHermite".
QuadratureOrder	7	Gauss-Hermite order per active independent component.
MaxQuadraturePoints	200000	Hard adaptive-quadrature grid limit.
InnerMaxIterations	120	Maximum conditional-mode iterations.
DegreesOfFreedomMethod	"Normal"	Nonlinear fixed effects use marginal-objective normal inference.
ResidualCorrelation	None	Within-block correlation: AR1, ContinuousAR1, CompoundSymmetry, ARMA, Unstructured, Exponential, Gaussian, or Spherical.
ResidualGrouping	Automatic	Expression defining independent residual blocks; Automatic uses the first grouping structure.
ResidualCovariate	Automatic	Time index or coordinate vector used by temporal or spatial residual correlation.
VarianceFunction	"Identity"	Relative residual standard deviations: Identity, ByLevel, Power, Exponential, ConstantPower, or Product.
VarianceCovariate	Automatic	Numeric covariate used by a variance function.
VarianceStrata	Automatic	Levels used by a ByLevel variance function.
Weights	Automatic	Observation weights. Gaussian fitters interpret these as inverse residual-variance weights; generalized fitters report their frequency-weight interpretation.
LinearOffsetFunction	None	A scalar, vector, function, or Wolfram expression added to the linear predictor.
MissingDataMethod	"Exclude"	Use "Exclude" for recorded listwise deletion or "Fail" to reject missing input.
MaxIterations	600	Maximum outer optimizer iterations.
AccuracyGoal	Automatic	Accuracy goal passed to the selected numerical optimizer.
PrecisionGoal	Automatic	Precision goal passed to the selected numerical optimizer.
WorkingPrecision	MachinePrecision	Working precision used by numerical optimization.
OptimizationMethod	Automatic	Use the validated model-specific optimizer strategy, or request a supported explicit optimizer method.
OptimizationStarts	3	Number of deterministic starts; the fit with the smallest valid objective is retained.
ConvergenceTolerance	5 5 10	Nonlinear scaled projected-gradient tolerance; this is forty times tighter than the 0.002 check used by lme4 while avoiding false failure labels at machine precision.
ConfidenceLevel	0.95	Confidence level used for reported fixed-effect intervals.
ProgressReporting	Automatic	Show a live notebook progress panel with the current stage, objective evaluations, best objective, start number, and elapsed time. Automatic is silent without a notebook front end.
EvaluationMonitor	None	An expression evaluated after each uncached marginal-objective evaluation; use RuleDelayed for side effects.
StepMonitor	None	An expression evaluated after each completed outer optimization start; use RuleDelayed for side effects.

▪

The fitted object supports the following property groups:

▪

Data and design

	"Data"	Rows used for fitting after missing-data processing.
	"Variables"	Ordered predictor and grouping variables.
	"IncludedRowIndices"	Original row indices retained for fitting.
	"ExcludedRowIndices"	Original row indices excluded from fitting.
	"FixedEffectsDesignMatrix"	Fixed-effect design matrix.
	"RandomEffectsDesignMatrix"	Sparse random-effect design matrix.

▪

Fixed effects

	"FixedEffects"	Association of fixed-effect estimates.
	"ParameterTableEntries"	Machine-readable parameter inference entries.
	"FixedEffectCovariance"	Estimated covariance matrix of fixed effects.
	"FixedEffectCorrelationMatrix"	Corresponding correlation matrix.

▪

Random and residual effects

	"RandomEffects"	Conditional modes grouped by random-effect structure.
	"RandomEffectCovariances"	Association of estimated covariance matrices.
	"ResidualVariance"	Gaussian residual variance, when applicable.
	"ResidualParameterEstimates"	Estimated residual correlation and variance-function parameters.

▪

Predictions and residuals

	"PopulationPredictedResponse"	Training predictions with random effects set to zero.
	"ConditionalPredictedResponse"	Training predictions using conditional random effects.
	"MarginalPredictedResponse"	Response-scale predictions integrated over random effects.
	"Residuals"	Conditional response residuals.
	"PearsonResiduals"	Variance-standardized residuals.
	"DevianceResiduals"	Signed deviance residuals when defined.

▪

Likelihood and diagnostics

	"LogLikelihood"	Constants-inclusive maximized or approximated log likelihood.
	"AIC"	Akaike information criterion.
	"BIC"	Bayesian information criterion.
	"ConvergenceReport"	Gradient, error, optimizer, mode, and tolerance diagnostics.
	"Converged"	True only when documented numerical gates pass.
	"SingularFit"	Whether a random-effect covariance lies on a rank boundary.
	"Warnings"	Statistical and numerical warnings retained with the fit.

▪

Nonlinear model

	"ModelExpression"	Original nonlinear Wolfram expression.
	"ParameterSymbols"	Ordered nonlinear parameters.
	"ConditionalParameterValues"	Observation-level parameter values after random effects.

Examples

(8)

Basic Examples

(1)

Fit the Orange logistic growth model with a tree-specific asymptote:

In[1]:=

orangeFit=

NonlinearMixedEffectsModelFit

orangeData,

asym

1+Exp

xmid-age

scal



,{asym200.`,xmid725.`,scal350.`},{{asym},tree},{age,tree}

Out[1]=

MixedEffectsModel[GaussianNonlinear, Laplace, 35 observations]

Obtain estimates and likelihood diagnostics:

In[1]:=

orangeFit[{"FixedEffects","RandomEffectCovariances","ResidualVariance","LogLikelihood"}]

Out[1]=

parameter	estimate
asym	192.053
xmid	727.906
scal	348.073
tree variance	1001.49
residual variance	61.5128
log likelihood	-131.572

Overlay the fitted population curve on the five observed tree trajectories: