CTS (single): Single-condition threshold sweep

Performs a threshold sweep for one focal condition X. For each threshold in sweep_range, the outcome Y and all X variables are binarized using user-specified thresholds, and a crisp-set QCA is executed.

ctSweepS(
  dat,
  outcome = NULL,
  conditions = NULL,
  sweep_var,
  sweep_range,
  thrY,
  thrX_default = 7,
  pre_calibrated = NULL,
  dir.exp = NULL,
  include = "",
  incl.cut = 0.8,
  n.cut = 1,
  pri.cut = 0,
  extract_mode = c("first", "all", "essential"),
  return_details = TRUE,
  Yvar = NULL,
  Xvars = NULL
)

Arguments

dat: Data frame containing the outcome and condition variables.
outcome: Character. Outcome variable name. Supports negation with tilde prefix (e.g., "~Y") following QCA package conventions.
conditions: Character vector. Names of condition variables.
sweep_var: Character. Name of the condition to be swept. Must be one of conditions.
sweep_range: Numeric vector. Candidate thresholds for sweep_var.
thrY: Numeric. Threshold for Y (fixed).
thrX_default: Numeric. Default threshold for non-swept X variables. Variables listed in pre_calibrated do not require this threshold.
pre_calibrated: Character vector or NULL. Names of condition variables that have been pre-calibrated (e.g., via QCA::calibrate()) and should be passed through to QCA::truthTable() without binarization. These variables must contain values in the [0, 1] range. Variables not listed here will be binarized using thrX_default as usual. Default is NULL (all variables binarized). Variables listed here are never swept: they are used as they are. To sweep a variable that holds membership scores, leave it out of this argument; it is then binarized at the thresholds you supply (for example 0.3, 0.5, 0.7), like any other numeric variable.
dir.exp: Directional expectations for minimize. If NULL (default), no directional expectations are applied. To compute the intermediate solution, specify a numeric vector (1, 0, or -1 for each condition). Example: dir.exp = c(1, 1, 1) for three conditions all expected to contribute positively.
include: Inclusion rule for minimize. "" (default, QCA compatible) computes the complex solution without logical remainders. Use "?" to include logical remainders for parsimonious (with dir.exp = NULL) or intermediate solutions (with dir.exp specified).
incl.cut: Consistency cutoff for truthTable.
n.cut: Frequency cutoff for truthTable.
pri.cut: PRI cutoff for minimize.
extract_mode: Character. How to handle multiple solutions: "first" (default), "all", or "essential". See qca_extract for details.
return_details: Logical. If TRUE (default), returns both summary and detailed objects for use with generate_report().
Yvar: Deprecated. Use outcome instead.
Xvars: Deprecated. Use conditions instead.

Value

If return_details = FALSE, a data frame with columns:

threshold — swept threshold for sweep_var
expression — minimized solution expression
inclS — solution consistency
covS — solution coverage
(additional columns depending on extract_mode)

If return_details = TRUE, a list with:

summary — the data frame above
details — per-threshold list of threshold, thrX_vec, truth_table, solution

Note that return_details changes the type of the returned object, not just its contents: with TRUE the summary table is at result$summary, whereas with FALSE the summary table is the returned object and result$summary is NULL. Code intended to work under both settings should branch on inherits(result, "data.frame") (or simply always pass return_details = TRUE) rather than assuming result$summary exists.

Examples

# Load sample data
data(sample_data)

# === Three Types of QCA Solutions ===

# 1. Complex Solution (default, QCA compatible)
result_comp <- ctSweepS(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_var = "X3",
  sweep_range = 7,
  thrY = 7,
  thrX_default = 7
  # include = "" (default), dir.exp = NULL (default)
)
head(result_comp$summary)
#>   threshold                  expression   inclS      covS n_solutions
#> 1         7 ~X1*X3 + ~X2*X3 + X1*X2*~X3 0.90625 0.8787879           1

# 2. Parsimonious Solution (include = "?")
result_pars <- ctSweepS(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_var = "X3",
  sweep_range = 7,
  thrY = 7,
  thrX_default = 7,
  include = "?"  # Include logical remainders
)
head(result_pars$summary)
#>   threshold expression   inclS      covS n_solutions
#> 1         7 X3 + X1*X2 0.90625 0.8787879           1

# 3. Intermediate Solution (include = "?" + dir.exp)
result_int <- ctSweepS(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_var = "X3",
  sweep_range = 7,
  thrY = 7,
  thrX_default = 7,
  include = "?",
  dir.exp = c(1, 1, 1)  # All conditions expected positive
)
head(result_int$summary)
#>   threshold expression   inclS      covS n_solutions
#> 1         7 X3 + X1*X2 0.90625 0.8787879           1

# === Threshold Sweep Example ===

# Run single condition threshold sweep on X3 (complex solutions by default)
result <- ctSweepS(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_var = "X3",
  sweep_range = 6:8,
  thrY = 7,
  thrX_default = 7
)
head(result$summary)
#>   threshold                  expression   inclS      covS n_solutions
#> 1         6                       X1*X2 1.00000 0.3030303           1
#> 2         7 ~X1*X3 + ~X2*X3 + X1*X2*~X3 0.90625 0.8787879           1
#> 3         8 ~X1*X3 + ~X2*X3 + X1*X2*~X3 1.00000 0.8181818           1

# Run with negated outcome (~Y)
result_neg <- ctSweepS(
  dat = sample_data,
  outcome = "~Y",
  conditions = c("X1", "X2", "X3"),
  sweep_var = "X3",
  sweep_range = 6:8,
  thrY = 7,
  thrX_default = 7
)
head(result_neg$summary)
#>   threshold        expression     inclS      covS n_solutions
#> 1         6           ~X1*~X3 1.0000000 0.4893617           1
#> 2         7 ~X1*~X3 + ~X2*~X3 0.9166667 0.9361702           1
#> 3         8 ~X1*~X3 + ~X2*~X3 0.8867925 1.0000000           1