clmstan: Cumulative Link Models with CmdStanR

Description

Fit cumulative link models (CLMs) for ordinal categorical data using CmdStanR. The package supports various link functions including standard links (logit, probit, cloglog, loglog, cauchit) and flexible parametric links (GEV, AEP, Symmetric Power, Aranda-Ordaz, log-gamma).

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

Main functions

• clm_stan() - Fit a cumulative link model

• supported_links() - List available link functions

Methods

• print.clmstan() - Print summary

• summary.clmstan() - Detailed summary

• coef.clmstan() - Extract coefficients

• predict.clmstan() - Predict categories or probabilities

• plot.clmstan() - Diagnostic plots

• loo.clmstan() - Leave-one-out cross-validation

Author(s)

Maintainer: Tomotaka Momozaki momozaki.stat@gmail.com

References

Flexible Link Functions:

Aranda-Ordaz, F. J. (1981). On two families of transformations to additivity for binary response data. Biometrika, 68(2), 357-363.

Li, D., Wang, X., & Dey, D. K. (2019). Power link functions in an ordinal regression model with Gaussian process priors. Environmetrics, 30(6), e2564.

Prentice, R. L. (1976). A generalization of the probit and logit methods for dose response curves. Biometrics, 32(4), 761-768.

Wang, X. & Dey, D. K. (2011). Generalized extreme value regression for ordinal response data. Environmental and Ecological Statistics, 18(4), 619-634.

Naranjo, L., Pérez, C. J., & Martín, J. (2015). Bayesian analysis of some models that use the asymmetric exponential power distribution. Statistics and Computing, 25(3), 497-514.

See Also

Useful links:

• instantiate package

• cmdstanr

Asymmetric Exponential Power (AEP) link CDF

Description

The AEP distribution with alpha = 0.5 (fixed for identifiability).

Usage

aep_cdf(x, theta1, theta2)

Arguments

Details

For x <= 0: F(x) = 0.5 * (1 - P(1/theta1, u1)) where u1 = (|x| * 2 * Gamma(1 + 1/theta1))^theta1

For x > 0: F(x) = 0.5 + 0.5 * P(1/theta2, u2) where u2 = (x * 2 * Gamma(1 + 1/theta2))^theta2

P(a, x) is the regularized incomplete gamma function (pgamma).

Special case: theta1 = theta2 gives a symmetric distribution. Note: theta = 2 has a Gaussian kernel but is NOT equal to probit due to scaling.

Reference: Naranjo et al. (2015) Statistics and Computing

Value

CDF values

Apply custom prior specifications for link parameters

Description

Apply custom prior specifications for link parameters

Usage

apply_custom_link_priors(result, link_prior)

Arguments

Value

Updated result list with custom priors

Apply user priors to Stan data

Description

Merges user-specified priors with default values and updates the Stan data list.

Usage

apply_priors_to_stan_data(stan_data, prior, threshold, full = FALSE)

Arguments

Value

Updated stan_data list with prior values

Aranda-Ordaz asymmetric link CDF

Description

F(x; lambda) = 1 - (1 + exp(x))^(-lambda)

Usage

aranda_ordaz_cdf(x, lambda)

Arguments

Details

Special cases:

• lambda = 1: logit

• lambda -> 0: cloglog

Reference: Aranda-Ordaz (1981) Biometrika

Value

CDF values

Combine Multiple Prior Specifications

Description

Combines multiple prior() objects into a single prior specification list.

Usage

## S3 method for class 'clm_prior_spec'
c(...)

Arguments

Value

An object of class "clm_prior_list" containing all prior specifications.

Examples

# Combine multiple priors
priors <- c(
  prior(normal(0, 2.5), class = "b"),
  prior(normal(0, 10), class = "Intercept"),
  prior(gamma(2, 0.1), class = "df")
)
print(priors)

Cauchy Distribution for Prior Specification

Description

Creates a Cauchy distribution object for use with prior().

Usage

cauchy(mu = 0, sigma = 1)

Arguments

Value

An object of class "clm_dist" representing a Cauchy distribution.

See Also

prior(), normal(), gamma(), student_t()

Examples

# Create a Cauchy prior (weakly informative)
cauchy(0, 2.5)

# Use with prior()
prior(cauchy(0, 2.5), class = "b")

Unified CDF dispatcher for clmstan

Description

Computes the cumulative distribution function (CDF) for any supported link function. This is the R equivalent of unified_F() in Stan.

Usage

clm_cdf(x, link, link_param = list())

Arguments

Value

CDF values F(x)

Prior Specification for clmstan

Description

Create prior specifications for cumulative link models in clmstan.

Default priors:

• Regression coefficients (beta): normal(0, 2.5)

• Cutpoints (c): normal(0, 10) for flexible, normal(0, 5) for symmetric

• Interval (d): gamma(2, 0.5) for equidistant threshold

Link parameter priors (when estimated):

Usage

clm_prior(
  beta_sd = NULL,
  c_sd = NULL,
  c1_mu = NULL,
  c1_sd = NULL,
  d_alpha = NULL,
  d_beta = NULL,
  cpos_sd = NULL,
  df_alpha = NULL,
  df_beta = NULL,
  lambda_ao_alpha = NULL,
  lambda_ao_beta = NULL,
  lambda_lg_mu = NULL,
  lambda_lg_sd = NULL,
  xi_mu = NULL,
  xi_sd = NULL,
  r_alpha = NULL,
  r_beta = NULL,
  theta1_alpha = NULL,
  theta1_beta = NULL,
  theta2_alpha = NULL,
  theta2_beta = NULL
)

Arguments

Value

An object of class "clm_prior" containing prior specifications.

Examples

# Create a prior object (does not require Stan)
my_prior <- clm_prior(beta_sd = 2, c_sd = 5)
print(my_prior)

## Not run: 
# Examples below require CmdStan and compiled Stan models
data(wine, package = "ordinal")

# Default priors (no customization needed)
fit <- clm_stan(rating ~ temp, data = wine,
                chains = 2, iter = 500, warmup = 250, refresh = 0)

# Custom prior for regression coefficients
fit2 <- clm_stan(rating ~ temp, data = wine,
                 prior = clm_prior(beta_sd = 1),
                 chains = 2, iter = 500, warmup = 250, refresh = 0)

## End(Not run)

Fit a Cumulative Link Model using CmdStanR

Description

Fit a Cumulative Link Model using CmdStanR

Usage

clm_stan(
  formula,
  data,
  link = "logit",
  base = "logit",
  threshold = "flexible",
  link_param = NULL,
  prior = NULL,
  chains = 4,
  iter = 2000,
  warmup = NULL,
  ...
)

Arguments

Value

An object of class "clmstan"

Examples

## Not run: 
# Fit a proportional odds model
library(ordinal)
data(wine)
fit <- clm_stan(rating ~ temp + contact, data = wine, link = "logit")
print(fit)

# Fit with t-link (fixed df)
fit_t <- clm_stan(rating ~ temp, data = wine, link = "tlink",
                  link_param = list(df = 8))

# Fit with GEV link (estimate xi)
fit_gev <- clm_stan(rating ~ temp, data = wine, link = "gev",
                    link_param = list(xi = "estimate"))

## End(Not run)

clmstan S3 Class

Description

The clmstan class represents a fitted cumulative link model. It contains the CmdStanR fit object and additional metadata.

Slots

fit

The CmdStanMCMC object from cmdstanr

formula

The model formula

data

The original data frame

link

The link function used

base

The base distribution (for SP link)

threshold

The threshold structure

link_param

Link parameter settings (for flexible links)

full

TRUE if link parameters were estimated (Bayesian inference), FALSE if they were fixed at user-specified values

K

Number of response categories (cached from data)

N

Number of observations (extracted from data for efficiency)

P

Number of predictors (extracted from design matrix)

Complementary log-log CDF

Description

F(x) = 1 - exp(-exp(x))

Usage

cloglog_cdf(x)

Arguments

Details

This corresponds to the Gumbel (maximum) distribution.

Value

CDF values

Extract coefficients from clmstan objects

Description

Returns posterior point estimates (mean or median) for all model parameters.

Usage

## S3 method for class 'clmstan'
coef(object, type = c("mean", "median"), ...)

Arguments

Value

A named numeric vector with:

• Threshold coefficients (e.g., "1|2", "2|3", ...)

• Regression coefficients (variable names from formula)

Examples

## Not run: 
fit <- clm_stan(rating ~ temp, data = wine)
coef(fit)
coef(fit, type = "median")

## End(Not run)

Compute category probabilities for all draws

Description

Compute category probabilities for all draws

Usage

compute_probs_all(draws, X, link, base_link_param, K, full = FALSE)

Arguments

Value

Array of S x N x K probabilities

Compute category probabilities for a single draw

Description

Compute category probabilities for a single draw

Usage

compute_probs_single(c_vec, eta_vec, link, link_param, K)

Arguments

Value

Matrix of N x K probabilities

Compute relative effective sample size for log-likelihood

Description

Compute relative effective sample size for log-likelihood

Usage

compute_r_eff(object, log_lik, cores = 1)

Arguments

Value

A vector of relative effective sample sizes (length N)

Convert Prior Specification to Internal Format

Description

Internal function to convert distribution-based prior specifications to the internal format used by apply_priors_to_stan_data().

Usage

convert_prior_spec_to_legacy(prior)

Arguments

Value

A list with clm_prior class containing prior parameter values

MCMC Diagnostics for clmstan objects

Description

Provides a summary of MCMC convergence diagnostics including HMC-specific diagnostics (divergences, treedepth, E-BFMI) and general convergence measures (Rhat, ESS).

Usage

diagnostics(object, ...)

## S3 method for class 'clmstan'
diagnostics(
  object,
  detail = FALSE,
  rhat_threshold = 1.01,
  ess_threshold = 400,
  ...
)

Arguments

Details

The function checks for the following issues:

• Divergences: Number of divergent transitions (ideally 0)

• Treedepth: Transitions hitting max treedepth (efficiency issue)

• E-BFMI: Energy Bayesian Fraction of Missing Information (values < 0.3 indicate problems)

• Rhat: Potential scale reduction factor (values > 1.01 indicate lack of convergence)

• ESS: Effective sample size for bulk and tail (low values indicate high autocorrelation)

Value

Invisibly returns a list containing:

• hmc: HMC diagnostics from CmdStanMCMC$diagnostic_summary()

• convergence: Data frame of per-parameter Rhat and ESS values

• issues: Logical indicating whether any issues were detected

Examples

## Not run: 
fit <- clm_stan(rating ~ temp, data = wine)
diagnostics(fit)
diagnostics(fit, detail = TRUE)

## End(Not run)

Extract ACF values from clmstan object

Description

Computes autocorrelation function (ACF) values for MCMC chains and returns them in a tidy data frame format.

Usage

extract_acf(object, pars = NULL, lags = 20, ...)

Arguments

Details

The ACF measures how correlated each draw is with previous draws in the same chain. High autocorrelation at many lags indicates slow mixing and the need for more samples or reparameterization.

Ideally, ACF should drop to near zero within a few lags. Persistent high autocorrelation suggests the sampler is exploring the posterior slowly.

Value

A data frame with columns:

• parameter: Parameter name

• chain: Chain number

• lag: Lag value (0, 1, 2, ...)

• acf: Autocorrelation value

Examples

## Not run: 
fit <- clm_stan(rating ~ temp, data = wine)
acf_df <- extract_acf(fit)
head(acf_df)

# Plot ACF for specific parameters
library(ggplot2)
acf_df |>
  dplyr::filter(parameter == "beta[1]") |>
  ggplot(aes(x = lag, y = acf, color = factor(chain))) +
  geom_line() +
  geom_hline(yintercept = 0, linetype = "dashed")

## End(Not run)

Extract link parameter draws for full model

Description

Extract link parameter draws for full model

Usage

extract_link_param_draws(object)

Arguments

Value

List of link parameter vectors

Extract posterior summary for link parameters

Description

Extract posterior summary for link parameters

Usage

extract_link_params_summary(object, probs = c(0.025, 0.5, 0.975))

Arguments

Value

A data frame with posterior summaries, or NULL if no estimated params

Extract log-likelihood matrix from clmstan object

Description

Extract log-likelihood matrix from clmstan object

Usage

extract_log_lik(object)

Arguments

Value

An S x N matrix of log-likelihood values, where S is the number of posterior samples and N is the number of observations.

Extract posterior summary for specified parameters

Description

Extract posterior summary for specified parameters

Usage

extract_posterior_summary(fit, pars, probs = c(0.025, 0.5, 0.975))

Arguments

Value

A data frame with posterior summaries

Extract posterior draws needed for prediction

Description

Extract posterior draws needed for prediction

Usage

extract_prediction_draws(object, ndraws = NULL)

Arguments

Value

List with c (cutpoints), beta (coefficients), link_params (if full model)

Extract y_rep from Stan fit

Description

Extract y_rep from Stan fit

Usage

extract_y_rep(object, ndraws = NULL)

Arguments

Value

S x N integer matrix

Fitted values for clmstan objects

Description

Returns expected category probabilities for each observation. This is equivalent to predict(object, type = "probs", summary = TRUE).

Usage

## S3 method for class 'clmstan'
fitted(
  object,
  newdata = NULL,
  summary = TRUE,
  robust = FALSE,
  probs = c(0.025, 0.975),
  ndraws = NULL,
  ...
)

Arguments

Value

If summary = TRUE (default): A data frame with N rows and columns for each category probability (P[Y=1], P[Y=2], etc.). If summary = FALSE: An S x N x K array of probability draws.

See Also

predict.clmstan(), posterior_predict.clmstan()

Flat (Improper Uniform) Prior Distribution

Description

Creates a flat (improper uniform) distribution object for use with prior(). A flat prior assigns equal probability density to all values, which is improper (does not integrate to 1) but can be used when the likelihood provides sufficient information for identification.

Usage

flat()

Value

An object of class "clm_dist" representing a flat distribution.

Note

Flat priors are supported for:

• Regression coefficients (class "b")

• Threshold classes ("Intercept", "c1", "cpos")

Using flat priors may lead to improper posteriors if the likelihood does not provide sufficient information. For thresholds with ordered constraints, Stan's internal transformation provides implicit regularization.

See Also

prior(), normal(), student_t(), cauchy()

Examples

# Create a flat prior for regression coefficients
prior(flat(), class = "b")

# Flat prior for thresholds (flexible)
prior(flat(), class = "Intercept")

Format a distribution object as a string

Description

Format a distribution object as a string

Usage

format_dist(x)

Arguments

Value

A character string representation

Gamma Distribution for Prior Specification

Description

Creates a gamma distribution object for use with prior().

Usage

gamma(alpha, beta)

Arguments

Value

An object of class "clm_dist" representing a gamma distribution.

Note

This function masks base::gamma(). To use the base gamma function, use base::gamma() explicitly.

See Also

prior(), normal(), student_t(), cauchy()

Examples

# Create a gamma prior
gamma(2, 0.1)

# Use with prior() for degrees of freedom
prior(gamma(2, 0.1), class = "df")

Get base (fixed) link parameters from object

Description

Get base (fixed) link parameters from object

Usage

get_base_link_params(object)

Arguments

Value

List of fixed link parameters

Get draws for plotting with bayesplot

Description

Returns draws for default parameters (excluding log_lik, y_rep, eta, raw c).

Usage

get_clmstan_draws(object, pars = NULL)

Arguments

Value

A draws_array suitable for bayesplot

Get coefficient names from design matrix

Description

Get coefficient names from design matrix

Usage

get_coef_names(object)

Arguments

Value

A character vector of coefficient names

Get default prior for a link parameter

Description

Get default prior for a link parameter

Usage

get_default_link_prior(link, param)

Arguments

Value

A list with prior specification (family, args)

Get default priors for a threshold structure

Description

Get default priors for a threshold structure

Usage

get_default_priors(threshold = "flexible")

Arguments

Value

A list with default prior values

Get default priors for threshold parameters

Description

Get default priors for threshold parameters

Usage

get_default_threshold_prior(threshold)

Arguments

Details

Default priors:

• flexible: c ~ normal(0, prior_c_sd)

• equidistant: c1 ~ normal(0, 10), d ~ gamma(2, 0.5)

• symmetric: c_pos ~ normal(0, 5) (truncated to positive)

Value

A list with default prior specifications

Get link parameters for a specific draw

Description

Get link parameters for a specific draw

Usage

get_link_param_for_draw(link_param_draws, s, base_param)

Arguments

Value

Link parameters for draw s

Get required parameters for a link function

Description

Get required parameters for a link function

Usage

get_link_params(link)

Arguments

Value

A character vector of required parameter names

Get link type number for Stan

Description

Converts a link function name to the integer code used in Stan.

Usage

get_link_type(link)

Arguments

Details

Link type mapping:

• 1: logit

• 2: probit

• 3: cloglog

• 4: loglog

• 5: cauchit

• 6: tlink

• 7: aranda_ordaz

• 8: sp

• 9: log_gamma

• 10: gev

• 11: aep

Value

An integer (1-11) representing the link type

Get Stan model name based on threshold and full model flag

Description

Get Stan model name based on threshold and full model flag

Usage

get_model_name(threshold, full = FALSE)

Arguments

Value

A character string with the Stan model name

Get base type number for SP link

Description

Converts a base distribution name to the integer code used in Stan for SP link.

Usage

get_sp_base_type(base)

Arguments

Details

Base type mapping (symmetric distributions only, per Li et al. 2019):

• 1: logit

• 2: probit

• 3: cauchit

• 4: tlink

Value

An integer (1-6) representing the base type

Generate threshold names in ordinal::clm style

Description

Creates threshold names like "1|2", "2|3", etc. based on factor levels.

Usage

get_threshold_names(object)

Arguments

Value

A character vector of threshold names

Get threshold parameter information

Description

Get threshold parameter information

Usage

get_threshold_params(threshold)

Arguments

Details

Threshold parameters:

• flexible: c (ordered[K-1])

• equidistant: c1 (real), d (real<lower=0>)

• symmetric: c_pos (positive_ordered[(K-1)/2])

Value

A list with parameter names and their Stan types

Generalized Extreme Value (GEV) link CDF

Description

F(x; xi) = exp(-(1 + xi * x)^(-1/xi))

Usage

gev_cdf(x, xi)

Arguments

Details

Special cases:

• xi = 0: Gumbel (equals loglog)

• xi < 0: Weibull (bounded above)

• xi > 0: Frechet (heavy tail)

Reference: Wang & Dey (2011)

Value

CDF values

Check if object is clmstan

Description

Check if object is clmstan

Usage

is.clmstan(x)

Arguments

Value

TRUE if x is a clmstan object

Check if a link function requires parameters

Description

Check if a link function requires parameters

Usage

is_flexible_link(link)

Arguments

Value

TRUE if the link requires additional parameters

Available Link Functions

Description

clmstan supports the following link functions for cumulative link models:

Standard links (no additional parameters):

• "logit" - Logistic (proportional odds model)

• "probit" - Normal (latent variable interpretation)

• "cloglog" - Complementary log-log (proportional hazards)

• "loglog" - Log-log (Gumbel minimum)

• "cauchit" - Cauchy (heavy tails)

Flexible links (with additional parameters):

• "tlink" - Student-t (df > 0)

  • df = Inf: equals probit

  • df < 3: increasingly heavy tails; df > 30 is nearly normal

• "aranda_ordaz" - Aranda-Ordaz asymmetric (lambda > 0)

  • lambda = 1: equals logit

  • lambda -> 0: approaches cloglog

• "gev" - Generalized extreme value (shape parameter xi)

  • xi = 0: Gumbel (equals loglog)

  • xi < 0: Weibull (short tail)

  • xi > 0: Frechet (heavy tail)

• "sp" - Symmetric power (r > 0, base distribution)

  • r = 1: equals base distribution

  • 0 < r < 1: positively skewed

  • r > 1: negatively skewed

• "log_gamma" - Log-gamma (lambda)

  • lambda = 0: equals probit

  • lambda > 0 or < 0: asymmetric

• "aep" - Asymmetric exponential power (theta1 > 0, theta2 > 0)

  • alpha = 0.5 fixed for identifiability

  • theta1 = theta2: symmetric distribution

  • theta = 2: Gaussian kernel (but NOT equal to probit due to scaling)

  • theta < 2: heavy tails (leptokurtic)

  • theta > 2: light tails (platykurtic)

Link Parameter Specification

Flexible link parameters can be either fixed or estimated (inferred).

Fixed parameters: Specify a numeric value

clm_stan(y ~ x, link = "tlink", link_param = list(df = 8))
clm_stan(y ~ x, link = "gev", link_param = list(xi = 0))  # equals loglog
clm_stan(y ~ x, link = "aep", link_param = list(theta1 = 2, theta2 = 2))  # symmetric

Estimated parameters: Use "estimate" (with default prior)

clm_stan(y ~ x, link = "tlink", link_param = list(df = "estimate"))
clm_stan(y ~ x, link = "gev", link_param = list(xi = "estimate"))

Custom priors: Combine "estimate" with prior argument

clm_stan(y ~ x, link = "gev",
         link_param = list(xi = "estimate"),
         prior = prior(normal(0, 0.3), class = "xi"))

Default Priors for Link Parameters

When using "estimate", the following default priors are used:

SP Link Details (Li et al., 2019)

The Symmetric Power link uses a symmetric base distribution F_0, specified via the base argument. Supported bases:

• base = "logit": Logistic base (default)

• base = "probit": Normal base

• base = "cauchit": Cauchy base

• base = "tlink": Student-t base (requires df)

Note: Li et al. (2019) define F_0 as a CDF "whose corresponding PDF is symmetric about 0".

Log-gamma link CDF

Description

Based on the log-gamma distribution:

• lambda = 0: probit (normal)

• lambda > 0: F(x) = pgamma(exp(x), shape = lambda, rate = lambda)

• lambda < 0: F(x) = 1 - pgamma(exp(-x), shape = -lambda, rate = -lambda)

Usage

loggamma_cdf(x, lambda)

Arguments

Details

Reference: Prentice (1976) Biometrics

Value

CDF values

Log-log CDF

Description

F(x) = exp(-exp(-x))

Usage

loglog_cdf(x)

Arguments

Details

This corresponds to the Gumbel (minimum) distribution. It is the reflection of cloglog: loglog(x) = 1 - cloglog(-x)

Value

CDF values

Leave-One-Out Cross-Validation for clmstan objects

Description

Computes approximate leave-one-out cross-validation (LOO-CV) for a fitted cumulative link model using Pareto smoothed importance sampling (PSIS).

Usage

## S3 method for class 'clmstan'
loo(x, ..., r_eff = NULL, cores = getOption("mc.cores", 1), save_psis = FALSE)

Arguments

Details

The function extracts the log-likelihood matrix (log_lik) computed in the generated quantities block of the Stan model and passes it to loo.

Pareto k diagnostics: Observations with high Pareto k values (k > 0.7) indicate potential problems with the LOO approximation for those observations. Use plot() on the returned object to visualize the Pareto k values.

Model comparison: Use loo_compare to compare multiple models. Models with higher elpd_loo are preferred.

Value

An object of class c("psis_loo", "loo") containing:

• estimates: A matrix with columns Estimate and SE for elpd_loo, p_loo, and looic.

• pointwise: A matrix with pointwise contributions.

• diagnostics: A list with Pareto k values and effective sample sizes for each observation.

See Also

waic.clmstan for WAIC computation, loo for details on the LOO algorithm, loo_compare for model comparison.

Examples

## Not run: 
fit <- clm_stan(rating ~ temp, data = wine)
loo_result <- loo(fit)
print(loo_result)
plot(loo_result)

# Compare two models
fit1 <- clm_stan(rating ~ temp, data = wine, link = "logit")
fit2 <- clm_stan(rating ~ temp, data = wine, link = "probit")
loo::loo_compare(loo(fit1), loo(fit2))

## End(Not run)

Create design matrix

Description

Creates the design matrix for predictors (without intercept column).

Usage

make_design_matrix(formula, data)

Arguments

Value

A design matrix (N x P)

Map Parameter Class and Distribution to Legacy Parameter Names

Description

Map Parameter Class and Distribution to Legacy Parameter Names

Usage

map_class_to_params(class, dist)

Arguments

Value

A named list of legacy parameter values

Check if any link parameter requires estimation

Description

Check if any link parameter requires estimation

Usage

needs_full_model(link_param)

Arguments

Value

TRUE if any parameter is set to "estimate"

Create a clmstan object (internal constructor)

Description

This is an internal constructor called by clm_stan(). Users should not call this function directly.

Usage

new_clmstan(
  fit,
  formula,
  data,
  link,
  base,
  threshold,
  link_param = NULL,
  full = FALSE,
  K,
  N,
  P
)

Arguments

Value

An object of class "clmstan"

Normal Distribution for Prior Specification

Description

Creates a normal distribution object for use with prior().

Usage

normal(mu = 0, sigma = 1)

Arguments

Value

An object of class "clm_dist" representing a normal distribution.

See Also

prior(), gamma(), student_t(), cauchy()

Examples

# Create a normal prior
normal(0, 2.5)

# Use with prior()
prior(normal(0, 2.5), class = "b")

Parse formula for CLM

Description

Parse formula for CLM

Usage

parse_clm_formula(formula, data)

Arguments

Value

A list with response and predictor_formula

Plot method for clmstan objects

Description

Produces diagnostic plots using the bayesplot package.

Usage

## S3 method for class 'clmstan'
plot(
  x,
  type = c("trace", "dens", "hist", "areas", "intervals", "acf"),
  pars = NULL,
  ...
)

Arguments

Value

A ggplot object

Examples

## Not run: 
fit <- clm_stan(rating ~ temp, data = wine)
plot(fit)                    # trace plots
plot(fit, type = "dens")     # density plots
plot(fit, type = "intervals") # credible intervals
plot(fit, type = "acf")      # autocorrelation plots
plot(fit, pars = "beta")     # only beta parameters

## End(Not run)

Posterior predictive distribution for clmstan objects

Description

Draws from the posterior predictive distribution. For each posterior sample, a predicted category is sampled from the categorical distribution with the predicted probabilities.

Usage

posterior_predict.clmstan(object, newdata = NULL, ndraws = NULL, ...)

Arguments

Value

An integer matrix of dimension S x N containing predicted categories (1 to K), where S is the number of posterior draws and N is the number of observations.

See Also

predict.clmstan(), fitted.clmstan()

Predict method for clmstan objects

Description

Generates predictions from a fitted cumulative link model.

Usage

## S3 method for class 'clmstan'
predict(
  object,
  newdata = NULL,
  type = c("class", "probs"),
  summary = TRUE,
  robust = FALSE,
  probs = c(0.025, 0.975),
  ndraws = NULL,
  ...
)

Arguments

Value

Depending on type and summary:

• type = "class", summary = TRUE: A data frame with columns Estimate (mean/median predicted class), Est.Error (SD), quantile columns, and Class (modal predicted category).

• type = "class", summary = FALSE: An S x N integer matrix of predicted categories (1 to K), where S is the number of posterior draws and N is the number of observations.

• type = "probs", summary = TRUE: A data frame with columns for each category probability (P[Y=1], P[Y=2], etc.).

• type = "probs", summary = FALSE: An S x N x K array of predicted probabilities.

See Also

fitted.clmstan() for expected probabilities, posterior_predict.clmstan() for posterior predictive samples.

Prepare link parameters for Stan

Description

Fills in default values for link parameters and validates them.

Usage

prepare_link_params(link, link_param = NULL)

Arguments

Value

A list with all link parameters (df, lambda, xi, r, base_type, theta1, theta2)

Prepare link parameters for full Stan model

Description

Determines which parameters to estimate vs. fix, and sets up priors.

Usage

prepare_link_params_full(link, link_param = NULL, link_prior = NULL)

Arguments

Value

A list with estimation flags, fixed values, and prior hyperparameters

Prepare design matrix for prediction

Description

Prepare design matrix for prediction

Usage

prepare_prediction_matrix(object, newdata)

Arguments

Value

Design matrix (N x P)

Prepare data for Stan model

Description

Prepare data for Stan model

Usage

prepare_stan_data(
  formula,
  data,
  link = "logit",
  link_param = NULL,
  prior_beta_sd = 2.5,
  prior_c_sd = 10
)

Arguments

Value

A list suitable for passing to CmdStan

Dispatch to appropriate data preparation function

Description

Routes to the correct prepare function based on threshold structure and whether link parameters are being estimated.

Usage

prepare_stan_data_dispatch(
  formula,
  data,
  link,
  base,
  link_param,
  threshold,
  full,
  prior
)

Arguments

Value

A list suitable for passing to CmdStan

Prepare data for equidistant threshold Stan model

Description

Creates a Stan data list for cumulative link models with equidistant (equally spaced) thresholds: c_k = c_1 + (k-1) * d

Usage

prepare_stan_data_equidistant(
  formula,
  data,
  link = "logit",
  link_param = NULL,
  prior_beta_sd = 2.5,
  prior_c1_mu = 0,
  prior_c1_sd = 10,
  prior_d_alpha = 2,
  prior_d_beta = 0.5
)

Arguments

Value

A list suitable for passing to CmdStan (clm_equidistant.stan)

Prepare data for full Stan model with link parameter inference

Description

Prepare data for full Stan model with link parameter inference

Usage

prepare_stan_data_full(
  formula,
  data,
  link = "logit",
  link_param = NULL,
  prior_beta_sd = 2.5,
  prior_c_sd = 10,
  link_prior = NULL
)

Arguments

Value

A list suitable for passing to CmdStan (clm_full.stan)

Prepare data for symmetric threshold Stan model

Description

Creates a Stan data list for cumulative link models with symmetric thresholds centered at 0: c[k] = -c[K-k]

Usage

prepare_stan_data_symmetric(
  formula,
  data,
  link = "logit",
  link_param = NULL,
  prior_beta_sd = 2.5,
  prior_cpos_sd = 5
)

Arguments

Details

Examples:

• K=4 (3 thresholds): c = (-a, 0, a)

• K=5 (4 thresholds): c = (-b, -a, a, b)

• K=6 (5 thresholds): c = (-b, -a, 0, a, b)

Value

A list suitable for passing to CmdStan (clm_symmetric.stan)

Print method for clm_dist objects

Description

Print method for clm_dist objects

Usage

## S3 method for class 'clm_dist'
print(x, ...)

Arguments

Value

Invisibly returns the input clm_dist object.

Print method for clm_prior objects

Description

Print method for clm_prior objects

Usage

## S3 method for class 'clm_prior'
print(x, ...)

Arguments

Value

Invisibly returns the input clm_prior object.

Print method for clm_prior_list objects

Description

Print method for clm_prior_list objects

Usage

## S3 method for class 'clm_prior_list'
print(x, ...)

Arguments

Value

Invisibly returns the input clm_prior_list object.

Print method for clm_prior_spec objects

Description

Print method for clm_prior_spec objects

Usage

## S3 method for class 'clm_prior_spec'
print(x, ...)

Arguments

Value

Invisibly returns the input clm_prior_spec object.

Print method for clmstan objects

Description

Print method for clmstan objects

Usage

## S3 method for class 'clmstan'
print(x, ...)

Arguments

Value

Invisibly returns x

Print method for summary.clmstan objects

Description

Print method for summary.clmstan objects

Usage

## S3 method for class 'summary.clmstan'
print(x, ...)

Arguments

Value

Invisibly returns x

Specify Prior Distributions

Description

Specify prior distributions for model parameters using distribution functions.

Usage

prior(prior, class = "b", coef = "")

Arguments

Value

An object of class "clm_prior_spec" representing the prior specification.

See Also

normal(), gamma(), student_t(), cauchy(), clm_prior()

Examples

# Specify a normal prior for regression coefficients
prior(normal(0, 2.5), class = "b")

# Specify a gamma prior for degrees of freedom
prior(gamma(2, 0.1), class = "df")

# Combine multiple priors
c(
  prior(normal(0, 2.5), class = "b"),
  prior(normal(0, 10), class = "Intercept")
)

Symmetric Power (SP) link CDF

Description

The SP link applies a power transformation to a base CDF:

Usage

sp_cdf(x, r, base, df = 8)

Arguments

Details

For r <= 1: F_sp(x) = F_0(x/r)^r For r > 1: F_sp(x) = 1 - F_0(-r*x)^(1/r)

Special case: r = 1 gives the base distribution F_0.

Reference: Li et al. (2019) Environmetrics

Value

CDF values

Student-t Distribution for Prior Specification

Description

Creates a Student-t distribution object for use with prior().

Usage

student_t(df = 3, mu = 0, sigma = 1)

Arguments

Value

An object of class "clm_dist" representing a Student-t distribution.

See Also

prior(), normal(), gamma(), cauchy()

Examples

# Create a Student-t prior with heavy tails
student_t(3, 0, 2.5)

# Use with prior()
prior(student_t(3, 0, 2.5), class = "b")

Summarize class prediction draws

Description

Summarize class prediction draws

Usage

summarize_class_draws(class_draws, robust = FALSE, probs = c(0.025, 0.975))

Arguments

Value

Data frame with summary statistics

Summarize probability draws

Description

Summarize probability draws

Usage

summarize_probs_draws(probs_array, robust = FALSE)

Arguments

Value

Data frame with mean probabilities per category

Summary method for clmstan objects

Description

Summary method for clmstan objects

Usage

## S3 method for class 'clmstan'
summary(object, probs = c(0.025, 0.5, 0.975), digits = 3, ...)

Arguments

Value

An object of class "summary.clmstan" containing:

• coefficients: Posterior summary for regression coefficients

• thresholds: Posterior summary for threshold parameters

• beta0: Posterior summary for intercept

• link_params: Posterior summary for link parameters (full model only)

• model_info: Model metadata (formula, link, threshold, K, N, P)

Get supported link functions

Description

Get supported link functions

Usage

supported_links(type = c("all", "standard", "flexible"))

Arguments

Value

A character vector of supported link function names

Examples

supported_links()
supported_links("standard")
supported_links("flexible")

Get supported threshold structures

Description

Get supported threshold structures

Usage

supported_thresholds()

Value

A character vector of supported threshold structure names

Examples

supported_thresholds()

Validate full model parameters

Description

Checks that estimation flags make sense for the specified link.

Usage

validate_full_params(link, params)

Arguments

Check if a link function is valid

Description

Check if a link function is valid

Usage

validate_link(link)

Arguments

Value

TRUE if valid, otherwise throws an error

Validate link parameters

Description

Validate link parameters

Usage

validate_link_params(link, params)

Arguments

Validate prediction inputs

Description

Validate prediction inputs

Usage

validate_prediction_input(object, newdata, ndraws)

Arguments

Validate prior specification for a model

Description

Checks that the prior specification is compatible with the model settings.

Usage

validate_prior(prior, threshold, link, link_param)

Arguments

Value

TRUE if valid, otherwise throws a warning

Validate that the distribution is compatible with the parameter class

Description

Validate that the distribution is compatible with the parameter class

Usage

validate_prior_class_dist(class, dist)

Arguments

Validate prior values

Description

Validate prior values

Usage

validate_prior_values(prior)

Arguments

Validate threshold specification

Description

Validate threshold specification

Usage

validate_threshold(threshold, K = NULL)

Arguments

Details

Validation rules:

• flexible: No restrictions

• equidistant: K = 2 triggers a warning (d is not identifiable)

• symmetric: Requires K >= 3

Value

TRUE if valid, otherwise throws an error

Widely Applicable Information Criterion for clmstan objects

Description

Computes the Widely Applicable Information Criterion (WAIC) for a fitted cumulative link model.

Usage

## S3 method for class 'clmstan'
waic(x, ...)

Arguments

Details

WAIC is an alternative to LOO-CV that is asymptotically equivalent to leave-one-out cross-validation. However, LOO-CV with PSIS is generally preferred because:

• It provides useful diagnostics (Pareto k values)

• It is more robust in finite samples

• It has been shown to be more reliable in practice

For most purposes, loo.clmstan is recommended over WAIC.

Value

An object of class c("waic", "loo") containing:

• estimates: A matrix with columns Estimate and SE for elpd_waic, p_waic, and waic.

• pointwise: A matrix with pointwise contributions.

See Also

loo.clmstan for LOO-CV (recommended), waic for details on WAIC computation, loo_compare for model comparison.

Examples

## Not run: 
fit <- clm_stan(rating ~ temp, data = wine)
waic_result <- waic(fit)
print(waic_result)

## End(Not run)