Baseline-category logit / softmax family for a single unordered categorical response with \(K \ge 3\) categories. For a categorical trait with categories \(1, \ldots, K\) and reference category 1, the model is \(\eta_{k} = \beta_{0k} + x^\top \beta_k\) for \(k = 2, \ldots, K\) with \(\eta_1 \equiv 0\), and \(\Pr(y = k) = \exp(\eta_k) / \sum_j \exp(\eta_j)\) (softmax). It recovers the \((K-1)\) per-category intercepts and slopes as contrasts against the reference category.
Details
This is a response family and must not be confused with the
categorical() constructor, which is a missing-predictor
imputation family. Because an unordered categorical response spans
\(K-1\) latent liability dimensions rather than one, the admitted
structured-term surface is bounded and every combination below was decided by
a signed recovery study, not construction alone.
Admitted: fixed effects always; an ordinary
shared latent(0 + trait | unit, d = k) ordination, which connects
a multinomial trait to other-family traits through its \(K-1\)
contrast pseudo-traits (the default unique = TRUE works, with the
categorical contrast \(\Psi\) mapped off); the intercept-only
phylogenetic-machinery tier in all three modes – phylo_latent(species,
d = k) (reduced-rank), phylo_dep() (full unstructured \(V\);
the identical phylo_rr parameterisation as
phylo_latent(d = K - 1)), and phylo_indep() (diagonal
\(V\); standalone phylo_unique() is its deprecated alias) –
together with their animal_*() (pedigree/A) and single-name
kernel_*() (dense K) twins, which run the same engine;
and the analogous spatial (SPDE) mode axis – spatial_latent(0 +
trait | coords, d = k) (loadings-only), spatial_indep()
(per-contrast independent fields), and spatial_dep() (verified
identical to spatial_latent(d = n_traits)). All of the
phylogenetic/relatedness cells are loadings-only: none emits a
\(\Psi\) companion, and unique = TRUE (a free phylogenetic
\(\Psi\)) is NOT admitted.
Recovery evidence: on the phylogenetic/relatedness surface, the
one-categorical-draw-per-species study did not meet its prespecified criterion
(rail rate 8/20 against a 6/20 threshold, identically for
phylo_latent()/animal_latent()/kernel_latent() by
proven engine identity; phylo_dep() rails 8/20 separately). A
pre-registered replication study – five categorical draws per species
rather than one – met the criterion for the loadings-only and full-\(V\) combinations
(rail rate 4/20, median \(\hat\rho\) 0.680 against a true 0.6) but has
NOT been tested for phylo_indep()'s diagonal-\(V\) mode, whose
own corrected rerun independently did not meet the criterion (small contrast
variances collapse; a planted-zero check fails). The spatial mode axis and the
(1 | group) route below both met their signed recovery criteria
outright, with no replication rescue needed. One categorical
draw per species does not identify \(V\); five draws per species
does.
A generic (1 | group)
random intercept is also admitted, but its semantics are
baseline-vs-rest, not per-category: the engine adds one draw per
group level to EVERY one of a multinomial observation's \(K-1\)
baseline-contrast rows, which shifts \(P(y = \text{baseline})\) versus
\(P(y \ne \text{baseline})\) without changing the odds between any two
NON-baseline categories (within one fit, across groups). sigma_re's
substantive interpretation is therefore reference-category-
specific, and re-labelling the baseline is not a
reparameterisation of the same model: under baseline = 1 the shared
draw constrains the log-odds between the two non-baseline categories to be
constant across groups, while under a different baseline the SAME
engine shares a (new) draw between a different pair of categories instead
– a different parametric restriction, not the same distribution
relabelled. Re-fitting under a different baseline therefore changes
the fitted response-scale probabilities too, not only sigma_re.
The non-phylogenetic cluster /
cluster2 diagonal tier (indep(0 + trait | g) via the
cluster/cluster2 arguments to gllvmTMB, and its
soft-deprecated standalone unique() alias) is admitted as
per-contrast independent variances – the per-category random intercept
most users want – but common = TRUE (the scalar() modifier)
at that tier is NOT admitted. Both the (1 | group) and cluster/
cluster2 routes abort typed if every level of the grouping factor covers
exactly one categorical observation: that is an observation-level random
effect (OLRE) in disguise, unidentifiable because the softmax latent scale
is fixed.
Refused, not merely deferred: phylo_scalar() /
animal_scalar() / kernel_scalar() / spatial_scalar()
and common = TRUE at the cluster/cluster2 tier – a single shared
level across the \(K-1\) contrasts has no interpretable null on the
\((I+J)\) contrast geometry, as confirmed in a null-generating simulation.
Everything else is still deferred and fails with an explicit error
rather than reaching an untested
categorical path: dep(), explicit unique() /
indep() at the unit tier, latent()/dep() at the
cluster/cluster2 tiers, and the unit_obs grouping
tier; augmented (intercept + slope) forms of every admitted keyword above;
unique = TRUE on phylo_latent()/animal_latent()/
kernel_latent() (a free phylogenetic \(\Psi\)) and
spatial_latent()'s paired diagonal companion; standalone
spatial_unique()/deprecated bare spatial() (a
paired-companion alias mechanism, unlike the phylogenetic mode axis's
*_unique(), which IS admitted); multi-kernel (more than one
kernel_latent()/kernel_dep()/kernel_indep() name in
one fit); meta_V() / equalto() (confirmed Gaussian-only, no
route on a categorical-contrast pseudo-trait); and mi() predictor
terms.
A two-category response is exactly binomial(link = "logit") and is
redirected there. See also ordinal_probit() for ordered
categories.
See also
ordinal_probit() for ordered categories; categorical() for the
missing-predictor imputation namesake.