% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lsirm1pl_normal_mcar.R
\name{lsirm1pl_normal_mcar}
\alias{lsirm1pl_normal_mcar}
\title{1PL LSIRM with normal likelihood for missing completely at random data.}
\usage{
lsirm1pl_normal_mcar(
  data,
  ndim = 2,
  niter = 15000,
  nburn = 2500,
  nthin = 5,
  nprint = 500,
  jump_beta = 0.4,
  jump_theta = 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_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,
  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_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_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{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}.
}}
}
\value{
\code{lsirm1pl_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.}
}
\description{
\link{lsirm1pl_normal_mcar} is used to fit LSIRM with 1pl in incomplete data assumed to be missing completely at random.
\link{lsirm1pl_normal_mcar} factorizes continuous 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. The resulting latent space provides an interaction map that represents interactions between respondents and items.
}
\details{
\code{lsirm1pl_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: \deqn{Y_{j,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 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 <- lsirm1pl_normal_mcar(data)

# The code following can achieve the same result.
lsirm_result <- lsirm(data ~ lsirm1pl(spikenslab = FALSE, fixed_gamma = FALSE,
missing_data ='mcar', missing.val = 99))

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