multinomial: Nominal multinomial family specification

View source: R/FUN_glmm_nominal.R

multinomialR Documentation

Nominal multinomial family specification

Description

Creates a nominal, unordered multinomial response family for native Laplace mixed-model fitting with mmes.

Usage

multinomial(reference = NULL)

Arguments

reference

Optional label of the category used as the zero-logit reference. By default, the last declared response-factor level is used.

Details

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.

Value

An object of class "family" with class "sommer_nominal_family".

See Also

mmes, ordinal, familym, postPEV, predict.mmes

Examples

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)

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