View source: R/FUN_glmm_families.R
| ordinal | R Documentation |
Creates a cumulative-logit or cumulative-probit ordered-response family for
native Laplace models fitted with mmes, including categorical
familym compositions.
This experimental implementation requires maximum likelihood and the
Henderson formulation; it is not supported by PQL. Mixed-family responses
use numeric category codes; see familym.
ordinal(link = "logit", thresholds = NULL)
link |
Character string naming the cumulative link. Supported values are
|
thresholds |
Optional strictly increasing numeric threshold values used
to initialize the ordered category cutpoints. To hold them fixed, set
|
For categories 1,\ldots,K, the cumulative-link convention is
P(Y_i \leq k \mid u)=F(c_k-\eta_i), with
\eta_i=x_i'\beta+z_i'u+o_i. Here F is the standard logistic or
standard normal CDF and c_1<\cdots<c_{K-1} are cutpoints.
Thus positive predictor coefficients shift probability toward higher
categories. The internal kernel evaluates log category probabilities,
expected category codes, and predictor derivatives through fourth order for
supplied fixed cutpoints. Expected codes are not category probabilities and
depend on the numerical category coding.
The native objective jointly estimates a free first cutpoint and
log-positive successive gaps along with fixed effects and random covariance
parameters. Analytic cutpoint scores include random-mode and Laplace
determinant dependence. It rejects fixed-design confounding of cutpoint
locations and requires observations in every declared category when estimating
cutpoints. Response preparation preserves explicitly ordered factor levels,
or validates numeric integer category codes 1,\ldots,K with no gaps.
The response schema is checked before row filtering: unordered factors,
characters, matrices and non-integer codes are rejected rather than sorted,
collapsed or rounded. Ordered factors can declare absent levels, but estimating
their cutpoints requires observations in every declared category after the
standard response, fixed-covariate and random-covariate missing-data policies
are applied. With fixed cutpoints, absent ordered-factor levels are preserved.
Preparation reads thresholds and estimate from the
existing familyParameters list. Control-supplied thresholds
override constructor thresholds. With estimate=TRUE (the default),
unsupplied cutpoints start at the link-transformed retained cumulative category
frequencies. With estimate=FALSE, cutpoints must be supplied.
In both cases exactly K-1 cutpoints are required.
Estimating cutpoints removes the fixed-design intercept column without
rebuilding the factor contrasts; equivalent constant columns still error.
Fixed cutpoints retain the formula's intercept. Thus a no-intercept formula
that produces a full set of factor indicators is still confounded with free
cutpoint locations and is rejected.
An unrestricted predictor intercept and unrestricted cutpoint locations cannot both be identified.
The fitted object stores thresholds (cutpoint estimates with initially
missing standard errors), ordinal$levels and
category.probabilities. By default fitted(fit) and
predict(fit) return an observation-by-category probability matrix
with category labels as column names. Types "response" and
"probabilities" are equivalent; "link" returns the latent
predictor and "mean" returns the expected numeric category code.
The internal fitted.values vector also contains expected codes, not
category probabilities. Such means and response, Pearson and working
residuals depend on the chosen category coding. Deviance residuals use the
observed category log probability; randomized quantile residuals use its
cumulative-probability interval.
Conditional prediction uses fitted modes for known random levels.
re.form=NA sets random effects to zero. Population prediction
(re.form="population") integrates category probabilities over the
supported random covariance structures, using exact normal convolution for
probit and 24-node Gaussian quadrature for logit. Public simulations return
ordered factors with the original category levels; bootstrap refits use
numeric category codes internally and report absent-category failures.
All uncertainty is post-fit: summary() reports cutpoint standard
errors after transforming the joint marginal Hessian from log-gap coordinates,
and vcov() retains the fixed-effect covariance convention.
predict(se.fit=TRUE) includes joint cutpoint, fixed-effect and covariance
parameter uncertainty; conditional prediction also includes random-mode
posterior uncertainty. Probability standard errors have the same shape as
the probability matrix. With cov.fit=TRUE, the covariance is ordered
column-major: all rows for the first category, then all rows for the second,
and so on. postPEV() propagates joint parameter uncertainty through
the modes rather than silently conditioning on estimated cutpoints.
Nonconverged, near-boundary or non-positive-definite fits do not receive
success-shaped standard errors. No fit-time numerical Hessian or PEV is
computed, and no new package dependency is required.
Implementation tests do not establish coverage calibration or qualification for sparse categories, separation or weakly identified covariance parameters. An external targeted study of 3,000 paired datasets (both links, four categories and random intercepts) found all 1,200 regular-scenario fits converged and parameter-recovery gates passed, with 99.7–100 percent joint SE availability. Nevertheless 18 of 712 registered gates failed, mainly pointwise probability coverage/RMSE, so the full targeted inference envelope is not qualified. Regular probability coverage ranged from 90.3 to 98.0 percent; some Wilson intervals excluded nominal 95 percent. Sparse scenarios intentionally rejected absent categories and weak-variance scenarios often lacked usable uncertainty despite convergence. These findings do not qualify random-effect PEV coverage, fixed-cutpoint inference or general covariance. These findings motivated a further post-fit probability-interval calibration study. A subsequent held-out study of 1,200 fresh datasets compared paired Wald, logit-, probit- and arcsine-transformed probability intervals with fixed acceptance gates. They failed 8, 3, 4 and 5 of 96 pointwise cell gates respectively. None qualified across the full envelope, despite complete fit convergence and 99.7–100 percent SE availability. Transformations alone are not a demonstrated general coverage correction; the public SE API remains unchanged. These were delta intervals, not a refit-bootstrap study. The scalar link functions in this specification describe the cumulative link, not the expected category code. Scalar variance, deviance, AIC and GLM initialization methods explicitly error rather than returning placeholder results. The constructor itself does not validate any response.
An object of class "family".
mmes, familym, zipoisson
ordinal()
ordinal(link = "probit", thresholds = c(-1, 0.5, 2))
## Not run:
ctrl <- mmes_control()
fit <- mmes(rating ~ treatment, random=~group, data=dat,
family=ordinal(), control=ctrl,
method=mmes_method(objective="ml", integration="laplace"))
fitted(fit) # labelled category probabilities
predict(fit, re.form=NA)
summary(fit)$thresholds # uncertainty computed after fitting
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.