% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/feature_cipma.R
\name{assess_cipma}
\alias{assess_cipma}
\title{Combined Importance-Performance Map Analysis (cIPMA) for PLS-SEM}
\usage{
assess_cipma(
  seminr_model,
  target,
  scale_min = 1,
  scale_max = 7,
  nca = TRUE,
  nca_ceilings = c("ce_fdh", "cr_fdh"),
  nca_test.rep = 0,
  nca_steps = 10,
  seed = 123
)
}
\arguments{
\item{seminr_model}{An estimated SEMinR model from \code{estimate_pls()}.}

\item{target}{Name of the target (endogenous) construct for the IPMA.}

\item{scale_min}{Minimum of the measurement scale (default 1).}

\item{scale_max}{Maximum of the measurement scale (default 7).}

\item{nca}{Logical; if \code{TRUE} (default), run NCA to produce a cIPMA.}

\item{nca_ceilings}{Character vector of ceiling techniques for NCA
(default \code{c("ce_fdh", "cr_fdh")}).}

\item{nca_test.rep}{Number of NCA permutation test repetitions (default 0).
Set > 0 to obtain significance for the necessity classification.}

\item{nca_steps}{Number of bottleneck table steps (default 10).}

\item{seed}{Random seed for reproducibility (default 123).}
}
\value{
An object of class \code{cipma_analysis} containing:
  \item{importance_unstd}{Named numeric vector of unstandardized total effects}
  \item{importance_std}{Named numeric vector of standardized total effects}
  \item{performance}{Named numeric vector of construct performances (0--100)}
  \item{nca}{An \code{nca_analysis} object (NULL if \code{nca = FALSE})}
  \item{classification}{Data frame classifying each construct}
  \item{target}{Name of the target construct}
  \item{constructs}{Character vector of included constructs}
  \item{scale_range}{Numeric vector \code{c(scale_min, scale_max)}}
  \item{negative_weight_constructs}{Constructs with negative outer weights (if any)}
  \item{excluded_interactions}{Interaction constructs excluded from IPMA}
  \item{pls_model}{The original estimated seminr model}
}
\description{
\code{assess_cipma} conducts an Importance-Performance Map Analysis (IPMA)
and optionally combines it with Necessary Condition Analysis (NCA) to
produce a combined IPMA (cIPMA). The analysis identifies constructs that
are both important (high total effect) and necessary (without which the
outcome cannot reach high levels), following the 7-step cIPMA procedure
of Sarstedt et al. (2024).
}
\details{
\strong{Importance} is measured by the unstandardized total effect of each
construct on the target. Unstandardized effects are obtained by scaling
standardized path coefficients using the standard deviations of rescaled
(0--100) construct scores.

\strong{Performance} is the weighted average of rescaled indicator means,
where each indicator is rescaled from the original measurement scale
([\code{scale_min}, \code{scale_max}]) to 0--100. Weights are the PLS
outer weights, which must all be positive for valid IPMA rescaling.

Interaction constructs (e.g., \code{"X*W"}) are automatically excluded
from the IPMA because their performance is not meaningful on a 0--100
scale.

When \code{nca = TRUE}, NCA is run on construct scores for each
predecessor--target pair, and constructs are classified into four
categories based on crossing importance (above/below median) with
necessity (NCA d >= 0.1 and p < 0.05).
}
\examples{
library(seminr)
library(seminrExtras)

mobi_mm <- constructs(
  composite("Image",        multi_items("IMAG", 1:5)),
  composite("Expectation",  multi_items("CUEX", 1:3)),
  composite("Value",        multi_items("PERV", 1:2)),
  composite("Satisfaction", multi_items("CUSA", 1:3)),
  composite("Loyalty",      multi_items("CUSL", 1:3))
)

mobi_sm <- relationships(
  paths(from = "Image",       to = c("Expectation", "Satisfaction", "Loyalty")),
  paths(from = "Expectation", to = c("Value", "Satisfaction")),
  paths(from = "Value",       to = "Satisfaction"),
  paths(from = "Satisfaction",to = "Loyalty")
)

mobi_pls <- estimate_pls(data = mobi,
                          measurement_model = mobi_mm,
                          structural_model  = mobi_sm)

\donttest{
cipma_result <- assess_cipma(mobi_pls,
                              target = "Loyalty",
                              scale_min = 1,
                              scale_max = 10)
print(cipma_result)
summary(cipma_result)
plot(cipma_result)
}

}
\references{
Ringle, C. M. & Sarstedt, M. (2016). Gain More Insight from Your PLS-SEM
Results: The Importance-Performance Map Analysis. Industrial Management &
Data Systems, 119(9), 1865-1886.

Sarstedt, M., Richter, N. F., Hauff, S. & Ringle, C. M. (2024). Combined
Importance-Performance Map Analysis (cIPMA): A SmartPLS 4 Tutorial.
Journal of Marketing Analytics, 12, 746-760.

Hauff, S. et al. (2024). Importance and Performance in PLS-SEM and NCA:
Introducing the cIPMA. Journal of Retailing and Consumer Services, 78,
103723.
}
\seealso{
\code{\link{assess_ipma}} for IPMA without NCA,
  \code{\link{assess_nca}} for standalone NCA analysis
}
