clmstan

Cumulative Link Models with CmdStanR

Overview

clmstan fits cumulative link models (CLMs) for ordinal categorical data using CmdStanR. It supports 11 link functions including standard links (logit, probit, cloglog) and flexible parametric links (GEV, AEP, Symmetric Power).

Models are pre-compiled using the instantiate package for fast execution without runtime compilation.

Documentation

Full documentation is available at: https://t-momozaki.github.io/clmstan/

Installation

Prerequisites

This package requires:

1. CmdStan - Stan's command-line interface
2. cmdstanr - R interface to CmdStan (not on CRAN)

Step 1: Install cmdstanr

# Install cmdstanr from r-universe (recommended)
install.packages("cmdstanr",
                 repos = c("https://stan-dev.r-universe.dev",
                           getOption("repos")))

Step 2: Install CmdStan

library(cmdstanr)
install_cmdstan()  # Only needed once

Step 3: Install clmstan

# From CRAN (when available)
install.packages("clmstan")

# From GitHub (development version)
# install.packages("devtools")
devtools::install_github("t-momozaki/clmstan")

Note: During package installation, Stan models are compiled automatically. This may take a few minutes on first install.

Quick Start

library(clmstan)

# Example data
set.seed(123)
n <- 100
x <- rnorm(n)
latent <- 1.0 * x + rlogis(n)
y <- cut(latent, breaks = c(-Inf, -1, 0, 1, Inf), labels = 1:4)
data <- data.frame(y = y, x = x)

# Fit a cumulative link model with logit link
fit <- clm_stan(y ~ x, data = data, link = "logit",
                chains = 4, iter = 2000, warmup = 1000)

# View results
fit$fit$summary(variables = c("beta", "c_transformed", "beta0"))

Supported Link Functions

Standard Links (5)

Flexible Links with Parameters (6)

Using Flexible Links

# Fixed parameter
fit_t <- clm_stan(y ~ x, data = data, link = "tlink",
                  link_param = list(df = 8))

# Estimate parameter with Bayesian inference
fit_gev <- clm_stan(y ~ x, data = data, link = "gev",
                    link_param = list(xi = "estimate"))

Threshold Structures

# Equidistant thresholds
fit_equi <- clm_stan(y ~ x, data = data, threshold = "equidistant")

Prior Specification

Default Priors

clmstan uses weakly informative default priors:

For link parameters estimated via Bayesian inference:

Custom Priors

Use the prior() function with distribution helpers:

# Tighter prior on regression coefficients
fit <- clm_stan(y ~ x, data = data,
                prior = prior(normal(0, 1), class = "b"))

# Multiple priors
fit <- clm_stan(y ~ x, data = data,
                prior = c(
                  prior(normal(0, 1), class = "b"),
                  prior(normal(0, 5), class = "Intercept")
                ))

Prior for Link Parameters

When estimating link parameters, you can specify custom priors:

# Custom prior for t-link df parameter
fit <- clm_stan(y ~ x, data = data, link = "tlink",
                link_param = list(df = "estimate"),
                prior = prior(gamma(3, 0.2), class = "df"))

# Custom prior for GEV xi parameter
fit <- clm_stan(y ~ x, data = data, link = "gev",
                link_param = list(xi = "estimate"),
                prior = prior(normal(0, 0.5), class = "xi"))

Available Distribution Functions

Note: flat() creates an improper uniform prior. Use with caution as it may lead to improper posteriors if the data does not provide sufficient information. For thresholds with ordered constraints, Stan's internal transformation provides implicit regularization.

Prior Classes

License

MIT