nonlinear_curve: Traditional nonlinear mixed-model curves

View source: R/FUN_nonlinear_model.R

nonlinear_curveR Documentation

Traditional nonlinear mixed-model curves

Description

Declares a native parametric link-predictor contribution for nonlinear mixed models fitted by mmes.

Usage

nonlinear_curve(input, curve=c("exponential", "logistic", "saturation"),
                random=list(), joint=NULL)

Arguments

input

Name of one numeric column in data.

curve

One of "exponential", "logistic" or "saturation".

random

Empty list or uniquely curve-parameter-named, one-term random formulas for independent parameter effects, for example list(rate=~vsm(ism(subject), sigma2=0.04)). Existing formulas are unchanged.

joint

Optional list with parameters (at least two unique curve parameter names) and one random formula, for example list(parameters=c("asymptote","rate"), random=~vsm(usm(.parameter),ism(subject))). The internal .parameter axis has the declared parameter order. Joint and independent parameter names must be disjoint.

Details

The supported curves are

A\exp(-kx),

A/(1+\exp(-k(x-m))),

and

Ax/(K+x).

Their named parameters are asymptote, rate (exponential and logistic), midpoint (logistic), and half (saturation). All except midpoint are strictly positive and optimized on the log scale. Exponential and saturation inputs must be non-negative. There is no automatic input scaling.

With random=list(), joint=NULL, the curve is a fixed mean and ordinary random effects are additive Gaussian terms. A nonempty random list declares Gaussian deviations in named curve coordinates: log scale for positive parameters, identity for midpoint. For example, random rate means \log(k_j)=\log(k)+b_j. The shared positive parameter is the zero-deviation value (and marginal median), not its arithmetic mean. All curve parameters may vary, optionally together with independent ordinary additive effects. Separate named formulas specify independent parameter blocks, even when their grouping variables coincide. The joint block permits correlated Gaussian deviations using the existing vsm() covariance syntax. It may coexist with independent formulas for other parameters (for example midpoint). Cross-covariance with ordinary additive effects remains unsupported. Each observation must select exactly one unit incidence for each declared random curve parameter; random slopes and overlapping loadings are rejected. Shaped native covariance descriptors and known positive-definite relationship precisions use the existing covariance machinery. The joint .parameter axis must occur exactly once as a covariance-shaping factor, not as the final grouping term. It is generated internally in the declared order and must not be a data column. No user-data stacking is needed and no response is replicated. For example usm(.parameter) specifies an unstructured covariance among log-asymptote and log-rate deviations; ism(subject) supplies the grouping basis and Gu retains its usual known-precision meaning. Additional shaping factors and rrm() retain their descriptor semantics. Group-parameter rows align by covariance/group labels across independent blocks; a parameter with no deviation for a row uses its shared coordinate. Multiple-parameter covariance term labels are prefixed by curve[parameter] (or the comma-separated joint parameter names), so identical grouping formulas remain distinguishable in reporting and named constraints. Their parameter indices and existing vcc mapping semantics are unchanged. Multiple-parameter curveRandomMode names include both the parameter and group-coordinate label. Joint second and third derivatives include all cross-parameter terms. Random covariance factors must have native or fixed evaluators and native analytic (or parameter-free) derivatives. The built-in rrm() is also supported through its native normalized loading map, rather than its R covariance evaluator. Arbitrary R callbacks and numerical covariance derivatives are rejected. Dedicated numerical checks cover ism(), dsm(), usm(), ar1m(), csm(), heterogeneous and homogeneous fam(), and rrm(), including representative Kronecker products. This is not a blanket guarantee for every covariance constructor. For Gaussian identity observations, integration is exact Gaussian ML for purely additive effects and Laplace ML for random curve parameters. Family-aware Laplace uses the exact conditional Hessian, including likelihood-score-times-second-derivative terms, and full analytic outer scores including mode motion. This native mixed-model route requires at least one random term (additive or curve); fixed-only curves use the reference specification route. Full-coordinate covariance must be positive definite, except for built-in reduced-rank factors. For rrm(), the effect is represented as b=L v, with a proper Gaussian prior on latent v. Loading parameters remain jointly estimated, and analytic scores include the moving loading map. No inverse of singular covariance, artificial specific variance or diagonal ridge is introduced. Relationship precision and the latent prior must remain positive definite; exact zero overall variance is not accepted. With additive random effects retained, remove the curve-random declaration to fit the zero-curve-variance model. Exact zero is never replaced silently by a small positive variance. Independent homogeneous Gaussian residuals are supported; structured observation residuals are not.

Response families reuse the native likelihoods: binomial with logit, probit or cloglog link; Poisson, NB2, Gamma and zero-inflated Poisson with log link; Gaussian identity; ordinal logit/probit; nominal softmax; and rowwise familym() mixtures, including categorical traits. Apart from the existing exact Gaussian additive route, these use Laplace ML. The curve is added to the link predictor, not the response mean. It is shared across traits and across every nonreference nominal logit; separate nonlinear parameter sets by category or trait are not introduced. Existing categorical linear-design conventions still apply, including .nominalCategory for a standalone nominal model and .familyCoordinate for mixtures. Single categorical responses may be factors; categorical mixtures use numeric category codes as in ordinary native Laplace models.

Numerical choices belong to mmes_control. optimizer accepts algorithm="nlminb" and gradient="analytic". Supply a complete named vector of natural-scale curve starts through mmes(start=list(parameters=...)), or omit it for deterministic automatic initialization. Supplying start overrides automatic initialization. Automatic starts are deterministic and require input variation and a positive response maximum after subtracting the offset. They do not consume random numbers. For non-Gaussian models automatic starts use unit link-scale amplitude; supplied starts are recommended. No silent numerical-gradient or optimizer fallback is performed. Family nuisance parameters use the existing familyParameters list (trait-nested for familym()), including fixed/estimated NB2 shape, Gamma/Gaussian dispersion, zero-inflation probability and ordinal thresholds. Other GLMM fitting controls do not apply. Zero-component regression uses zipoisson(zero=~...).

For Laplace fits, mode defaults to list(maxit=100L, tol=1e-8, stepTol=1e-8, warmStart="auto", starts="deterministic"). Here "auto" selects deterministic cold starts, equivalent to "off". Safeguarded Newton steps compare zero and +/-0.5 curve-coordinate starts (latent curve coordinates for reduced-rank terms). Final curvature must be positive definite without damping; failures, score norms, iterations and competing modes are reported. This is not a global-mode guarantee. Warm starts and stochastic starts are not supported.

Use convergence$maxIters, convergence$likelihoodTol and convergence$parameterTol for the outer optimizer. The latter tolerances map to nlminb relative objective and parameter-step tolerances. Resource admission uses execution$denseMemoryMB; thread policy uses execution$blasThreads. Unsupported non-default controls are rejected. Sparse-support components bound Hessian/factor workspace before sparse products are assembled; a large connected relationship graph can be refused conservatively even if its actual fill would fit. This budget is not a process-wide RSS limit. diagnostics$profile="force" enables fitting phase timings, and profile_nonlinear measures separate inclusive kernels, dimensions, work counts and retained object sizes after fitting.

The combined ordinary/nonlinear mean must be locally identifiable. Starts with rank-deficient mean derivatives are rejected; rank deficiency at the accepted fit warns. Nonlinear optimization can have local optima; convergence and final scores are reported, not a guarantee of a global optimum.

Fitting returns point estimates only. PEV and all uncertainty are explicitly post-fit processes; see post_nonlinear for observed parameter curvature, natural-scale covariance, conditional-mode covariance, approximate PEV and prediction intervals. postPEV() dispatches to this nonlinear implementation; vcov() and uncertainty prediction arguments request operation-local post-fit calculations. Summaries display saved uncertainty, or compute it only when explicitly requested with inference=TRUE. predict(re.form=NULL) uses conditional modes; predict(re.form=NA) uses zero random deviations. predict(re.form="population") integrates the curve against its fitted Gaussian prior, not a mode/parameter uncertainty distribution. It generally differs from zero-deviation prediction for random curves. For non-Gaussian responses, additive effects also change the population response mean. Their joint prior, including within-observation nominal predictor covariance, is integrated; link output integrates the predictor and response output integrates means or category probabilities. Gaussian quadrature compares increasing orders with population=list(order=20L, maxOrder=160L, tol=1e-7); failure to meet scaled agreement is an explicit error. Conditional and population new-data predictions require represented random levels and the fitted covariance basis. Fitted groupParameters and curveRandomMode expose natural-scale group parameters and coordinate modes. For reduced-rank models, randomMode and curveRandomMode are restored to the original full coordinates; latentRandomMode and randomCoordinates retain the latent point mode and dimension metadata. Population means use the implied full-coordinate marginal prior variance, including singular positive-semidefinite reduced-rank covariance. fitted(type="link") and predict(type="link") return link-scale predictors; response output is numeric for scalar families, category-probability matrices for ordinal/nominal models, and trait-named lists for categorical mixtures. Residual types retain the existing native-family conventions; unordered nominal working/quantile residuals are undefined and rejected. simulate(nsim=1, seed=NULL, re.form="conditional", maxMemoryMB=NULL) draws observations at fitted modes; re.form="population" draws new random effects from their fitted prior before evaluating the curve and response likelihood. Explicit seeds restore the caller's RNG state. These are generative draws, not PEV or parameter-uncertainty products.

Value

A versioned, serializable sommer_nonlinear_curve specification. The fitted object has class mmes.nonlinear, inheriting from mmes. coef() reports ordinary fixed and natural-scale curve parameters; summary() reports estimates and diagnostics only.

Examples

set.seed(12)
dat <- data.frame(x=rep(seq(0, 5, length.out=10), 12),
                  group=factor(rep(seq_len(12), each=10)))
dat$y <- 4*exp(-0.6*dat$x) + rnorm(12, sd=0.3)[dat$group] +
  rnorm(nrow(dat), sd=0.15)
model <- nonlinear_curve("x", "exponential")
fit <- mmes(y~0+curve_term("growth"), random=~group, data=dat,
  curves=list(growth=model),
  method=mmes_method(objective="ml"),
  start=list(parameters=c(asymptote=4, rate=0.5)),
  control=mmes_control(
    convergence=list(maxIters=300),
    diagnostics=list(verbose=FALSE, dateWarning=FALSE)))
coef(fit)
predict(fit, newdata=dat[1:3, ])
predict(fit, newdata=data.frame(x=c(1, 2)), re.form=NA)

model <- nonlinear_curve("x", random=list(
  rate=~vsm(ism(group), sigma2=0.04)))
independent <- nonlinear_curve("x", random=list(
  asymptote=~vsm(ism(group)), rate=~vsm(ism(group))))
correlated <- nonlinear_curve("x", joint=list(
  parameters=c("asymptote","rate"),
  random=~vsm(usm(.parameter),ism(group))))
# Ordinary additive effects may be added with mmes(random=~group).
# Structured rate deviations:
# nonlinear_curve("x", random=list(
#   rate=~vsm(rrm(environment, k=1), ism(group))))

sommer documentation built on Nov. 14, 2026, 5:07 p.m.