% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/incl.test.R
\name{incl.test}
\alias{incl.test}
\alias{print.incl_test}
\alias{as.data.frame.incl_test}
\title{Inclusion-cutoff robustness test for QCA solutions}
\usage{
incl.test(
  data,
  outcome,
  conditions = NULL,
  incl.cut = 1,
  step = 0.01,
  max_steps = 20,
  n.cut = 1,
  solution = "all",
  include = NULL,
  dir.exp = NULL,
  which_M = 1,
  i_mode = c("all", "C1P1"),
  exclude_mode = c("recompute", "static", "none"),
  exclude_recompute = list(type = 2),
  exclude_static = NULL,
  result_shape = c("wide", "long"),
  progress = TRUE,
  ...
)

\method{print}{incl_test}(x, row.names = FALSE, ...)

\method{as.data.frame}{incl_test}(x, ...)
}
\arguments{
\item{data}{A non-empty data frame object containing the outcome and
condition columns used in the QCA analysis.}

\item{outcome}{Name of the outcome. This must be a single
non-empty character string.}

\item{conditions}{Optional character vector of condition names. If \code{NULL},
the condition set is left to \code{\link[QCA:truthTable]{QCA::truthTable()}}.}

\item{incl.cut}{Baseline inclusion cutoff passed to \code{\link[QCA:truthTable]{QCA::truthTable()}}.
This must be a single finite number in \verb{[0, 1]}.}

\item{step}{Positive numeric step size used to move \code{incl.cut} downward and
upward from the baseline value.}

\item{max_steps}{Maximum number of stepwise moves to attempt in each
direction.}

\item{n.cut}{Frequency cutoff passed to \code{\link[QCA:truthTable]{QCA::truthTable()}}.}

\item{solution}{Solution type to monitor. Accepted values are \code{"all"},
\code{"con"} or \code{"conservative"}, \code{"par"} or \code{"parsimonious"}, and \code{"int"} or
\code{"intermediate"}.}

\item{include}{Optional minimization include setting. Currently, this
argument accepts only \code{NULL}, \code{""}, or \code{"?"}.}

\item{dir.exp}{Directional expectations used when the monitored solution is
intermediate.}

\item{which_M}{Positive integer giving which solution alternative to use
when minimization returns multiple models.}

\item{i_mode}{Character string controlling intermediate-solution selection.
Accepted values are \code{"all"} and \code{"C1P1"}.}

\item{exclude_mode}{Character string controlling how excluded rows are
handled for parsimonious and intermediate minimization. \code{"recompute"}
recalculates exclusions from each truth table, \code{"static"} reuses
\code{exclude_static}, and \code{"none"} does not use exclusions.}

\item{exclude_recompute}{Named list of arguments passed to \code{\link[QCA:findRows]{QCA::findRows()}}
when \code{exclude_mode = "recompute"}.}

\item{exclude_static}{Already computed exclusion object reused when
\code{exclude_mode = "static"}.}

\item{result_shape}{Layout of the clean \code{results} table when
\code{solution = "all"}. \code{"wide"} keeps one row per direction with
solution-type-specific columns such as \code{con_last_safe} and \code{par_reason}.
\code{"long"} returns one row per direction and solution type, with a \code{solution_type}
column. Single-solution-type calls keep the compact single-solution-type
layout.}

\item{progress}{Logical; if \code{TRUE} and the session is interactive, show a
text progress bar.}

\item{...}{Additional arguments routed through the QCA workflow. Arguments
matching \code{\link[QCA:truthTable]{QCA::truthTable()}} are forwarded to truth table construction;
remaining minimization arguments are filtered and forwarded to
\code{\link[QCA:minimize]{QCA::minimize()}}. The function also looks in \code{...} for \code{include},
\code{dir.exp}, or \code{direxp} if those arguments were not supplied explicitly.
In \code{\link[=print.incl_test]{print.incl_test()}}, \code{...} is passed to \code{\link[=print.data.frame]{print.data.frame()}}. In
\code{\link[=as.data.frame.incl_test]{as.data.frame.incl_test()}}, \code{...} is ignored.}

\item{x}{An \code{incl_test} object returned by \code{\link[=incl.test]{incl.test()}}.}

\item{row.names}{Logical; passed to \code{\link[=print.data.frame]{print.data.frame()}} by
\code{\link[=print.incl_test]{print.incl_test()}}.}
}
\value{
An object of class \code{incl_test} with the following components:
\describe{
\item{\code{diagnostics}}{A detailed data frame with one row for the lower
search and one row for the upper search. When \code{solution = "all"}, each
monitored solution type is searched independently, so diagnostics has
one row per direction and solution type. It includes the baseline
\code{incl.cut}, the last safe value, the first failing value, the number of
successful steps, stop reason, change classification, and exclusion
information for the baseline, last safe, and first failing runs.}
\item{\code{results}}{A compact data frame with the columns
\code{direction}, \code{start}, \code{last_safe}, \code{first_failing}, \code{steps},
\code{total_delta}, and \code{reason}. When \code{solution = "all"} and
\code{result_shape = "wide"}, the row unit remains \code{direction}, but the
boundary and reason columns are solution-type-specific, using prefixes \code{con_},
\code{par_}, and, when available, \code{int_}. When \code{result_shape = "long"},
\code{results} has one row per direction and solution type.}
\item{\code{bounds}}{A named numeric vector with \code{Lower} and \code{Upper}
elements taken from the last safe values in each search direction. When
\code{solution = "all"}, this is a lower/upper matrix with one column per
monitored solution type.}
\item{\code{baseline}}{A list containing the baseline truth table,
minimization results, selected solution terms used for comparison,
exclusion set used, and
status information.}
\item{\code{by_direction}}{A named list with one entry for the lower search
and one for the upper search, each containing the search trace and
stopping information.}
\item{\code{settings}}{A list containing the analysis settings used to build
the result object.}
}

\code{print.incl_test()} prints a concise summary and the \code{results} table.
\code{as.data.frame.incl_test()} returns the \code{results} table.
If \code{ggplot2} is installed, \code{plot.incl_test()} provides interval and trace
views; see \code{?qcaERT_plots}.
}
\description{
Perturbs the truth table inclusion cutoff used in the analysis and checks
when the monitored QCA solution changes. Starting from a baseline
\code{incl.cut}, the function searches downward and upward in fixed steps and
records the last value that preserved the baseline solution, the first value
that changed the solution or triggered an error, and the reason the search
stopped in each direction.
}
\details{
The baseline analysis is built with \code{\link[QCA:truthTable]{QCA::truthTable()}} using the supplied
\code{incl.cut} and \code{n.cut}, followed by minimization under the requested
solution type. The function then tests lower and upper values of
\code{incl.cut} one step at a time. When \code{solution = "all"}, conservative,
parsimonious, and, when requested, intermediate paths are searched
independently.

A directional search stops when one of the following occurs:
\itemize{
\item the next tested value falls outside \verb{[0, 1]},
\item truth table construction fails,
\item exclusion recomputation fails,
\item minimization fails, or
\item the monitored solution changes relative to the baseline.
}

The shared solution-control, exclusion, and returned-object conventions are
described in \code{?qcaERT_conventions}.
}
\examples{
\donttest{
library(QCA)
data(LR)

conditions <- c("DEV", "URB", "LIT", "IND", "STB")
outcome <- "SURV"
dir_exp <- rep("1", length(conditions))

thresholds <- list(
  DEV = findTh(LR$DEV, groups = 7),
  URB = findTh(LR$URB, groups = 4),
  LIT = findTh(LR$LIT, groups = 4),
  IND = findTh(LR$IND, groups = 4),
  STB = findTh(LR$STB, groups = 4),
  SURV = findTh(LR$SURV, groups = 4)
)

dat <- LR
dat$DEV <- calibrate(LR$DEV, type = "fuzzy", thresholds = thresholds$DEV)
dat$URB <- calibrate(LR$URB, type = "fuzzy", thresholds = thresholds$URB)
dat$LIT <- calibrate(LR$LIT, type = "fuzzy", thresholds = thresholds$LIT)
dat$IND <- calibrate(LR$IND, type = "fuzzy", thresholds = thresholds$IND)
dat$STB <- calibrate(LR$STB, type = "fuzzy", thresholds = thresholds$STB)
dat$SURV <- calibrate(LR$SURV, type = "fuzzy", thresholds = thresholds$SURV)

out <- incl.test(
  data = dat,
  outcome = outcome,
  conditions = conditions,
  incl.cut = 0.8,
  step = 0.05,
  max_steps = 5,
  n.cut = 1,
  solution = "all",
  dir.exp = dir_exp,
  result_shape = "long",
  progress = TRUE
)

out
as.data.frame(out)
plot(out, solution_type = "conservative")
}

}
\seealso{
\link{qcaERT_plots}, \code{\link[=calib.test]{calib.test()}}, \code{\link[=ncut.test]{ncut.test()}}, \code{\link[=loo.test]{loo.test()}},
\code{\link[=subsample.test]{subsample.test()}}, \code{\link[=altset.test]{altset.test()}}, \code{\link[=theory.test]{theory.test()}}, \code{\link[=cluster.test]{cluster.test()}},
\code{\link[=sol.df]{sol.df()}}
}
