% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/feature_pcm.R
\name{assess_pcm}
\alias{assess_pcm}
\title{Predictive Contribution of the Mediator (PCM)}
\usage{
assess_pcm(seminr_model, target = NULL, noFolds = 10, reps = 10)
}
\arguments{
\item{seminr_model}{A PLS model estimated by \code{seminr::estimate_pls()}.}

\item{target}{Character string specifying the outcome construct. If
\code{NULL}, auto-detects when a single final endogenous construct exists.}

\item{noFolds}{Integer, number of folds for cross-validation (default 10).}

\item{reps}{Integer, number of cross-validation repetitions (default 10).}
}
\value{
An object of class \code{pcm_analysis} containing:
\describe{
  \item{target}{The outcome construct name.}
  \item{mediation_paths}{List of identified mediation triples
    (antecedent, mediator, target).}
  \item{pcm_results}{List of per-path results, each with RMSE/MAE for DA
    and EA approaches plus PCM values per indicator.}
  \item{noFolds}{Number of cross-validation folds used.}
  \item{reps}{Number of cross-validation repetitions used.}
}
}
\description{
Evaluates the predictive contribution of mediating constructs in a PLS-SEM
model. For each mediation path (antecedent -> mediator -> target), computes
the PCM metric by comparing cross-validated predictions from the Direct
Antecedents (DA) and Earliest Antecedents (EA) approaches on an isolated
partial mediation sub-model.
}
\details{
The PCM metric (Danks, 2021) quantifies the predictive improvement due to
the mediator. It is computed by isolating each mediation path into a partial
mediation sub-model (X -> M -> Y with direct path X -> Y), then comparing
out-of-sample predictions from two approaches:

\itemize{
  \item \strong{DA (Direct Antecedents)}: Predicts Y using its direct
    structural predictors (M and X).
  \item \strong{EA (Earliest Antecedents)}: Predicts Y using only the
    earliest antecedent (X), propagated through the structural model.
}

\deqn{PCM = \frac{METRIC_{EA} - METRIC_{DA}}{METRIC_{EA}}}

Rules of thumb for PCM interpretation:
\itemize{
  \item \strong{0 to 0.05}: Weak predictive contribution
  \item \strong{0.05 to 0.10}: Moderate predictive contribution
  \item \strong{Greater than 0.10}: Strong predictive contribution
  \item \strong{Negative}: Mediator damages predictive accuracy
}
}
\examples{
\donttest{
library(seminr)
data(mobi)

# Simple mediation: Image -> Satisfaction -> Loyalty
mobi_mm <- constructs(
  composite("Image",        multi_items("IMAG", 1:5)),
  composite("Satisfaction", multi_items("CUSA", 1:3)),
  composite("Loyalty",      multi_items("CUSL", 1:3))
)
mobi_sm <- relationships(
  paths(from = "Image", to = "Satisfaction"),
  paths(from = "Satisfaction", to = "Loyalty"),
  paths(from = "Image", to = "Loyalty")
)
model <- estimate_pls(mobi, mobi_mm, mobi_sm)

# Compute PCM
pcm <- assess_pcm(model, target = "Loyalty", noFolds = 10, reps = 10)
pcm
summary(pcm)
}

}
\references{
Danks, N. P. (2021). The Piggy in the Middle: The Role of
Mediators in PLS-SEM Prediction. \emph{The DATA BASE for Advances in
Information Systems}, 52(SI), 24-42.
}
\seealso{
\code{\link[seminr]{predict_pls}} for the underlying prediction
  methods.
}
