TSQCA (version 1.3.1)

dtSweep: DTS–QCA: Two-dimensional X–Y threshold sweep

Description

Sweeps thresholds for multiple X variables and the outcome Y jointly. For each combination of X thresholds and each candidate Y threshold, the data are binarized and a crisp-set QCA is executed.

Usage

dtSweep(
  dat,
  outcome = NULL,
  conditions = NULL,
  sweep_list_X,
  sweep_range_Y,
  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
)

Value

If return_details = FALSE, a data frame with columns:

• combo_id — index of threshold combination

• thrY — threshold for Y

• thrX — character summary of X thresholds

• 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 — list of runs with combo_id, thrY, thrX_vec, truth_table, solution

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_list_X

Named list. Each element is a numeric vector of candidate thresholds for the corresponding X. Variables listed in pre_calibrated do not need a sweep_list_X entry.

sweep_range_Y

Numeric vector. Candidate thresholds for Y.

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 sweep_list_X thresholds as usual. Default is NULL (all variables binarized). It is recommended to sweep variables on their original (raw) scale rather than as pre-calibrated fuzzy values, because raw-scale thresholds are easier to interpret substantively.

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.

Examples

# Load sample data
data(sample_data)

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

# Quick demonstration with 2 conditions
sweep_list_X <- list(X1 = 7, X2 = 7)
sweep_range_Y <- 7

# 1. Complex Solution (default, QCA compatible)
result_comp <- dtSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2"),
  sweep_list_X = sweep_list_X,
  sweep_range_Y = sweep_range_Y
  # include = "" (default), dir.exp = NULL (default)
)
head(result_comp$summary)

# 2. Parsimonious Solution (include = "?")
result_pars <- dtSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2"),
  sweep_list_X = sweep_list_X,
  sweep_range_Y = sweep_range_Y,
  include = "?"  # Include logical remainders
)
head(result_pars$summary)

# 3. Intermediate Solution (include = "?" + dir.exp)
result_int <- dtSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2"),
  sweep_list_X = sweep_list_X,
  sweep_range_Y = sweep_range_Y,
  include = "?",
  dir.exp = c(1, 1)  # Positive expectations
)
head(result_int$summary)

# === Threshold Sweep Example ===

# Using 2 conditions and 2 threshold levels
sweep_list_X <- list(
  X1 = 6:7,
  X2 = 6:7
)
sweep_range_Y <- 6:7

# Run dual threshold sweep (complex solutions by default)
result_quick <- dtSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2"),
  sweep_list_X = sweep_list_X,
  sweep_range_Y = sweep_range_Y
)
head(result_quick$summary)

# \donttest{
# Full analysis with 3 conditions (81 combinations)
sweep_list_X_full <- list(
  X1 = 6:8,
  X2 = 6:8,
  X3 = 6:8
)
sweep_range_Y_full <- 6:8

result_full <- dtSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_list_X = sweep_list_X_full,
  sweep_range_Y = sweep_range_Y_full
)
head(result_full$summary)
# }