% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/qcaERT-conventions.R
\name{qcaERT_conventions}
\alias{qcaERT_conventions}
\title{qcaERT argument and output conventions}
\description{
The qcaERT robustness functions are siblings. They share a common public
structure for solution controls, exclusion handling, returned objects,
printing, and data-frame coercion. Individual function pages describe the
function-specific workflow; this page describes the package-wide conventions
that should be read consistently across the function family.
}
\section{Solution Controls}{

Most functions accept \code{solution}, \code{include}, \code{dir.exp}, \code{which_M}, and
\code{i_mode}.

\code{solution} may be \code{"all"}, \code{"con"}/\code{"conservative"},
\code{"par"}/\code{"parsimonious"}, or \code{"int"}/\code{"intermediate"}. For single-solution-type
calls, \code{include} is optional and is resolved from \code{solution}: conservative
uses \code{include = ""}, while parsimonious and intermediate use
\code{include = "?"}. Intermediate solutions require \code{dir.exp}.

When \code{solution = "all"}, do not supply \code{include}. The monitored set contains
conservative and parsimonious solutions by default. If \code{dir.exp} is supplied,
the intermediate solution is also monitored. In stepwise boundary searches
such as \code{\link[=incl.test]{incl.test()}}, \code{\link[=ncut.test]{ncut.test()}}, and \code{\link[=calib.test]{calib.test()}}, these solution
types are searched independently; one solution type changing does not stop
the search for another solution type. When a baseline or step fails in one
monitored solution type, inspect the solution-type-specific rows in
\code{diagnostics}, \code{results}, or supporting \verb{by_*} components before interpreting
an all-solution run as a single combined failure.

\code{which_M} selects the model or solution alternative to use when QCA
minimization returns multiple alternatives. \code{i_mode} controls which
intermediate branches are included; accepted values are \code{"all"} and
\code{"C1P1"}. Most robustness functions default to allowing all intermediate
branches. \code{theory.test()} defaults to \code{"C1P1"} because
comparative theory testing needs one comparable intermediate branch per
theory by default.
}

\section{Exclusions}{

Functions that can monitor parsimonious or intermediate solutions use a
common exclusion convention. \code{exclude_mode = "recompute"} recalculates excluded
rows for each perturbed, reduced, or sampled truth table using
\code{\link[QCA:findRows]{QCA::findRows()}} and \code{exclude_recompute}. \code{exclude_mode = "static"}
reuses the supplied \code{exclude_static} object. \code{exclude_mode = "none"} avoids
exclusion handling.

The family default for recomputation is
\code{exclude_recompute = list(type = 2)}. \code{\link[=incl.test]{incl.test()}}, \code{\link[=ncut.test]{ncut.test()}},
\code{\link[=calib.test]{calib.test()}}, \code{\link[=loo.test]{loo.test()}}, \code{\link[=subsample.test]{subsample.test()}}, \code{\link[=altset.test]{altset.test()}}, and
\code{\link[=theory.test]{theory.test()}} share this \code{exclude_mode}, \code{exclude_recompute}, and
\code{exclude_static} convention. \code{cluster.test()} starts from an existing truth
table and therefore accepts \code{exclude} directly instead of exposing
\code{exclude_mode}.
}

\section{Calibration Specifications}{

Calibration-family functions use \code{calib_spec} for calibration information.
A \code{calib_spec} entry is named by calibrated set, contains the raw source name
in \code{raw}, the calibration \code{type}, and \code{thresholds}, and may contain \code{method}
and a \code{calibrate} list forwarded to \code{\link[QCA:calibrate]{QCA::calibrate()}}.

For condition-only calibration tests, \code{calib_spec} is named by
\code{conditions}. When \code{calib.test()} or \code{altset.test()} is called with
\code{test.outcome = TRUE}, \code{calib_spec} is named by \code{c(conditions, outcome)}.
The outcome must not be included in
\code{conditions}; outcome calibration testing is requested explicitly with
\code{test.outcome = TRUE}.

Crisp conditions use one threshold. Fuzzy direct calibration supports three
thresholds in \code{c(E, C, I)} order or six thresholds in
\code{c(E1, C1, I1, I2, C2, E2)} order. Fuzzy indirect calibration treats its
thresholds as ordered cutpoints.

These calibration-perturbation routines are designed for QCA workflows using
crisp and fuzzy sets. They are not multi-value calibration tools.
In \code{\link[=loo.test]{loo.test()}} and \code{\link[=subsample.test]{subsample.test()}} with \code{calib = "recompute"}, a
\code{calib_spec} entry may additionally contain \code{findTh}, a named list of
\code{\link[QCA:findTh]{QCA::findTh()}} arguments, to re-estimate thresholds on each reduced or
subsampled raw dataset. Without \code{findTh}, the baseline \code{thresholds} stored in
\code{calib_spec} are reused.
}

\section{Result Objects}{

Most robustness functions return an S3 object with \code{diagnostics}, \code{results},
and \code{settings}, plus supporting components such as \code{baseline}, \code{bounds},
\code{by_direction}, \code{by_case}, \code{by_run}, \code{by_draw}, or \code{summary}.

\code{diagnostics} is the detailed internal table. \code{results} is the clean
table. The \code{print()} method shows a concise summary plus the
results, and \code{as.data.frame()} returns the clean \code{results} table.

For \code{\link[=incl.test]{incl.test()}}, \code{\link[=ncut.test]{ncut.test()}}, and \code{\link[=calib.test]{calib.test()}}, \code{result_shape}
controls the layout of the clean \code{results} table when \code{solution = "all"}.
The default \code{"wide"} layout keeps one row per tested path and uses
solution-type-prefixed columns such as \code{con_last_safe} and \code{par_reason}. The
\code{"long"} layout uses one row per tested path and solution type, with a
\code{solution_type} column. The raw \code{diagnostics} table is unchanged.

\code{cluster.test()} and \code{theory.test()} use structured \code{results} lists because
their clean output has more than one natural table. \code{cluster.test()} returns
\code{overview}, \code{clusters}, and \code{units}; \code{as.data.frame()} returns
\code{results$overview}. \code{theory.test()} returns \code{models}, \code{pairwise}, and
\code{solutions}; \code{as.data.frame()} returns \code{results$models}.
}

\section{Plotting}{

Plotting requires \code{ggplot2}. \code{plot()} methods are provided
for \code{incl_test}, \code{calib_test}, and \code{theory_test} objects. Interval and trace
views map directly to stored boundary-search diagnostics; theory plots map
selected theory-specific models into consistency/coverage space.
\code{\link[=sol.chart]{sol.chart()}} renders \code{\link[=sol.df]{sol.df()}} tables as solution charts. See
\code{?qcaERT_plots} and \code{?sol.chart}.
}

\section{QCA Solution Objects}{

\code{cluster.test()} and \code{\link[=sol.df]{sol.df()}} consume QCA minimization objects. \code{\link[=sol.df]{sol.df()}}
extracts a compact data frame, and \code{\link[=sol.chart]{sol.chart()}} gives a visual display of
that extracted table. Case and solution-expression reconstruction use the
data-frame \code{pims} component produced by \code{\link[QCA:minimize]{QCA::minimize()}}.
}

