% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lsirm2pl_normal_mcar.R
\name{lsirm2pl_normal_mcar}
\alias{lsirm2pl_normal_mcar}
\title{2PL LSIRM with normal likelihood and missing completely at random data.}
\usage{
lsirm2pl_normal_mcar(
  data,
  ndim = 2,
  niter = 15000,
  nburn = 2500,
  nthin = 5,
  nprint = 500,
  jump_beta = 0.4,
  jump_theta = 1,
  jump_alpha = 1,
  jump_gamma = 1,
  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_mean_alpha = 0.5,
  pr_sd_alpha = 1,
  pr_a_theta = 0.001,
  pr_b_theta = 0.001,
  pr_a_eps = 0.001,
  pr_b_eps = 0.001,
  missing.val = 99,
  verbose = FALSE,
  fix_theta_sd = FALSE,
  fix_alpha_1 = TRUE,
  adapt = NULL
)
}
\arguments{
\item{data}{Matrix; a binary or continuous item response matrix for analysis. Each row represents a respondent, and each column contains responses to the corresponding item.}

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

\item{niter}{Integer; the total number of MCMC iterations to run. Default is 15000.}

\item{nburn}{Integer; the number of initial MCMC iterations to discard as burn-in. Default is 2500.}

\item{nthin}{Integer; the number of MCMC iterations to thin. Default is 5.}

\item{nprint}{Integer; the interval at which MCMC samples are displayed during execution. Default is 500.}

\item{jump_beta}{Numeric; the jumping rule for the beta proposal density. Default is 0.4.}

\item{jump_theta}{Numeric; the jumping rule for the theta proposal density. Default is 1.}

\item{jump_alpha}{Numeric; the jumping rule for the alpha proposal density. Default is 1.}

\item{jump_gamma}{Numeric; the jumping rule for the gamma proposal density. Default is 0.2}

\item{jump_z}{Numeric; the jumping rule for the z proposal density. Default is 0.5.}

\item{jump_w}{Numeric; the jumping rule for the w proposal density. Default is 0.5.}

\item{pr_mean_beta}{Numeric; the mean of the normal prior for beta. Default is 0.}

\item{pr_sd_beta}{Numeric; the standard deviation of the normal prior for beta. Default is 1.}

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

\item{pr_sd_theta}{Numeric; the standard deviation of the normal prior for theta. Default is 1.}

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

\item{pr_sd_gamma}{Numeric; standard deviation of log normal prior for gamma. Default is 1.}

\item{pr_mean_alpha}{Numeric; the mean of the log normal prior for alpha. Default is 0.5.}

\item{pr_sd_alpha}{Numeric; the standard deviation of the log normal prior for alpha. Default is 1.}

\item{pr_a_theta}{Numeric; the shape parameter of the inverse gamma prior for the variance of theta. Default is 0.001.}

\item{pr_b_theta}{Numeric; the scale parameter of the inverse gamma prior for the variance of theta. Default is 0.001.}

\item{pr_a_eps}{Numeric; the shape parameter of inverse gamma prior for variance of data likelihood. Default is 0.001.}

\item{pr_b_eps}{Numeric; the scale parameter of inverse gamma prior for variance of data likelihood. Default is 0.001.}

\item{missing.val}{Numeric; a number to replace missing values. Default is 99.}

\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 theta parameter is fixed. Default is FALSE.}

\item{fix_alpha_1}{Logical; If TRUE, the first element of the alpha parameter is fixed to 1. Default is TRUE.}

\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}, \code{accept_alpha}, 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, alpha). 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/alpha/gamma}: Numeric; (optional) parameter-specific target acceptance rates to override \code{target_accept}.
}}
}
\value{
\code{lsirm2pl_normal_mcar} returns an object of  list containing the following components:
 \item{data}{A data frame or matrix containing the variables used in the model.}
 \item{missing.val}{A number to replace missing values.}
 \item{bic}{Numeric value with the corresponding BIC.}
\item{mcmc_inf}{Details about the number of MCMC iterations, burn-in periods, and thinning intervals.}
\item{map_inf}{The log maximum a posteriori (MAP) value and the iteration number at which this MAP value occurs.}
\item{beta_estimate}{Posterior estimates of the beta parameter.}
\item{theta_estimate}{Posterior estimates of the theta parameter.}
\item{sigma_theta_estimate}{Posterior estimates of the standard deviation of theta.}
\item{gamma_estimate}{Posterior estimates of gamma parameter.}
\item{z_estimate}{Posterior estimates of the z parameter.}
\item{w_estimate}{Posterior estimates of the w parameter.}
\item{beta}{Posterior samples of the beta parameter.}
\item{theta}{Posterior samples of the theta parameter.}
\item{theta_sd}{Posterior samples of the standard deviation of theta.}
\item{gamma}{Posterior samples of the gamma parameter.}
\item{z}{Posterior samples of the z parameter, represented as a 3-dimensional matrix where the last axis denotes the dimension of the latent space.}
\item{w}{Posterior samples of the w parameter, represented as a 3-dimensional matrix where the last axis denotes the dimension of the latent space.}
\item{z_raw}{Posterior samples of the z parameter without procrustes matching.}
\item{w_raw}{Posterior samples of the w parameter without procrustes matching.}
\item{accept_beta}{Acceptance ratio for the beta parameter.}
\item{accept_theta}{Acceptance ratio for the theta parameter.}
\item{accept_z}{Acceptance ratio for the z parameter.}
\item{accept_w}{Acceptance ratio for the w parameter.}
\item{accept_gamma}{Acceptance ratio for the gamma parameter.}
\item{sigma_estimate}{Posterior estimates of the standard deviation.}
\item{sigma}{Posterior samples of the standard deviation.}
\item{alpha_estimate}{Posterior estimates of the alpha parameter.}
 \item{alpha}{Posterior estimates of the alpha parameter.}
 \item{accept_alpha}{Acceptance ratio for the alpha parameter.}
}
\description{
\link{lsirm2pl_normal_mcar} is used to fit 2PL LSIRM for continuous variable in incomplete data assumed to be missing completely at random.
\link{lsirm2pl_normal_mcar} factorizes item response matrix into column-wise item effect, row-wise respondent effect and further embeds interaction effect in a latent space, while ignoring the missing element under the assumption of missing completely at random. Unlike 1PL model, 2PL model assumes the item effect can vary according to respondent, allowing additional parameter multiplied with respondent effect. The resulting latent space provides an interaction map that represents interactions between respondents and items.
}
\details{
\code{lsirm2pl_normal_mcar} models the continuous value of response by respondent \eqn{j} to item \eqn{i} with item effect \eqn{\beta_i}, respondent effect \eqn{\theta_j} and the distance between latent position \eqn{w_i} of item \eqn{i} and latent position \eqn{z_j} of respondent \eqn{j} in the shared metric space, with \eqn{\gamma} represents the weight of the distance term. For 2pl model, the the item effect is assumed to have additional discrimination parameter \eqn{\alpha_i} multiplied by \eqn{\theta_j}: \deqn{Y_{j,i} = \alpha_i\theta_j+\beta_i-\gamma||z_j-w_i|| + e_{j,i}} where the error \eqn{e_{j,i} \sim N(0,\sigma^2)} Under the assumption of missing completely at random, the model ignores the missing element in doing inference. For the details of missing completely at random assumption and data augmentation, see References.
}
\examples{
# generate example (continuous) item response matrix
data     <- matrix(rnorm(500, mean = 0, sd = 1),ncol=10,nrow=50)

# generate example missing indicator matrix
missing_mat     <- matrix(rbinom(500, size = 1, prob = 0.2),ncol=10,nrow=50)

# make missing value with missing indicator matrix
data[missing_mat==1] <- 99

lsirm_result <- lsirm2pl_normal_mcar(data)

# The code following can achieve the same result.
lsirm_result <- lsirm(data ~ lsirm2pl(spikenslab = FALSE, fixed_gamma = FALSE,
                      missing_data = "mcar"))

}
\references{
Little, R. J., & Rubin, D. B. (2019). Statistical analysis with missing data (Vol. 793). John Wiley & Sons.
}
