% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nmf.ffb.R, R/nmf.sem.R
\name{nmf.ffb.inference}
\alias{nmf.ffb.inference}
\alias{nmf.sem.inference}
\title{Statistical inference for NMF-FFB via X-fixed full pair bootstrap}
\usage{
nmf.ffb.inference(
  object,
  Y1,
  Y2,
  B = 1000L,
  threshold = 0.01,
  ci.level = 0.95,
  C1.L1 = 1,
  C2.L1 = 0.1,
  seed = 123L,
  ...
)

nmf.sem.inference(
  object,
  Y1,
  Y2,
  B = 1000L,
  threshold = 0.01,
  ci.level = 0.95,
  C1.L1 = 1,
  C2.L1 = 0.1,
  seed = 123L,
  ...
)
}
\arguments{
\item{object}{A fitted object returned by \code{\link{nmf.sem}}.  Must
contain \code{X}, \code{C1}, \code{C2}.}

\item{Y1}{Endogenous variable matrix (P1 x N).  Must match the data
used in \code{nmf.sem()}.}

\item{Y2}{Exogenous variable matrix (P2 x N).  Same.}

\item{B}{Number of bootstrap replicates.  Default \code{1000}; required
for the \code{***} threshold (sup > 0.999).  Reduce to 500 for
exploratory speed (only \code{*} / \code{**} stay reliable).}

\item{threshold}{Display threshold \eqn{\delta} for the support rate
\eqn{\Pr_{\mathrm{boot}}(\hat c^{(b)} > \delta)}.  Default
\code{0.01}; entries below this magnitude are treated as effectively
zero in the path diagram.}

\item{ci.level}{Confidence level for the percentile bootstrap CI.
Default \code{0.95}.}

\item{C1.L1, C2.L1}{L1 sparsity penalties used by the original
\code{\link{nmf.sem}} fit.  These must match the fit's hyperparameters
for the bootstrap to estimate the correct model.  Defaults
(\code{1.0}, \code{0.1}) match \code{nmf.sem}'s defaults but you
should pass the actual values used.}

\item{seed}{Base RNG seed for the bootstrap.  Each replicate uses
\code{seed + b} (resampling) and \code{seed + 1000 + b}
(\eqn{C_1, C_2} initialization).  Default \code{123}.}

\item{...}{Hidden options:
\describe{
\item{\code{epsilon}}{Convergence tolerance for the inner fixed-X MU
loop.  Default \code{1e-6}.}
\item{\code{maxit}}{Maximum iterations for the inner MU loop.
Default \code{5000}.}
\item{\code{ncores}}{Number of parallel workers.  Default \code{1}
(serial).  Cross-platform: uses \code{parallel::mclapply} on
Linux/macOS and \code{parallel::parLapply} (PSOCK cluster) on
Windows.}
\item{\code{print.trace}}{Logical, print progress.  Default
\code{FALSE}.}
}}
}
\value{
The input \code{object} with additional bootstrap inference
components:
\item{coefficients}{Data frame with rows for every entry of \eqn{C_1}
and \eqn{C_2} and columns \code{Type} ("C1" / "C2"), \code{Basis},
\code{Covariate}, \code{Estimate}, \code{CI_low}, \code{CI_high},
\code{support_rate}, \code{p_value} (\eqn{= 1 - \mathrm{support\_rate}},
for compatibility with downstream consumers such as
\code{\link{nmf.sem.DOT}}), and \code{sig}.}
\item{C1.support.rate, C2.support.rate}{Per-element support rates
(Q x P1 and Q x P2 matrices).}
\item{C1.ci.lower, C1.ci.upper, C2.ci.lower, C2.ci.upper}{Per-element
percentile CI bounds.}
\item{C1.array, C2.array}{Bootstrap distributions: 3D arrays of shape
B x Q x P1 (and B x Q x P2).  Invalid replicates contain \code{NA}.}
\item{rho.boot, AR.boot, iter.boot}{Per-replicate spectral radius,
amplification ratio, and inner-loop iteration count.}
\item{bootstrap.B, bootstrap.threshold, bootstrap.ci.level}{Inputs
recorded for reproducibility.}
\item{bootstrap.n.valid, bootstrap.n.invalid}{Validity counts.}
}
\description{
\code{nmf.sem.inference} performs statistical inference on the structural
coefficient matrices \eqn{C_1} (latent feedback, \eqn{\Theta_1}) and
\eqn{C_2} (exogenous loading, \eqn{\Theta_2}) from a fitted
\code{\link{nmf.sem}} model.

The procedure is a \strong{full pair bootstrap} that holds the basis
matrix \eqn{\hat X} from the original fit fixed across all replicates
(which avoids label switching and gives a clean conditional
interpretation: ``uncertainty of the structural coefficients given the
measurement model''):
\enumerate{
\item For each replicate \eqn{b = 1, \dots, B}, resample column indices
\eqn{(i_1, \dots, i_N)} with replacement from \eqn{\{1, \dots, N\}}
and form \eqn{Y_1^{(b)} = Y_1[, i]}, \eqn{Y_2^{(b)} = Y_2[, i]}.
\item Re-estimate \eqn{(C_1^{(b)}, C_2^{(b)})} by running the
\code{\link{nmf.sem}} multiplicative updates \emph{with \eqn{X = \hat X}
held fixed} (no \eqn{X} update; no centroid sort), using the same
\code{C1.L1}, \code{C2.L1} as the original fit.
\item Discard replicates that violate stationarity
(\eqn{\rho(X C_1^{(b)}) \ge 1}) or have an amplification ratio
exceeding the geometric-series bound by more than 1\\%.
}
Because \eqn{C_1, C_2 \ge 0} are non-negative by construction, exact
zeros are essentially never observed in the bootstrap distribution.
Significance is assessed via a \strong{support rate} at a small display
threshold \eqn{\delta} (default \code{0.01}):
\deqn{
  \mathrm{sup}(c) \;=\; \frac{1}{|\mathrm{valid}|}
    \sum_{b \in \mathrm{valid}} \mathbf{1}\!\left( \hat c^{(b)} > \delta \right).
}
This is a one-sided counterpart of the classical \eqn{p}-value:
large \code{support_rate} indicates strong evidence that the entry is
meaningfully positive.  Significance markers follow the lavaan
convention with the natural correspondence \eqn{p = 1 - \mathrm{sup}}:
\code{*} (sup > 0.95), \code{**} (sup > 0.99), \code{***}
(sup > 0.999).  Cutoffs use strict greater-than so the rule
mirrors the standard R convention for p-values (p < 0.05 / 0.01 /
0.001 → \emph{/\strong{/}}), translated to support_rate via
\eqn{\mathrm{sup} = 1 - p}.
}
\section{Lifecycle}{

This function's interface changed at v0.6.8: the legacy 1-step Newton
wild bootstrap (with sandwich SE) has been replaced by the full pair
bootstrap described above, following the paper revision.  The fields
\code{sigma2.used}, \code{C2.se}, \code{C2.se.boot}, \code{C2.p.side}
that the previous implementation produced are no longer present.
}

\examples{
\donttest{
Y <- t(iris[, -5])
Y1 <- Y[1:2, ]; Y2 <- Y[3:4, ]
res  <- nmf.sem(Y1, Y2, rank = 2)
res2 <- nmf.sem.inference(res, Y1, Y2, B = 200)  # quick demo
head(res2$coefficients)
}
}
\references{
Satoh, K. (2025). Applying non-negative matrix factorization with covariates
to structural equation modeling for blind input-output analysis.
arXiv:2512.18250. \url{https://arxiv.org/abs/2512.18250}
}
\seealso{
\code{\link{nmf.sem}}, \code{\link{nmf.sem.DOT}}
}
