% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bayesqm-package.R
\docType{package}
\name{bayesqm-package}
\alias{bayesqm}
\alias{bayesqm-package}
\title{bayesqm: Bayesian Q Methodology: Exact Rank-Order Likelihood for Forced Q Sorts}
\description{
\if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}}

A Bayesian analysis for Q methodology, alongside the classical one. Models the forced Q sort as an ordered partition of the statements through an exact rank-order likelihood (the design quotas fix the partition margins, so the likelihood of the observed sorting event is exact), fits it by a parameter-expanded Gibbs sampler in R with no compiled code and a convergence gate on rotation-invariant functionals, resolves rotational ambiguity via the MatchAlign post-processing of Poworoznek et al. (2025) \doi{10.1214/25-BA1544}, and returns the familiar Q tables as posterior summaries: credible intervals for bounded participant loadings, flag probabilities with an explicit unclassified state, quota-respecting factor arrays, distinguishing and consensus statements judged against a posterior critical difference and a grid-width equivalence region, one posterior false-discovery rule for all published claims, and a two-signal posterior-predictive workflow for the number of factors.

A Bayesian analysis for Q methodology, alongside the classical one. The
forced Q sort is modeled as an ordered partition of the statements
through an exact rank-order likelihood: the design quotas fix the
partition margins, so the probability of the observed sorting event is
the full observed-data likelihood. The posterior is sampled by a
parameter-expanded Gibbs sampler in R with no compiled code, gated on rotation-invariant
convergence diagnostics, aligned by MatchAlign, and returned as the
familiar Q tables with uncertainty attached.
}
\details{
The typical workflow:

\enumerate{
\item \strong{Import data.} \code{\link[=read_qsort]{read_qsort()}} auto-detects CSV, Excel,
PQMethod \code{.DAT}, Ken-Q JSON / multi-sheet Excel, KADE ZIP, or
Easy-HTMLQ Firebase JSON. \code{\link[=qsort_data]{qsort_data()}} constructs the object
directly from a matrix. The exact likelihood needs forced sorts:
every participant must match the design grid.
\item \strong{Fit.} \code{\link[=fit_bayesian]{fit_bayesian()}} returns a \code{bayesqm_fit}; \code{\link[=extend]{extend()}}
warm-continues a chain the convergence gate flagged.
\item \strong{Read the tables.} \code{\link[=compute_loadings]{compute_loadings()}} (bounded loadings
with credible intervals), \code{\link[=compute_flags]{compute_flags()}} (flag probabilities
with an unclassified state), \code{\link[=compute_zscores]{compute_zscores()}},
\code{\link[=compute_factor_array]{compute_factor_array()}} (quota-exact arrays),
\code{\link[=compute_qdc]{compute_qdc()}} (distinguishing / consensus / indeterminate),
\code{\link[=crib_sheet]{crib_sheet()}}, and \code{\link[=claims]{claims()}} — one posterior false-discovery
rule selecting every claim.
\item \strong{Check the model.} \code{\link[=check_fit]{check_fit()}} (agreement, extra-factor,
and paired-comparison checks) and \code{\link[=check_persons]{check_persons()}} (the person check,
against mixed-replication bands).
\item \strong{Choose K.} \code{\link[=fit_ladder]{fit_ladder()}} and \code{\link[=select_k]{select_k()}} run the
two-signal workflow; \code{\link[=loo_ladder]{loo_ladder()}} adds directional
corroboration.
\item \strong{Report.} The \verb{plot_*} views, \code{\link[=rotate_factors]{rotate_factors()}} for
judgmental rotation, \code{\link[=rename_factors]{rename_factors()}}, and the standard R
accessors (\code{coef()}, \code{fitted()}, \code{as_draws_df()},
\code{\link[=posterior_interval]{posterior_interval()}}, \code{\link[=prior_summary]{prior_summary()}}).
}
}
\section{Relationship to classical Q analysis}{

The questions and the reporting conventions are Q's own; what the
Bayesian account adds is a probability behind each familiar verdict.
Vocabulary carries over: flags, factor arrays, defining sorts,
distinguishing and consensus statements. Two deliberate differences in
the tables:
\itemize{
\item Factor characteristics do not print eigenvalues or explained
variance, which have no counterpart in a generative model; report
the defining-sort counts from \code{\link[=claims]{claims()}} and the extra-factor check
of \code{\link[=check_fit]{check_fit()}} in their place.
\item Consensus is a positive finding (an equivalence region of one grid
column, \code{\link[=delta_grid]{delta_grid()}}), not the complement of distinguishing, so a
statement can be distinguishing, consensus, or neither.
}
}

\references{
Poworoznek, E., Anceschi, N., Ferrari, F., & Dunson, D. (2025).
Efficiently Resolving Rotational Ambiguity in Bayesian Matrix
Sampling with Matching. \emph{Bayesian Analysis}.

Vehtari, A., Gelman, A., Simpson, D., Carpenter, B., & Bürkner, P.-C.
(2021). Rank-Normalization, Folding, and Localization: An Improved
R-hat for Assessing Convergence of MCMC. \emph{Bayesian Analysis}, 16(2),
667-718.
}
\seealso{
Useful links:
\itemize{
  \item \url{https://github.com/rdazadda/bayesqm}
  \item \url{https://rdazadda.github.io/bayesqm/}
  \item Report bugs at \url{https://github.com/rdazadda/bayesqm/issues}
}

}
\author{
\strong{Maintainer}: Raymond Dacosta Azadda \email{rdazadda@alaska.edu} (\href{https://orcid.org/0009-0002-4384-4556}{ORCID})

Authors:
\itemize{
  \item Raymond Dacosta Azadda \email{rdazadda@alaska.edu} (\href{https://orcid.org/0009-0002-4384-4556}{ORCID})
  \item Henry Ofoe Agbi-Kaiser (\href{https://orcid.org/0009-0008-6127-9136}{ORCID})
  \item Hannah D. Robinson (\href{https://orcid.org/0009-0000-5159-1363}{ORCID})
  \item  AK-ACE Team
  \item Karsten Hueffer
  \item Taa'aii Peter
  \item Stacy Rasmus
}

}
\keyword{internal}
