View source: R/FUN_glmm_nominal.R
| multinomial | R Documentation |
Creates a nominal, unordered multinomial response family for native Laplace
mixed-model fitting with mmes.
multinomial(reference = NULL)
reference |
Optional label of the category used as the zero-logit reference. By default, the last declared response-factor level is used. |
This family supports unordered factors and plain integer category codes
1, ..., K. Ordered factors, character responses, matrices, noninteger
codes, and numeric codes with gaps are rejected. The response must contain
observations in every declared category after missing-data filtering.
For K categories the model estimates K-1 logits against the
reference category. For example, with reference="green", the logits
are \log(p_{red}/p_{green}) and
\log(p_{blue}/p_{green}). A softmax calculation converts these
comparisons to probabilities that sum to one. Changing the reference changes
the coefficient representation, not the category labels returned by public
methods.
Fit with maximum likelihood and the native Laplace method, for example:
mmes(y ~ x, random = ~ group, data = dat, family = multinomial(),
method = mmes_method(objective = "ml",
integration = "laplace")). At least one random-effect term is
required. The model uses category-specific fixed coefficients. Random effects
can be shared across comparisons (for example ~group) or category
specific using the internal .nominalCategory factor in the random
formula. The latter is added to the stacked design by the fitter.
The public fit requires the Henderson formulation and output$inverse=0;
uncertainty is deferred until after fitting. PQL, supplied
W, weights formulas, vcc, structured residual covariance,
and non-default Gaussian solver/acceleration controls are unsupported.
Random-effect relationships and covariance structures use the existing
mmes_control() and covariance-descriptor machinery. No new package
dependency is required.
Categorical familym supports nominal traits together with
ordinal and scalar traits, using one numeric long-format response column.
That route uses .familyCoordinate, not .nominalCategory, for
explicit category-specific random covariance terms, and returns trait-named
lists from fitted() and predict(). Existing random coefficients
are shared, not silently expanded into independent effects.
fitted() and predict() return a matrix of category probabilities
with the original response levels as columns; type="link" returns the
K-1 logits. Conditional prediction uses fitted modes for known random
levels, and re.form=NA sets random effects to zero.
re.form="population" integrates category probabilities over the fitted
Gaussian latent process, including temporal/spatial covariance, random slopes
and supplied relationship precision. Each observation uses its actual joint
logit covariance. Up to four categories and multiple independent terms are supported;
new independent group levels are allowed if the fixed design remains valid.
New independent groups require identity relationship precision; new covariance
coordinates or relationship levels outside the represented basis are rejected.
Averaged logits are not returned. Population standard errors/covariances
propagate all estimated outer parameters and report uncertainty="full".
Deterministic 24- and 32-point tensor normal quadrature on the active covariance
eigenspace must agree within 10^{-6} absolute probability; this
consistency check is not a guaranteed integration error bound. Estimated
workspace respects execution$denseMemoryMB. Population probabilities
are plug-in means under the fitted covariance, not calibrated uncertainty.
simulate() returns factors preserving
the original category labels and can draw new population random effects with
re.form="population".
Post-fit summary() and vcov() calculate fixed-effect uncertainty
from the numerical Hessian of the marginal Laplace objective. postPEV()
calculates random-effect posterior variances after fitting.
predict(se.fit=TRUE) uses the joint fixed/random conditional curvature;
its probability-scale standard errors use a delta-method transformation.
These default prediction standard errors condition on the fitted covariance
parameters. Opt-in predict(se.fit=TRUE, uncertainty="full") includes
covariance-parameter uncertainty and movement of conditional random modes
using the full marginal parameter covariance, plus random-mode posterior
covariance for conditional predictions. Zero-random-effect prediction uses
the marginal fixed-coefficient covariance. This post-fit first-order
approximation does not provide calibrated intervals or future-response noise.
Boundary, nonconverged, or non-positive-definite fits do not
receive success-shaped uncertainty. boot_mmes() supports nominal
parameter-recovery and nested fixed-effect refits by simulating population
random effects and refitting the joint softmax likelihood. Bootstrap draws
are reported on the fixed-coefficient and native covariance-coordinate
scales. Failed or nonconverged replicates remain in diagnostics, and
percentile intervals use successful refits only. This descriptive bootstrap
has not yet been calibrated as a replacement for Wald intervals.
The fitted object's laplaceDiagnostics separates the optimizer code
and message, scoreMax (largest absolute optimizer-coordinate score),
covariance boundary flags, and saturatedRows (rows whose largest fitted
probability is within \sqrt{\epsilon} of one, where \epsilon is
machine precision). Saturation suggests possible separation or weak
identification; it does not prove separation.
covarianceCondition reports the largest/smallest covariance eigenvalue
ratio per random term. Ratios exceeding \epsilon^{-1/3} trigger an
ill-conditioning advisory, not a new fit rejection or uncertainty gate.
issues provides actionable messages printed by summary(), and
uncertaintyStatus distinguishes deferred calculations from unavailable
uncertainty. These checks do not compute Hessians or PEV during fitting.
Unstructured nominal covariance precision derivatives use triangular-factor
solves to avoid cancellation near singularity.
Likelihood, AIC and BIC are available for the fitted nominal model, and
nested fixed-effect likelihood comparisons are supported when their response,
random structure and covariance specification match.
residuals(type="deviance") returns unsigned
\sqrt{-2\log p_{i,y_i}} magnitudes, evaluated stably from conditional
logits. Their squares sum to the conditional response deviance, not the
marginal Laplace likelihood deviance. Response/Pearson residuals retain their
labelled observation-by-category matrices; categories within a row are
dependent. Working/quantile residuals remain unsupported because no natural
nominal category ordering is imposed. These post-fit model checks are
descriptive, not calibrated outlier tests; see residuals.mmes.
Statistical calibration
for the nominal model remains a separate validation task.
An object of class "family" with class
"sommer_nominal_family".
mmes, ordinal, familym,
postPEV, predict.mmes
multinomial()
multinomial(reference = "control")
## Not run:
ctrl <- mmes_control()
fit <- mmes(color ~ treatment, random=~group, data=dat,
family=multinomial(reference="green"), control=ctrl,
method=mmes_method(objective="ml", integration="laplace"))
fitted(fit) # labelled category probabilities
predict(fit, re.form=NA) # random effects set to zero
predict(fit, re.form="population") # eligible population category means
summary(fit)$betas # post-fit fixed-effect uncertainty
simulate(fit, nsim=2, seed=10)
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.