View source: R/FUN_nonlinear_model.R
| nonlinear_curve | R Documentation |
Declares a native parametric link-predictor contribution for nonlinear mixed models fitted
by mmes.
nonlinear_curve(input, curve=c("exponential", "logistic", "saturation"),
random=list(), joint=NULL)
input |
Name of one numeric column in |
curve |
One of |
random |
Empty list or uniquely curve-parameter-named, one-term random
formulas for independent parameter effects, for example
|
joint |
Optional list with |
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.
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.
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))))
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.