Skip to contents

Fit a Bayesian Q-methodology factor model

Source: R/estimation.R
fit_bayesian.Rd

Fits the low-rank Bayesian factor model to Q-sort data. Samples the posterior with Stan (via cmdstanr or rstan), resolves rotational ambiguity with MatchAlign, and returns a classed bayesqm_fit object carrying posterior-mean loadings and factor scores, credible intervals, raw draws, LOO, PPC, and diagnostics.

Usage

fit_bayesian(
  Y,
  K,
  stan_dir = NULL,
  robust = TRUE,
  nu = "estimate",
  chains = 4,
  iter = 2000,
  warmup = 1000,
  seed = NULL,
  adapt_delta = 0.9,
  max_draws = 2000,
  prior_loading_scale = 1,
  prior_sigma_scale = 1,
  prior_nu_alpha = 2,
  prior_nu_beta = 0.1,
  use_half_cauchy = FALSE,
  prob = 0.95,
  delta = NULL
)

Arguments

Y

Either a qsort_data object or a J x N numeric matrix with statements as rows and participants as columns.

K

Integer number of factors to extract.

stan_dir

Directory containing stan/factor_model.stan. NULL (the default) uses the copy shipped in inst/stan/.

robust

Logical; TRUE uses a Student-t likelihood, FALSE uses Normal.

nu

Either "estimate" (default) to sample the Student-t degrees of freedom, or a numeric value (e.g. 5, Inf) to fix it.

chains, iter, warmup

NUTS sampler settings.

seed

Optional integer seed for reproducibility.

adapt_delta

NUTS adapt_delta target (default 0.90).

max_draws

Thin post-warmup draws to at most this many before MatchAlign (default 2000).

prior_loading_scale, prior_sigma_scale, prior_nu_alpha, prior_nu_beta, use_half_cauchy

Prior hyperparameters (see the Stan model for parameterization).

prob

Credible-interval probability stored on the fit (default 0.95).

delta

Substantive viewpoint separation for the distinguishing/consensus probabilities. If NULL (default) it is computed as the reliability-adjusted critical difference (critical_delta()); pass a numeric value to override, or use suggest_delta() as an alternative.

Value

A bayesqm_fit object. See bayesqm-fit-methods for print() and summary(), and coef.bayesqm_fit() for the standard R accessors.

References

Poworoznek et al. (2025). Efficiently Resolving Rotational Ambiguity in Bayesian Matrix Sampling with Matching. Bayesian Analysis.

Examples

# \donttest{
# Needs a working Stan backend; skipped when cmdstanr/CmdStan is absent.
has_stan <- requireNamespace("cmdstanr", quietly = TRUE) &&
  !inherits(try(cmdstanr::cmdstan_path(), silent = TRUE), "try-error")
if (has_stan) {
  sim <- generate_data(N = 8, J = 12, K = 2, seed = 1)
  fit <- fit_bayesian(sim$Y, K = 2, chains = 1, iter = 600, warmup = 300)
  summary(fit)
}
# }