Skip to content

Fix clmm() submodel fits with the cloglog and loglog links - #613

Merged
avehtari merged 5 commits into
masterfrom
clmm-cloglog
Nov 12, 2026
Merged

avehtari merged 5 commits into
masterfrom
clmm-cloglog

Conversation

@avehtari

@avehtari avehtari commented Nov 9, 2026

Copy link
Copy Markdown
Member

Summary

For a single group-level term (1 | <group>), ordinal::clmm() uses C code that swaps the links cloglog and loglog (runehaubo/ordinal#76, open). projpred passes the link of the reference model to clmm() in fit_cumul_mlvl(). Thus, for a brms::cumulative(link = "cloglog") reference model, projpred fitted the multilevel submodels with the loglog link. projpred then computed their predictions with the cloglog link in ordinal:::predict.clm(). Submodels with more than one group-level term use the R code of clmm(), which is correct.

Example with clmm() alone: data from a cumulative cloglog model with 4 categories, 400 observations and no group effect. ordinal 2025.12.29 and 2026.7-26 give the same numbers. The default clmm() fit has about the log-likelihood of the clm() loglog fit. With useMatrix = TRUE, it has about that of the clm() cloglog fit.

fit logLik
clm(link = "cloglog") -396.26
clm(link = "loglog") -415.77
clmm(y ~ x + (1 | g), link = "cloglog") -415.67
the same with clmm.control(useMatrix = TRUE) -396.12

In projpred (master fa9a9e1, ordinal 2026.7-26), I called fit_cumul_mlvl() with link = "cloglog" on augmented data. The data came from a cumulative cloglog model with the thresholds -0.8, 0.2 and 1.1 and with group effects (300 observations, 15 groups). The fit gave the thresholds 0.154, 1.092 and 2.198. The R code of clmm() gives -0.727, 0.235 and 1.089. The category probabilities from subprd_augdat() differed from the true category probabilities by up to 0.562 in absolute value (0.176 with the R code). Some predicted probabilities were 0 where the true probability was not, so the KL divergence was infinite.

Changes

This PR passes useMatrix = TRUE to clmm() for the cloglog and loglog links, so that clmm() uses its R code. clmm() then cannot use ucminf(), so these fits use the default nlminb() optimizer. They are about 4 to 6 times slower. One fit with 300 observations, 4 categories, 2 predictors and 20 groups took 0.45 to 0.68 s. The fit with the C code and ucminf() took 0.10 to 0.12 s. These are three runs on one laptop with ordinal 2025.12.29. The other links do not change. In ordinal:::getCtrlArgs(), a useMatrix argument in ... takes precedence over control, so the setting also applies when the user passes control.

Side effects

Two side effects for these two links:

  • clmm() with useMatrix = TRUE stops if nAGQ is not 1. projpred does not pass nAGQ to clmm(). A user who passes it in ... now gets this error instead of a fit with the wrong link.
  • A user argument method = "ucminf" gives the clmm() warning that clmm() uses nlminb() instead.

Documentation

The PR documents the exception for these two links in ?projpred-package. The regenerated man/projpred-package.Rd also moves the paragraph about ucminf() for clmm() (#596) to the ordinal::clmm() item, where the roxygen source has it. The old .Rd had it under the MASS::polr() item.

Tests

Tests:

  • New test in test_fit_cumul_mlvl.R. It uses data from a cloglog model and from a loglog model, both without group effects. The fit_cumul_mlvl() fit equals the clm() fit with the same link within expect_equal(tolerance = 0.05). Its largest absolute coefficient difference to that fit is less than 1/5 of the one to the clm() fit with the other link. Both hold with and without a control from the user. Without the change in R/divergence_minimizers.R, 6 of these expectations fail.
  • test_fit_cumul_mlvl.R uses withr::local_seed() instead of set.seed(), so the tests leave the random seed of the session unchanged (as required since Tests: leave the R session unchanged after the tests and remove the manual cleanup #586).
  • Full test suite with NOT_CRAN=true on 8c9fd76: 40 files, 58,045 expectations, 0 failures, 5 skipped. The later commits change only comments, documentation, NEWS and test_fit_cumul_mlvl.R. That test file passes on 7baf8ce (38 expectations).
  • Versions for the tests and the timing: R 4.6.1, testthat 3.3.2, ordinal 2025.12.29, ucminf 1.2.3, lme4 2.0.1, brms 2.23.0, rstanarm 2.36.0.9000. The projpred example above used ordinal 2026.7-26.

@avehtari avehtari added the bug Bugs. label Nov 9, 2026
@avehtari
avehtari merged commit a45cde1 into master Nov 12, 2026
5 checks passed
@avehtari
avehtari deleted the clmm-cloglog branch November 12, 2026 08:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Bugs.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants