OTS: Outcome threshold sweep — otSweep • ThSQCA

Sweeps the threshold of the outcome Y while keeping the thresholds of all X conditions fixed.

otSweep(
  dat,
  outcome = NULL,
  conditions = NULL,
  sweep_range,
  thrX,
  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_range: Numeric vector. Candidate thresholds for Y.
thrX: Named numeric vector. Fixed thresholds for X variables. Names must match the conditions that require binarization. Variables listed in pre_calibrated do not need a thrX entry.
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 thresholds 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:

thrY — threshold for Y
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-Y-threshold list of thrY, 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)

# Set fixed thresholds for conditions
thrX <- c(X1 = 7, X2 = 7, X3 = 7)

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

# 1. Complex Solution (default, QCA compatible)
#    Does not use logical remainders (most conservative)
result_comp <- otSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 7,
  thrX = thrX
  # include = "" (default), dir.exp = NULL (default)
)
head(result_comp$summary)
#>   thrY                  expression   inclS      covS n_solutions
#> 1    7 ~X1*X3 + ~X2*X3 + X1*X2*~X3 0.90625 0.8787879           1

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

# 3. Intermediate Solution (include = "?" + dir.exp)
#    Uses logical remainders with directional expectations
result_int <- otSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 7,
  thrX = thrX,
  include = "?",
  dir.exp = c(1, 1, 1)  # All conditions expected positive
)
head(result_int$summary)
#>   thrY expression   inclS      covS n_solutions
#> 1    7 X3 + X1*X2 0.90625 0.8787879           1

# === Threshold Sweep Example ===

# Sweep with complex solutions (default)
result_sweep <- otSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 6:8,
  thrX = thrX
)
head(result_sweep$summary)
#>   thrY                  expression   inclS      covS n_solutions
#> 1    6 ~X1*X3 + ~X2*X3 + X1*X2*~X3 0.90625 0.8529412           1
#> 2    7 ~X1*X3 + ~X2*X3 + X1*X2*~X3 0.90625 0.8787879           1
#> 3    8                 No solution      NA        NA           0

# Run with negated outcome (~Y)
# Analyzes conditions for Y < threshold
result_neg <- otSweep(
  dat = sample_data,
  outcome = "~Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 6:8,
  thrX = thrX
)
head(result_neg$summary)
#>   thrY        expression     inclS      covS n_solutions
#> 1    6 ~X1*~X3 + ~X2*~X3 0.8958333 0.9347826           1
#> 2    7 ~X1*~X3 + ~X2*~X3 0.9166667 0.9361702           1
#> 3    8 ~X1*~X3 + ~X2*~X3 0.9791667 0.7833333           1