Package {ThSQCA}

ThSQCA: Threshold-Sweep QCA

Description

Provides threshold sweep methods for Qualitative Comparative Analysis (QCA). Implements Condition Threshold Sweep (CTS, for one or several conditions), Outcome Threshold Sweep (OTS), and Dual Threshold Sweep (DTS) for systematic exploration of threshold calibration effects on crisp-set QCA results. These methods extend traditional robustness approaches by treating threshold variation as an explicit analytical dimension and recording the sufficiency solution obtained at each threshold setting. Also provides Fiss (2011) doi:10.5465/amj.2011.60263120 core/peripheral condition classification via compute_fiss_core() and generate_fiss_chart(), enabling four-symbol configuration charts that distinguish core conditions (conditions of the parsimonious term contained in each configuration) from peripheral conditions (intermediate only). Built on top of the 'QCA' package by Dusa (2019) doi:10.1007/978-3-319-75668-4, with function arguments following 'QCA' conventions. Based on set-theoretic methods by Ragin (2008) doi:10.7208/chicago/9780226702797.001.0001 and established robustness protocols by Oana and Schneider (2024) doi:10.1177/00491241211036158. This package supersedes 'TSQCA'; see the NEWS file for migration guidance.

Author(s)

Maintainer: Yuki Toyoda yuki.toyoda.ds@hosei.ac.jp

Authors:

• Yuki Toyoda yuki.toyoda.ds@hosei.ac.jp

Other contributors:

• Japan Society for the Promotion of Science (KAKENHI Grant Number JP20K01998) [funder]

See Also

Useful links:

• https://github.com/im-research-yt/ThSQCA

• doi:10.5281/zenodo.17899390

• Report bugs at https://github.com/im-research-yt/ThSQCA/issues

Symbol sets for configuration charts

Description

Symbol sets for configuration charts

Usage

SYMBOL_SETS

Fiss-style symbol sets (4 symbols)

Description

Fiss-style symbol sets (4 symbols)

Usage

SYMBOL_SETS_FISS

Add metrics rows to markdown table

Description

Add metrics rows to markdown table

Usage

add_metrics_rows(table_str, metrics, labels)

Build condition-path matrix for configuration chart

Description

Build condition-path matrix for configuration chart

Usage

build_config_matrix(paths, conditions = NULL, symbols)

Arguments

Value

Matrix with conditions as rows, paths as columns

Build a Fiss-style configuration matrix (4-symbol)

Description

Build a Fiss-style configuration matrix (4-symbol)

Usage

build_fiss_matrix(interm_terms, classification, conditions, symbols, thr_label)

Arguments

Value

Character matrix with conditions as rows, terms as columns

Build configuration chart for a single solution

Description

Build configuration chart for a single solution

Usage

build_single_chart(
  paths,
  sol,
  symbols,
  labels,
  include_metrics,
  condition_order = NULL,
  solution_index = 1
)

Classify each condition of an intermediate term as core or peripheral

Description

The term is compared with each source parsimonious solution by nested_core_conditions(). When there are several source solutions (tied parsimonious solutions from which QCA derived the same intermediate solution), a condition is core only if it is core relative to every one of them. A condition whose polarity differs across the source solutions can therefore never be core (the safeguard introduced in version 2.0.5).

Usage

classify_term_fiss(interm_term, source_models, conditions)

Arguments

Value

Data frame with columns condition, status ("present", "absent", "dontcare") and type ("core", "peripheral", "dontcare"). Attribute "not_nested": integer indices of the source solutions that have no term contained in interm_term.

Collect and deduplicate the solution models attached to a QCA::minimize() result

Description

When dir.exp is specified and the minimization produces more than one prime implicant chart (QCA's own C1, C2, ... indexing, visible as "From C1P1, C2P1:" in print()), sol$i.sol contains one list entry per chart/path combination (e.g. C1P1, C2P1). Each entry's own $solution field is computed independently by QCA::minimize() (via its internal getSolution() call) and is NOT guaranteed to hold only that chart's own model: depending on the data, it may already enumerate the full, cross-chart set of tied minimal models. Concatenating every chart's $solution list (the previous approach used here and in generate_report()) therefore risks double- or N-fold counting the same model, inflating the reported number of solutions.

Usage

collect_unique_i_sol(sol)

Arguments

Details

This helper performs the same enumeration, then deduplicates by comparing each model's term set (order-independent), so structurally identical models are counted once regardless of which chart(s) produced them. This mirrors the manual "remove duplicate Boolean expressions" step that is standard practice when reporting multiple minimal solutions by hand.

Value

A list of unique solution term-vectors, or NULL if none were found.

Note

When dir.exp is specified, the true Intermediate solution is stored in sol$i.sol, not sol$solution (which contains the Parsimonious solution).

Compute Fiss Core/Peripheral Classification for Sweep Results

Description

Takes a threshold-sweep result produced by otSweep or ctSweepS and augments it with the Fiss (2011) core/peripheral classification of the intermediate solution. Results of ctSweepM and dtSweep are not supported yet and give an error.

Usage

compute_fiss_core(result, conditions = NULL)

Arguments

Details

The classification requires that:

• The sweep was run with include = "?" (to allow parsimonious computation)

• return_details = TRUE was used (truth tables must be stored)

• dir.exp was specified (i.e., the sweep produced intermediate solutions; core/peripheral is only meaningful when comparing parsimonious and intermediate solutions)

For each threshold in the result, this function:

1. Retrieves the intermediate solution already stored in result$details, and takes the model reported in the sweep summary (M1).

2. Identifies the parsimonious solution(s) from which QCA::minimize() derived that model. With dir.exp, QCA stores one entry in sol$i.sol for each pair of a complex solution and a parsimonious minimal solution (C1P1, C1P2, ...; see print(sol)), holding the parsimonious model in $p.sol and the intermediate model(s) obtained from it in $solution. Every entry that lists M1 is treated as a source.

3. Classifies each term (configuration) of M1: the conditions of the source parsimonious term(s) contained in that term are core; its other conditions are peripheral.

Value

The original result object with an additional $fiss_core slot: a named list keyed by threshold (character), each entry containing:

• parsim_expression — the parsimonious solution(s) M1 was compared with; several are shown with QCA's labels, e.g. "P1: ...; P2: ..."

• interm_expression — the intermediate solution classified (M1)

• parsim_n_solutions — number of tied parsimonious solutions on the truth table

• interm_n_solutions — number of intermediate minimal solutions

• parsim_sources — names of the i.sol entries M1 was derived from (e.g. "C1P1"), or NA when unavailable

• classification — data frame with columns term_idx, term_expr, condition, status, type

Relation to Fiss (2011)

Fiss (2011) defines core conditions as those that are part of both the parsimonious and the intermediate solution, and peripheral conditions as those that are eliminated in the parsimonious solution and therefore appear only in the intermediate solution. His solution tables apply this configuration by configuration: solutions are grouped by their core conditions, and the same condition can be core in one configuration and peripheral in another. This function follows that practice. A parsimonious term is contained in an intermediate term when every condition it specifies has the same status (present or absent) in the intermediate term; the core conditions of the intermediate term are the conditions of all parsimonious terms contained in it (one of the configurations in Fiss's high-performance table contains two parsimonious terms and has the core conditions of both).

Example: with the parsimonious solution ~A*E + A*B, the intermediate term ~A*~B*C*E contains ~A*E, so ~A and E are core and ~B and C are peripheral, even though B occurs in the other parsimonious term. Versions up to 2.0.7 compared each condition with the whole parsimonious solution and reported ~B as core here, which does not match how Fiss's tables are built.

Fiss (2011) does not discuss two situations, which this function handles conservatively and reports with a warning:

• Tied parsimonious solutions. If QCA derived M1 from a single parsimonious solution, that solution alone decides. If QCA derived the same M1 from several tied parsimonious solutions (the directional expectations do not single one out), a condition is core only if it is core relative to every one of them. For example, if M1 = SUP + TRU*PRC is derived both from TRU + SUP and from PRC + SUP, then TRU is core relative to the first and PRC relative to the second, so both are reported as peripheral. Fiss grounds coreness in the strength of the evidence; a condition whose status depends on which tied solution is chosen is not treated as strongly supported. To report core/peripheral status relative to one particular parsimonious solution, state that choice explicitly.

• No contained parsimonious term. An intermediate term can be covered by the parsimonious solution without containing any single parsimonious term (for example B*C*D*E with the parsimonious solution ~A*E + A*B). Its conditions are then all classified as peripheral.

Only M1 is classified. When the intermediate solution itself has several minimal models (see n_solutions in the sweep summary and interm_n_solutions below), the other models are not included in the classification or the chart. If the derivation cannot be read from the stored solution (no $i.sol or $p.sol), M1 is compared with every tied parsimonious solution.

References

Fiss, P. C. (2011). Building better causal theories: A fuzzy set approach to typologies in organization research. Academy of Management Journal, 54(2), 393-420.

See Also

generate_fiss_chart

Examples

## Not run: 
library(ThSQCA)
data(sample_data)

# Step 1: Run intermediate sweep (dir.exp required)
res <- otSweep(
  dat        = sample_data,
  outcome    = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 6:8,
  thrX       = c(X1 = 7, X2 = 7, X3 = 7),
  include    = "?",
  dir.exp    = c(1, 1, 1),
  return_details = TRUE
)

# Step 2: Augment with Fiss core/peripheral classification
res_fiss <- compute_fiss_core(res, conditions = c("X1", "X2", "X3"))

# Step 3: Generate Fiss-style chart
cat(generate_fiss_chart(res_fiss, symbol_set = "unicode"))

## End(Not run)

Generate configuration chart from paths (simple interface)

Description

A simpler interface for generating configuration charts when you have paths directly (without a full QCA solution object).

Usage

config_chart_from_paths(
  paths,
  symbol_set = c("unicode", "ascii", "latex"),
  language = c("en", "ja"),
  condition_order = NULL,
  n_sol = 1L,
  solution_note = TRUE,
  solution_note_style = c("simple", "detailed"),
  epi_list = NULL
)

Arguments

Value

Character string containing Markdown-formatted table.

Examples

# Simple usage with paths
paths <- c("A*B", "A*C*~D", "B*E")
chart <- config_chart_from_paths(paths)
cat(chart)

# With ASCII symbols
chart <- config_chart_from_paths(paths, symbol_set = "ascii")
cat(chart)

# With multiple solution note
chart <- config_chart_from_paths(paths, n_sol = 2)
cat(chart)

# With detailed note including EPIs
chart <- config_chart_from_paths(
  paths, n_sol = 2,
  solution_note_style = "detailed",
  epi_list = c("A*B")
)
cat(chart)

Generate configuration chart for multiple solutions (simple interface)

Description

Generates separate configuration charts for multiple solutions.

Usage

config_chart_multi_solutions(
  solutions,
  symbol_set = c("unicode", "ascii", "latex"),
  language = c("en", "ja"),
  condition_order = NULL,
  show_epi = FALSE
)

Arguments

Value

Character string containing Markdown-formatted tables.

Examples

# Multiple solutions
solutions <- list(
  c("A*B", "C"),
  c("A*B", "D"),
  c("A*C")
)
chart <- config_chart_multi_solutions(solutions)
cat(chart)

# With EPI identification
chart <- config_chart_multi_solutions(solutions, show_epi = TRUE)
cat(chart)

Convert configuration matrix to Markdown table

Description

Convert configuration matrix to Markdown table

Usage

config_matrix_to_md(mat, row_header = "Condition", center_align = TRUE)

Arguments

Value

Character string of Markdown table

CTS (multiple): Multi-condition threshold sweep

Description

Performs a grid search over thresholds of multiple X variables. For each combination of thresholds in sweep_list, the outcome Y and all X variables are binarized, and a crisp-set QCA is executed.

Usage

ctSweepM(
  dat,
  outcome = NULL,
  conditions = NULL,
  sweep_list,
  thrY,
  thrX_default = NULL,
  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

Value

If return_details = FALSE, a data frame with columns:

• combo_id — index of the threshold combination

• threshold — character string summarizing thresholds, e.g. "X1=6, X2=7, X3=7"

• 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-combination list of combo_id, 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 ===

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

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

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

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

# === Threshold Sweep Example ===

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

# Run multiple condition threshold sweep (complex solutions by default)
result_quick <- ctSweepM(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2"),
  sweep_list = sweep_list,
  thrY = 7
)
head(result_quick$summary)

# Run with negated outcome (~Y)
result_neg <- ctSweepM(
  dat = sample_data,
  outcome = "~Y",
  conditions = c("X1", "X2"),
  sweep_list = sweep_list,
  thrY = 7
)
head(result_neg$summary)


# Full multi-condition analysis (27 combinations)
sweep_list_full <- list(
  X1 = 6:8,
  X2 = 6:8,
  X3 = 6:8
)

result_full <- ctSweepM(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_list = sweep_list_full,
  thrY = 7
)
head(result_full$summary)

CTS (single): Single-condition threshold sweep

Description

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.

Usage

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

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)

# 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)

# 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 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)

# 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)

Convert data frame to Markdown table

Description

Convert data frame to Markdown table

Usage

df_to_md_table(df, digits = 3)

Arguments

Value

Character string of Markdown table.

DTS: 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
)

Arguments

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

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 ===

# 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)


# 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)

Escape special characters for Markdown

Description

Escapes asterisks and other special characters that have special meaning in Markdown syntax.

Usage

escape_md(text)

Arguments

Value

Character. Text with special characters escaped.

Extract all metrics from QCA solution object

Description

Safely extracts solution-level and term-level metrics from various QCA solution object structures. Handles cases where multiple solutions exist and sol.incl.cov may be NULL.

Usage

extract_all_metrics(IC, sol_obj = NULL)

Arguments

Value

List with elements:

• sol_inclS — solution consistency (or NA)

• sol_PRI — solution PRI (or NA)

• sol_covS — solution coverage (or NA)

• term_df — data frame of per-term metrics (or NULL)

Extract all unique conditions from paths

Description

Extract all unique conditions from paths

Usage

extract_conditions_from_paths(paths)

Arguments

Value

Character vector of unique condition names (without ~)

Extract per-path metrics for configuration chart

Description

Extract per-path metrics for configuration chart

Usage

extract_path_metrics_for_chart(sol, solution_index = 1)

Extract paths from a single solution

Description

Extract paths from a single solution

Usage

extract_paths_from_solution(solution)

Extract solution terms from a QCA solution object (intermediate or parsim)

Description

Extract solution terms from a QCA solution object (intermediate or parsim)

Usage

extract_sol_terms(sol)

Arguments

Value

Character vector of terms (prime implicants), or character(0)

Extract solution terms separately for each minimal solution

Description

Same sources as extract_sol_terms(), but the terms of each minimal solution (M1, M2, ...) are kept apart instead of being pooled. This is what the core/peripheral classification needs: pooling first makes a condition look as if it occurred with both polarities in "the" parsimonious solution, when in fact one minimal solution had it present and another had it absent.

Usage

extract_sol_terms_by_model(sol)

Arguments

Value

List of character vectors, one per minimal solution. Empty list when no solution is available.

Extract solution list from QCA object

Description

Extract solution list from QCA object

Usage

extract_solution_list(sol)

Note

When dir.exp is specified, the true Intermediate solution is stored in sol$i.sol, not sol$solution (which contains the Parsimonious solution).

Extract solution-level metrics for configuration chart

Description

Extract solution-level metrics for configuration chart

Usage

extract_solution_metrics_for_chart(sol, solution_index = 1)

Extract and format terms from solutions

Description

Extracts individual terms from solution expressions and returns formatted unique terms.

Usage

extract_terms(solutions, var_names, use_tilde = TRUE)

Arguments

Value

List with:

• all_terms — all terms (with duplicates)

• unique_terms — unique terms

• n_total — total term count

• n_unique — unique term count

Examples

var_names <- c("X1", "X2", "X3")
solutions <- c("X1*X2 + X3", "X1*X2 + X1*X3")
extract_terms(solutions, var_names)

Label for one threshold setting in Fiss charts and summaries

Description

Label for one threshold setting in Fiss charts and summaries

Usage

fiss_threshold_label(result, thr_key, sep = "=")

Arguments

Value

"X3=6" for a ctSweepS() result sweeping X3, otherwise "thrY=6".

Format one or more parsimonious models as a display expression

Description

Format one or more parsimonious models as a display expression

Usage

format_models_expr(models, labels = NULL)

Arguments

Value

"A + B" for one model, "P1: A + B; P2: C + B" for several, "No solution" for none.

Format a QCA solution expression

Description

Formats a complete solution expression (multiple terms joined by +).

Usage

format_qca_solution(solution, var_names, use_tilde = TRUE)

Arguments

Value

Character. The formatted solution expression.

Examples

var_names <- c("KSP", "KPR", "PRD", "RVT", "RCM")
format_qca_solution("KSPRVT + ~KPRPRD + RCM", var_names)
# Returns: "KSP*RVT + ~KPR*PRD + RCM"

Format multiple QCA solutions

Description

Formats a vector of solution expressions.

Usage

format_qca_solutions(solutions, var_names, use_tilde = TRUE)

Arguments

Value

Character vector. Formatted solution expressions.

Examples

var_names <- c("KSP", "KPR", "PRD", "RVT", "RCM")
solutions <- c("KSPRVT + RCM", "~KPRPRD")
format_qca_solutions(solutions, var_names)

Format a single QCA term

Description

Inserts * between variables in a term where it may have been omitted.

Usage

format_qca_term(term, var_names, use_tilde = TRUE)

Arguments

Value

Character. The formatted term with * between all variables.

Examples

var_names <- c("KSP", "KPR", "PRD", "RVT", "RCM")
format_qca_term("KSPRVTRCM", var_names)
# Returns: "KSP*RVT*RCM"

format_qca_term("~KPRPRD", var_names)
# Returns: "~KPR*PRD"

Generate Configuration Chart from QCA Solution

Description

Creates a Markdown-formatted configuration chart (Fiss-style table) from QCA minimization results. Supports single solution with multiple paths, and multiple solutions (displayed as separate tables).

Usage

generate_config_chart(
  sol,
  symbol_set = c("unicode", "ascii", "latex"),
  include_metrics = TRUE,
  language = c("en", "ja"),
  condition_order = NULL
)

Arguments

Value

Character string containing Markdown-formatted table(s).

Examples

## Not run: 
# After running QCA::minimize()
library(QCA)
tt <- truthTable(data, outcome = "Y", conditions = c("A", "B", "C"))
sol <- minimize(tt, include = "?", details = TRUE)

# Generate configuration chart
chart <- generate_config_chart(sol)
cat(chart)

# For LaTeX/PDF output (e.g., rticles)
chart <- generate_config_chart(sol, symbol_set = "latex")

# ASCII for maximum compatibility
chart <- generate_config_chart(sol, symbol_set = "ascii")

# Japanese labels
chart <- generate_config_chart(sol, language = "ja")

## End(Not run)

Generate cross-threshold configuration chart from sweep results

Description

Creates a configuration chart from threshold sweep results. Supports two levels of aggregation: solution-term level (Fiss-style, default) and threshold-level summary.

Usage

generate_cross_threshold_chart(
  result,
  conditions = NULL,
  symbol_set = c("unicode", "ascii", "latex"),
  chart_level = c("term", "summary"),
  language = c("en", "ja")
)

Arguments

Value

Character string containing Markdown-formatted table.

Examples

## Not run: 
data(sample_data)
result <- otSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 6:8,
  thrX = c(X1 = 7, X2 = 7, X3 = 7)
)

# Solution-term level, Fiss-style (default)
chart <- generate_cross_threshold_chart(result, c("X1", "X2", "X3"))
cat(chart)

# Threshold-level summary
chart <- generate_cross_threshold_chart(result, c("X1", "X2", "X3"),
                                         chart_level = "summary")
cat(chart)

## End(Not run)

Generate Fiss-Style Configuration Chart from Sweep Results

Description

Produces a Markdown-formatted configuration chart following Fiss (2011), using four symbols to distinguish core conditions (conditions of the parsimonious term contained in each configuration) from peripheral conditions (present in the intermediate solution only).

Usage

generate_fiss_chart(
  result,
  conditions = NULL,
  symbol_set = c("unicode", "ascii", "latex"),
  language = c("en", "ja")
)

Arguments

Details

Call compute_fiss_core first to augment the sweep result.

Value

Character string: Markdown-formatted Fiss configuration chart.

References

Fiss, P. C. (2011). Building better causal theories: A fuzzy set approach to typologies in organization research. Academy of Management Journal, 54(2), 393-420.

See Also

compute_fiss_core

Examples

## Not run: 
data(sample_data)
res <- otSweep(
  dat = sample_data, outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 6:8,
  thrX = c(X1 = 7, X2 = 7, X3 = 7),
  include = "?", dir.exp = c(1, 1, 1),
  return_details = TRUE
)
res_fiss <- compute_fiss_core(res, conditions = c("X1", "X2", "X3"))
cat(generate_fiss_chart(res_fiss))
cat(generate_fiss_chart(res_fiss, symbol_set = "latex"))
cat(generate_fiss_chart(res_fiss, language = "ja"))

## End(Not run)

Generate Markdown Report for QCA Analysis

Description

Creates a markdown report from QCA analysis results. Supports two formats: "full" (comprehensive) and "simple" (for manuscripts).

Usage

generate_report(
  result,
  output_file = "qca_report.md",
  format = c("full", "simple"),
  title = "QCA Analysis Report",
  dat = NULL,
  desc_vars = NULL,
  include_chart = TRUE,
  chart_symbol_set = c("unicode", "ascii", "latex"),
  chart_level = c("term", "summary"),
  solution_note = TRUE,
  solution_note_style = c("simple", "detailed"),
  solution_note_lang = c("en", "ja"),
  include_fiss_core = FALSE,
  include_raw_output = TRUE
)

Arguments

Value

Invisibly returns the path to the generated report.

Examples

## Not run: 
data(sample_data)
thrX <- c(X1 = 7, X2 = 7, X3 = 7)

result <- otSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 6:8,
  thrX = thrX,
  return_details = TRUE
)

# With descriptive statistics and configuration charts
generate_report(result, "my_report.md", format = "full", 
                dat = sample_data, include_chart = TRUE)

# Without configuration charts
generate_report(result, "my_report.md", format = "simple",
                include_chart = FALSE)

# With Fiss-style term-level charts (default, recommended for publications)
generate_report(result, "my_report.md", format = "full")

# With threshold-level summary charts
generate_report(result, "my_report.md", format = "full",
                chart_level = "summary")

# With Fiss core/peripheral chart (requires compute_fiss_core)
res_fiss <- compute_fiss_core(result, conditions = c("X1", "X2", "X3"))
generate_report(res_fiss, "my_report.md", format = "full",
                include_fiss_core = TRUE)

## End(Not run)

Generate solution note for multiple solutions

Description

Creates a note explaining that multiple equivalent solutions exist and that the displayed configuration is based on M1.

Usage

generate_solution_note(
  n_sol,
  epi_list = NULL,
  style = c("simple", "detailed"),
  language = c("en", "ja"),
  format = c("markdown", "latex")
)

Arguments

Value

Character string of the note, or empty string if n_sol <= 1.

Examples

# Simple note
generate_solution_note(2, style = "simple")

# Detailed note with EPIs
generate_solution_note(3, epi_list = c("A*B", "C"), style = "detailed")

# Japanese
generate_solution_note(2, style = "simple", language = "ja")

Generate solution-term level chart (Fiss-style)

Description

Creates a configuration chart where each column represents a single prime implicant (configuration), following Fiss (2011) notation.

Usage

generate_term_level_chart(sum_df, conditions, symbols, language = "en")

Arguments

Value

Character string containing Markdown-formatted table.

Generate threshold-level summary chart

Description

Creates a configuration chart where each column represents one threshold, showing all conditions that appear in any configuration at that threshold.

Usage

generate_threshold_level_chart(sum_df, conditions, symbols, language = "en")

Arguments

Value

Character string containing Markdown-formatted table.

Get all unique terms from multiple solutions

Description

Get all unique terms from multiple solutions

Usage

get_all_terms(sol_list)

Arguments

Value

List with:

• all_terms — all terms (with duplicates)

• unique_terms — unique terms

• term_counts — table of term frequencies

Determine condition status in a term

Description

Checks whether a condition is present, absent (negated), or don't care in a given term.

Usage

get_condition_status(term, condition)

Arguments

Details

Uses word boundary matching to avoid false positives when condition names are substrings of each other (e.g., X1 vs X10).

Value

Character. One of "present", "absent", or "dontcare".

Get labels for configuration chart based on language

Description

Get labels for configuration chart based on language

Usage

get_config_labels(language)

Get the number of intermediate solutions

Description

Get the number of intermediate solutions

Usage

get_n_solutions(sol)

Arguments

Value

Integer. Number of intermediate solutions, or 0 if none.

Note

When dir.exp is specified, the true Intermediate solution is stored in sol$i.sol, not sol$solution (which contains the Parsimonious solution). See collect_unique_i_sol for why deduplication is required when multiple prime implicant charts are present.

Identify Essential Prime Implicants from multiple solutions

Description

Finds terms that appear in ALL solutions (EPIs) versus terms that appear in only some solutions (SPIs).

Usage

identify_epi(solutions)

Arguments

Value

List with:

• epi — Essential prime implicants (in all solutions)

• spi — Selective prime implicants (in some solutions)

• n_solutions — Number of solutions

Examples

solutions <- list(
  c("A*B", "C", "D"),
  c("A*B", "C", "E"),
  c("A*B", "C", "F")
)
result <- identify_epi(solutions)
# result$epi = c("A*B", "C")
# result$spi = c("D", "E", "F")

Order-independent key for a model (set of terms)

Description

Order-independent key for a model (set of terms)

Usage

model_key(terms)

Arguments

Value

Single character string.

Core conditions of one intermediate term relative to one parsimonious model

Description

Implements the configuration-level reading of Fiss (2011): the core conditions of an intermediate configuration are the conditions of the parsimonious term(s) contained in it. A parsimonious term is contained (nested) in the intermediate term when every condition it specifies has the same status (present or absent) in the intermediate term. When several parsimonious terms are contained in it, their conditions are pooled, as in solution 2 of Fiss (2011, Table 4).

Usage

nested_core_conditions(interm_term, parsim_model, conditions)

Arguments

Value

List with core (character, condition names classified as core) and nested (logical, whether any parsimonious term is contained in the intermediate term).

OTS: Outcome threshold sweep

Description

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

Usage

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

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)

# 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)

# 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)

# === 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)

# 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)

Parse a single path/term into conditions

Description

Parse a single path/term into conditions

Usage

parse_path_conditions(path)

Arguments

Value

List with 'present' and 'absent' condition names

Parse solution expression into individual terms

Description

Splits a solution expression (ORed terms) into individual prime implicants.

Usage

parse_solution_terms(expr)

Arguments

Value

Character vector of terms (e.g., c("X3", "X1*X2")), or NULL if no valid expression.

Prepare analysis data frame for QCA::truthTable()

Description

Constructs the data frame to be passed to QCA::truthTable(). For pre-calibrated variables, the original values are passed through without binarization. For all other variables, qca_bin() is applied.

Usage

prepare_dat_bin(
  dat,
  outcome_clean,
  conditions,
  thrY,
  thrX_vec,
  pre_calibrated = NULL
)

Arguments

Value

Data frame with column Y (binarized outcome) and condition columns (binarized or passed through).

Print method for ThSQCA results

Description

Displays a concise overview of ThSQCA analysis results.

Usage

## S3 method for class 'tsqca_result'
print(x, ...)

## S3 method for class 'otSweep_result'
print(x, ...)

## S3 method for class 'dtSweep_result'
print(x, ...)

## S3 method for class 'ctSweepS_result'
print(x, ...)

## S3 method for class 'ctSweepM_result'
print(x, ...)

Arguments

Value

Invisibly returns x.

Examples

data(sample_data)
result <- otSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 6:8,
  thrX = c(X1 = 7, X2 = 7, X3 = 7)
)
print(result)

Print Fiss core/peripheral summary for a single threshold

Description

Displays which conditions are core and which are peripheral at a given threshold, in a human-readable format.

Usage

print_fiss_summary(result, thr_key = NULL, language = c("en", "ja"))

Arguments

Value

Invisibly returns the classification data frame for thr_key.

Examples

## Not run: 
res_fiss <- compute_fiss_core(res)
print_fiss_summary(res_fiss, thr_key = "7")

## End(Not run)

Binary calibration helper for ThSQCA

Description

Converts a numeric vector into a crisp set (0/1) based on a threshold.

Usage

qca_bin(x, thr)

Arguments

Value

Integer vector of 0/1 with the same length as x.

Extract solution information from a QCA minimization result

Description

Internal helper to obtain the solution expression, consistency (inclS) and coverage (covS) from an object returned by QCA::minimize().

Usage

qca_extract(sol, extract_mode = c("first", "all", "essential"))

Arguments

Value

A list with elements depending on extract_mode.

For "first": expression, inclS, covS.

For "all": adds n_solutions.

For "essential": adds selective_terms, unique_terms, n_solutions.

If extraction fails, returns "No solution" and NA_real_ for numeric values.

Run parsimonious QCA minimization on a stored truth table

Description

Run parsimonious QCA minimization on a stored truth table

Usage

run_parsimonious(truth_table, conditions)

Arguments

Value

QCA solution object, or NULL on error / no solution

Sample dataset for ThSQCA examples

Description

A small artificial dataset with variables:

Y

Outcome (numeric)

X1

Condition 1

X2

Condition 2

X3

Condition 3

Usage

sample_data

Format

A data frame with 80 rows and 4 variables.

Sanitize a truth table before Boolean minimization

Description

Guards against two behaviors of QCA::truthTable() (observed with QCA 3.25 / admisc 0.40) that can affect programmatic, repeated calls such as threshold sweeps. For sparse truth tables the incl/PRI columns may be returned as character rather than numeric, and logical-remainder rows (observed n = 0) may carry the string "-". Passing such a truth table to QCA::minimize() can, for some truth table structures, cause the minimization to hang or return misleading fit values. This helper coerces incl/PRI to numeric and sets the remainder rows to 0.

Usage

sanitize_truthtable(tt)

Arguments

Details

The OUT column is deliberately left untouched: minimize() uses OUT (with the symbolic "?" for remainders) to identify positive, negative, and remainder rows, so setting incl/PRI to 0 on remainder rows does not alter remainder handling.

Value

The same object with numeric incl/PRI columns and no NA in those columns. Returns the input unchanged if it is NULL or lacks a $tt data frame.

Split solution expression into terms

Description

Split solution expression into terms

Usage

split_solution_terms(solution)

Arguments

Value

Character vector of terms.

Summary method for ThSQCA results

Description

Displays detailed results table with solution formulas and fit measures.

Usage

## S3 method for class 'tsqca_result'
summary(object, ...)

## S3 method for class 'otSweep_result'
summary(object, ...)

## S3 method for class 'dtSweep_result'
summary(object, ...)

## S3 method for class 'ctSweepS_result'
summary(object, ...)

## S3 method for class 'ctSweepM_result'
summary(object, ...)

Arguments

Value

Invisibly returns object.

Examples

data(sample_data)
result <- otSweep(
  dat = sample_data,
  outcome = "Y",
  conditions = c("X1", "X2", "X3"),
  sweep_range = 6:8,
  thrX = c(X1 = 7, X2 = 7, X3 = 7)
)
summary(result)

Condition statuses of a single term

Description

Condition statuses of a single term

Usage

term_status(term, conditions)

Arguments

Value

Named character vector: "present", "absent" or "dontcare" for each condition.

Trace the reported intermediate model back to its parsimonious source(s)

Description

With include = "?" and dir.exp, QCA::minimize() stores one entry in sol$i.sol for each pair of a complex solution (C1, C2, ...) and a parsimonious minimal solution (P1, P2, ...), named C1P1, C1P2, and so on. Each entry holds that parsimonious model in $p.sol and the intermediate model(s) obtained from it in $solution.

Usage

trace_intermediate_sources(sol)

Arguments

Details

This helper picks the intermediate model that ThSQCA reports as M1 (the first model of i.sol$C1P1, else of the first entry, exactly as in qca_extract()), and returns every i.sol entry whose $solution contains that same model, together with those entries' parsimonious models. The core/peripheral comparison is then made against these source models only, not against tied parsimonious solutions from which the reported intermediate model was not obtained.

print(sol) groups entries whose $solution lists are identical ("From C1P1, C1P2:"). This helper instead keeps every entry that lists M1 among its models, including entries that also list other tied intermediate models. The set of sources is therefore the same as or larger than the printed grouping, which can only make the classification more conservative.

Value

NULL when sol$i.sol is missing, empty, or lacks $p.sol for a source entry (callers then fall back to recomputing the parsimonious solution). Otherwise a list with interm_terms (character), sources (character, entry names), parsim_models (list of character vectors, deduplicated), and parsim_labels (character, the P part of the first entry name for each model, e.g. "P2").

Validate the pre_calibrated parameter

Description

Checks that all names in pre_calibrated exist in conditions and that the corresponding values in dat are within the [0, 1] range required for fuzzy membership scores. Values of exactly 0.5 trigger a single warning naming the variable and the number of cases.

Usage

validate_pre_calibrated(pre_calibrated, conditions, dat)

Arguments

Value

Invisible NULL. Raises errors or warnings as needed.

Write full report content

Description

Write full report content

Usage

write_full_report(
  result,
  con,
  dat = NULL,
  desc_vars = NULL,
  include_chart = TRUE,
  chart_symbol_set = "unicode",
  chart_level = "term",
  solution_note = TRUE,
  solution_note_style = "simple",
  solution_note_lang = "en",
  include_raw_output = TRUE,
  use_fiss = FALSE
)

Write simple report content

Description

Write simple report content

Usage

write_simple_report(
  result,
  con,
  include_chart = TRUE,
  chart_symbol_set = "unicode",
  chart_level = "term",
  solution_note = TRUE,
  solution_note_style = "simple",
  solution_note_lang = "en",
  include_raw_output = TRUE,
  use_fiss = FALSE
)