% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lsirmgrm_mcar.R
\name{lsirmgrm_mcar}
\alias{lsirmgrm_mcar}
\title{1PL GRM LSIRM for missing completely at random data.}
\usage{
lsirmgrm_mcar(
  data,
  ncat = NULL,
  missing.val = 99,
  chains = 1,
  multicore = 1,
  seed = NA,
  ndim = 2,
  niter = 15000,
  nburn = 2500,
  nthin = 5,
  nprint = 500,
  jump_beta = 0.4,
  jump_theta = 1,
  jump_gamma = 0.2,
  jump_z = 0.5,
  jump_w = 0.5,
  pr_mean_beta = 0,
  pr_sd_beta = 1,
  pr_mean_theta = 0,
  pr_sd_theta = 1,
  pr_mean_gamma = 0.5,
  pr_sd_gamma = 1,
  pr_a_theta = 0.001,
  pr_b_theta = 0.001,
  adapt = NULL,
  verbose = FALSE,
  fix_theta_sd = FALSE
)
}
\arguments{
\item{data}{Matrix; an ordinal (ordered categorical) item response matrix. Each row represents a respondent, and
each column represents an item. Values can be either \code{0:(K-1)} or \code{1:K}. Missing values can be \code{NA}.}

\item{ncat}{Integer; number of categories \eqn{K}. If \code{NULL}, it is inferred from the observed data.}

\item{missing.val}{Numeric; numeric code used to represent missing values in the C++ sampler. Default is 99.}

\item{chains}{Integer; number of MCMC chains. Default is 1.}

\item{multicore}{Integer; number of cores for parallel execution when \code{chains > 1}. Default is 1.}

\item{seed}{Integer; RNG seed. Default is \code{NA}.}

\item{ndim}{Integer; latent space dimension. Default is 2.}

\item{niter}{Integer; total MCMC iterations. Default is 15000.}

\item{nburn}{Integer; burn-in iterations. Default is 2500.}

\item{nthin}{Integer; thinning interval. Default is 5.}

\item{nprint}{Integer; print interval if \code{verbose=TRUE}. Default is 500.}

\item{jump_beta}{Numeric; proposal SD for GRM thresholds. Default is 0.4. During MCMC sampling, threshold proposals are constrained to maintain the ordering \eqn{\beta_{i,1} > \beta_{i,2} > \cdots > \beta_{i,K-1}} for each item.}

\item{jump_theta}{Numeric; proposal SD for theta. Default is 1.}

\item{jump_gamma}{Numeric; proposal SD on log-scale for gamma. Default is 0.2.}

\item{jump_z}{Numeric; proposal SD for z. Default is 0.5.}

\item{jump_w}{Numeric; proposal SD for w. Default is 0.5.}

\item{pr_mean_beta}{Numeric; prior mean for thresholds. Default is 0.}

\item{pr_sd_beta}{Numeric; prior SD for thresholds. Default is 1.}

\item{pr_mean_theta}{Numeric; prior mean for theta. Default is 0.}

\item{pr_sd_theta}{Numeric; prior SD for theta. Default is 1.}

\item{pr_mean_gamma}{Numeric; log-normal prior mean for gamma. Default is 0.5.}

\item{pr_sd_gamma}{Numeric; log-normal prior SD for gamma. Default is 1.}

\item{pr_a_theta}{Numeric; shape for inverse-gamma prior on var(theta). Default is 0.001.}

\item{pr_b_theta}{Numeric; scale for inverse-gamma prior on var(theta). Default is 0.001.}

\item{adapt}{List; optional adaptive MCMC control. If not \code{NULL}, proposal standard deviations are adapted during burn-in using a Robbins-Monro update on the log proposal SD and are held fixed during the main MCMC sampling.
When adaptation is enabled, the reported acceptance ratios in the output (\code{accept_beta}, \code{accept_theta}, etc.) are computed only from iterations after burn-in, reflecting the performance of the adapted proposal distributions.
The defaults are tuning heuristics for random-walk Metropolis proposals: scalar parameters use a target acceptance rate of \code{0.44}, while latent position block proposals use \code{0.234}. The \code{0.44} target is commonly used for one-dimensional random-walk proposals, and \code{0.234} is the high-dimensional optimal-scaling benchmark discussed by Roberts, Gelman and Gilks (1997) and Roberts and Rosenthal (2001). These values are proposal-tuning targets, not convergence diagnostics.
Elements of the list can include:
\itemize{
  \item \code{use_adapt}: Logical; if \code{TRUE}, adaptive MCMC is used. Default is \code{FALSE}.
  \item \code{adapt_interval}: Integer; the number of iterations between proposal SD updates. Smaller values react more quickly but can be noisy; larger values are smoother but adapt more slowly. Default is \code{100}.
  \item \code{adapt_rate}: Numeric; Robbins-Monro scaling constant \eqn{c} in the step-size formula \eqn{c / t^\alpha}. Larger values adapt faster but can oscillate; smaller values are more conservative. Default is \code{1.0}. Recommended starting range is \code{0.5}--\code{2.0}.
  \item \code{decay_rate}: Numeric; Robbins-Monro decay exponent \eqn{\alpha} in \eqn{c / t^\alpha}. Values above \code{0.5} give diminishing adaptation consistent with the usual stochastic-approximation square-summability condition. Default is \code{0.6}; recommended range is \code{0.6}--\code{0.8}.
  \item \code{jump_min}, \code{jump_max}: Numeric; advanced lower and upper bounds for adapted proposal SDs, used to prevent proposal scales from collapsing to zero or becoming excessively large. These are normally left unchanged.
  \item \code{target_accept}: Numeric; default target acceptance rate for scalar random-walk updates (beta, theta, gamma). Default is \code{0.44}.
  \item \code{target_accept_zw}: Numeric; target acceptance rate for latent position block updates z and w. Default is \code{0.234}.
  \item \code{target_accept_beta/theta/gamma}: Numeric; (optional) parameter-specific target acceptance rates to override \code{target_accept}.
}}

\item{verbose}{Logical; If TRUE, MCMC samples are printed for each \code{nprint}. Default is FALSE.}

\item{fix_theta_sd}{Logical; If TRUE, the standard deviation of the respondent latent positions \eqn{\theta} is fixed at 1 instead of being sampled. Default is FALSE.}
}
\description{
\link{lsirmgrm_mcar} is used to fit 1PL GRM LSIRM in incomplete data assumed to be missing completely at random.
}
\examples{
\donttest{
# generate example ordinal item response matrix
set.seed(123)
nsample <- 50
nitem <- 10
data <- matrix(sample(1:5, nsample * nitem, replace = TRUE), nrow = nsample)

# generate missing value (MCAR)
data[sample(1:500, 50)] <- NA

# Fit 1PL GRM LSIRM with MCAR
fit <- lsirmgrm_mcar(data, niter = 1000, nburn = 500)
summary(fit)
}

}
