% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vbmimic.R
\name{vbmimic}
\alias{vbmimic}
\title{Regularized variational Bayes for extended MIMIC models}
\usage{
vbmimic(
  Y,
  X,
  Q_A,
  Q_B,
  v0 = 0.001,
  standardize = FALSE,
  max_it = 1000,
  convChk = FALSE,
  tolVal = 1e-05
)
}
\arguments{
\item{Y}{Numeric \verb{N x J} data matrix (observations by items). Missing values
in \code{Y} are supported: because the residual covariance is diagonal, a
missing response is replaced in-loop by its conditional expectation
\verb{eta_i A'}, with the conditional variance carried into the residual sum
of squares. Items or rows with no observed response are rejected.}

\item{X}{Numeric \verb{N x P} matrix of observed covariates (predictors of the
factors), with the same number of rows as \code{Y}. Missing covariates are
\strong{not} supported: \code{X} is conditioned on rather than modelled, so
imputing it would require a distributional assumption the MIMIC model
does not make.}

\item{Q_A}{Integer \verb{J x K} measurement design matrix: \code{1} = specified
(anchored) loading, \code{0} = fixed zero, \code{-1} = unspecified (selected by
spike-and-slab). \code{K} is the number of factors.}

\item{Q_B}{Integer \verb{K x P} structural design matrix using the same coding,
for the regression of the \code{K} factors on the \code{P} covariates.}

\item{v0}{Spike variance. A scalar gives a single fixed spike; a decreasing
vector gives a warm-started regularization path, each stage initialized at
the previous stage's solution (Rockova & George, 2018). The same schedule
is applied to the measurement and structural parts. \code{v0 = 0.001} (the
default) is the fixed spike of the published estimator.}

\item{standardize}{Logical; standardize \code{Y} and \code{X} before fitting. The
default \code{FALSE} is the behaviour of the published estimator. Note that
\code{\link[=vbfa]{vbfa()}} always standardizes internally; set \code{standardize = TRUE} for the
analogous behaviour here.}

\item{max_it}{Maximum number of variational iterations \emph{per stage}.}

\item{convChk}{Logical; print per-iteration convergence information via
\code{\link[=message]{message()}}. Default \code{FALSE} (quiet).}

\item{tolVal}{Convergence tolerance on the maximum absolute change in the
weighted residual vector.}
}
\value{
An object of class \code{c("vbmimic", "vbpm_fit")} -- a named list (see
\link{vbpm_fit}) with components:
\describe{
\item{A}{\verb{J x K} posterior mean measurement loadings.}
\item{B}{\verb{K x P} posterior mean structural coefficients.}
\item{pi_A, pi_B}{Posterior inclusion probabilities for the unspecified
entries of \code{Q_A} and \code{Q_B} (specified entries are held at 1, fixed
zeros at 0).}
\item{Q_A, Q_B}{The design matrices the model was fit with.}
\item{eta}{\verb{N x K} posterior mean factor scores.}
\item{Phi}{\verb{K x K} factor correlation matrix implied by \code{Sig}.}
\item{Sig, U}{Factor covariance matrix and its inverse.}
\item{V}{Length-\code{J} residual precisions.}
\item{rho, theta}{Inclusion rates for the measurement and structural
parts.}
\item{A_var, B_var}{Posterior variances of the loadings and structural
coefficients.}
\item{iter, flag, time}{Total iterations, \code{1} if the final stage
converged within \code{max_it} (else \code{0}), and elapsed time.}
\item{ELBO}{\code{NA_real_}; see Note.}
\item{standardize}{The \code{standardize} setting the model was fit with.}
\item{path}{The \code{v0} schedule and per-stage iteration counts.}
\item{preprocess}{\code{n_missing}, the response type, and \code{missing_mask} --
stored only when the data contain missing values, \code{NULL} otherwise.}
}

Every quantity appears exactly once: as of 0.7.0 the fit no longer
carries \verb{$coefficients}, \verb{$design}, \verb{$posterior}, or \verb{$settings}, which
duplicated the elements above.
}
\description{
Fits a partially confirmatory multiple-indicators multiple-causes (MIMIC)
model by a variational Bayes EM algorithm, with continuous spike-and-slab
regularization on \strong{both} the measurement and the structural part. Items
load on factors through a measurement design matrix \code{Q_A}, while covariates
predict the factors through a structural design matrix \code{Q_B}; entries of
either that are left unspecified are selected from the data.
}
\details{
This is the MIMIC member of the \code{vbpm} family and is the companion of
\code{\link[=vbfa]{vbfa()}}, which fits the measurement part alone. The two share the \code{-1/0/1}
design-matrix convention and the spike-and-slab formulation.
}
\note{
The evidence lower bound is \strong{not} currently returned. The published
algorithm converges on the weighted residual vector rather than on the
bound, and the bound's implementable closed form has not been assembled.
\code{\link[=fit_stats]{fit_stats()}} does accept a \code{vbmimic} fit, but returns a deliberately
limited result: \code{n_active_coef} (soft-selected measurement and structural
coefficients) plus typed \code{NA} for every covariance-based index and
parameter count, with an explanatory \code{note} attribute. \code{\link[=pefa]{pefa()}} does not
accept \code{vbmimic} fits at all: its sweep reports criterion gains across a
factor-count window, which requires one comparable objective for every
candidate in that window.
}
\examples{
## 3 factors, 18 items, 9 covariates in disjoint blocks of 3
B <- matrix(0, 3, 9)
for (k in 1:3) B[k, ((k - 1) * 3 + 1):(k * 3)] <- .3
sim <- sim_lvm(N = 300, K = 3, J = 18, P = 9, b = B, phx = 0, rseed = 1)
Y <- sim$dat[, 1:18]
X <- sim$dat[, 19:27]

## two anchored items per factor; the structural part left exploratory.
## Anchoring at least one part is advisable: with both Q_A and Q_B fully
## exploratory the solution can be rotationally ambiguous.
Q_A <- matrix(-1L, 18, 3)
for (k in 1:3) {
  a <- which(rep(1:3, each = 6) == k)[1:2]
  Q_A[a, ] <- 0L; Q_A[a, k] <- 1L
}
Q_B <- matrix(-1L, 3, 9)

fit <- vbmimic(Y, X, Q_A, Q_B)
fit$flag           # 1 if converged
round(fit$B, 2)    # structural coefficients

}
\references{
Jin, Y., & Chen, J. (2025). Regularized variational Bayesian approximations
for variable selection in extended multiple-indicators multiple-causes
models. \emph{Multivariate Behavioral Research}.
\doi{10.1080/00273171.2025.2483253}

Rockova, V., & George, E. I. (2018). The spike-and-slab LASSO.
\emph{Journal of the American Statistical Association}, 113(521), 431-444.
}
\seealso{
\code{\link[=vbfa]{vbfa()}} for the measurement model alone, \code{\link[=sim_lvm]{sim_lvm()}} to simulate
MIMIC data.
}
