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.
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
)Data frame containing the outcome and condition variables.
Character. Outcome variable name. Supports negation with
tilde prefix (e.g., "~Y") following QCA package conventions.
Character vector. Names of condition variables.
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.
Numeric vector. Candidate thresholds for Y.
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).
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.
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.
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).
Consistency cutoff for truthTable.
Frequency cutoff for truthTable.
PRI cutoff for minimize.
Character. How to handle multiple solutions:
"first" (default), "all", or "essential".
See qca_extract for details.
Logical. If TRUE (default), returns both
summary and detailed objects for use with generate_report().
Deprecated. Use outcome instead.
Deprecated. Use conditions instead.
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
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.
# 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)
#> combo_id thrY thrX expression inclS covS n_solutions
#> 1 1 7 X1=7, X2=7 X1*X2 1 0.3030303 1
# 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)
#> combo_id thrY thrX expression inclS covS n_solutions
#> 1 1 7 X1=7, X2=7 X1*X2 1 0.3030303 1
# 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)
#> combo_id thrY thrX expression inclS covS n_solutions
#> 1 1 7 X1=7, X2=7 X1*X2 1 0.3030303 1
# === 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)
#> combo_id thrY thrX expression inclS covS n_solutions
#> 1 1 6 X1=6, X2=6 X1*X2 0.8333333 0.4411765 1
#> 2 1 7 X1=6, X2=6 X1*X2 0.8333333 0.4545455 1
#> 3 2 6 X1=7, X2=6 X1*X2 1.0000000 0.3823529 1
#> 4 2 7 X1=7, X2=6 X1*X2 1.0000000 0.3939394 1
#> 5 3 6 X1=6, X2=7 No solution NA NA 0
#> 6 3 7 X1=6, X2=7 No solution NA NA 0
# \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)
#> combo_id thrY thrX expression inclS covS n_solutions
#> 1 1 6 X1=6, X2=6, X3=6 X1*X2 0.8333333 0.4411765 1
#> 2 1 7 X1=6, X2=6, X3=6 X1*X2 0.8333333 0.4545455 1
#> 3 1 8 X1=6, X2=6, X3=6 No solution NA NA 0
#> 4 2 6 X1=7, X2=6, X3=6 X1*X2 1.0000000 0.3823529 1
#> 5 2 7 X1=7, X2=6, X3=6 X1*X2 1.0000000 0.3939394 1
#> 6 2 8 X1=7, X2=6, X3=6 No solution NA NA 0
# }