| Type: | Package |
| Title: | Threshold Sweep Extensions for Qualitative Comparative Analysis |
| Version: | 1.0.0 |
| Description: | Provides threshold sweep methods for Qualitative Comparative Analysis (QCA). Implements Condition Threshold Sweep-Single (CTS-S), Condition Threshold Sweep-Multiple (CTS-M), 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 exploratory tool for discovering causal structures. 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 Rubinson et al. (2019) <doi:10.1177/00491241211036158>. |
| Depends: | R (≥ 4.0) |
| Imports: | QCA |
| Suggests: | knitr, rmarkdown, testthat (≥ 3.0.0) |
| VignetteBuilder: | knitr |
| License: | MIT + file LICENSE |
| URL: | https://github.com/im-research-yt/TSQCA, https://doi.org/10.5281/zenodo.17899390 |
| BugReports: | https://github.com/im-research-yt/TSQCA/issues |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.3.3 |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2026-01-07 10:15:14 UTC; yukit |
| Author: | Yuki Toyoda [aut, cre], Japan Society for the Promotion of Science [fnd] (KAKENHI Grant Number JP20K01998) |
| Maintainer: | Yuki Toyoda <yuki.toyoda.ds@hosei.ac.jp> |
| Repository: | CRAN |
| Date/Publication: | 2026-01-08 00:40:14 UTC |
TSQCA: Threshold Sweep Extensions for Qualitative Comparative Analysis
Description
Provides threshold sweep methods for Qualitative Comparative Analysis (QCA). Implements Condition Threshold Sweep-Single (CTS-S), Condition Threshold Sweep-Multiple (CTS-M), 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 exploratory tool for discovering causal structures. 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 Rubinson et al. (2019) doi:10.1177/00491241211036158.
Author(s)
Maintainer: 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:
Report bugs at https://github.com/im-research-yt/TSQCA/issues
Symbol sets for configuration charts
Description
Symbol sets for configuration charts
Usage
SYMBOL_SETS
Format
An object of class list of length 3.
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
paths |
Character vector of paths |
conditions |
Character vector of condition names (optional) |
symbols |
List with 'present' and 'absent' symbols |
Value
Matrix with conditions as rows, paths 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
)
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
paths |
Character vector. Paths in QCA notation (e.g., "AB~C"). |
symbol_set |
Character. One of |
language |
Character. |
condition_order |
Character vector. Optional ordering of conditions. |
n_sol |
Integer. Number of equivalent solutions. If > 1, a note is added explaining that multiple solutions exist and M1 is shown. Default is 1. |
solution_note |
Logical. Whether to add solution note when n_sol > 1. Default is TRUE. |
solution_note_style |
Character. |
epi_list |
Character vector. Essential prime implicants for detailed notes.
Only used when |
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
solutions |
List of character vectors. Each element is a vector of paths for one solution. |
symbol_set |
Character. One of |
language |
Character. |
condition_order |
Character vector. Optional ordering of conditions. |
show_epi |
Logical. Whether to identify and display Essential Prime Implicants (EPIs) in the note. Default is FALSE. |
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
mat |
Matrix with rownames and colnames |
row_header |
Character. Header for the row names column |
center_align |
Logical. Whether to center-align columns |
Value
Character string of Markdown table
MCTS–QCA: 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,
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., |
conditions |
Character vector. Names of condition variables. |
sweep_list |
Named list. Each element is a numeric vector of
candidate thresholds for the corresponding X. Names must match
|
thrY |
Numeric. Threshold for Y (fixed). |
dir.exp |
Directional expectations for |
include |
Inclusion rule for |
incl.cut |
Consistency cutoff for |
n.cut |
Frequency cutoff for |
pri.cut |
PRI cutoff for |
extract_mode |
Character. How to handle multiple solutions:
|
return_details |
Logical. If |
Yvar |
Deprecated. Use |
Xvars |
Deprecated. Use |
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 ofcombo_id,thrX_vec,truth_table,solution
Examples
# Load sample data
data(sample_data)
# Quick demonstration with 2 conditions (< 5 seconds)
# This explores 2^2 = 4 threshold combinations
sweep_list <- list(
X1 = 6:7, # Reduced from 6:8 to 6:7
X2 = 6:7 # Reduced from 6:8 to 6:7
)
# Run multiple condition threshold sweep with reduced parameters (standard)
result_quick <- ctSweepM(
dat = sample_data,
outcome = "Y",
conditions = c("X1", "X2"), # Reduced from 3 to 2 conditions
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 with 3 conditions
# This explores 3^3 = 27 threshold combinations (takes ~5-8 seconds)
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
)
# Visualize threshold-dependent solution paths
head(result_full$summary)
CTS–QCA: 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,
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., |
conditions |
Character vector. Names of condition variables. |
sweep_var |
Character. Name of the condition to be swept.
Must be one of |
sweep_range |
Numeric vector. Candidate thresholds for |
thrY |
Numeric. Threshold for Y (fixed). |
thrX_default |
Numeric. Default threshold for non-swept X variables. |
dir.exp |
Optional named numeric vector of directional expectations
for |
include |
Inclusion rule for |
incl.cut |
Consistency cutoff for |
n.cut |
Frequency cutoff for |
pri.cut |
PRI cutoff for |
extract_mode |
Character. How to handle multiple solutions:
|
return_details |
Logical. If |
Yvar |
Deprecated. Use |
Xvars |
Deprecated. Use |
Value
If return_details = FALSE, a data frame with columns:
-
threshold— swept threshold forsweep_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 ofthreshold,thrX_vec,truth_table,solution
Examples
# Load sample data
data(sample_data)
# Run single condition threshold sweep on X3 (standard)
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
df |
Data frame to convert. |
digits |
Number of decimal places for numeric columns. |
Value
Character string of Markdown table.
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,
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., |
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. |
sweep_range_Y |
Numeric vector. Candidate thresholds for Y. |
dir.exp |
Directional expectations for |
include |
Inclusion rule for |
incl.cut |
Consistency cutoff for |
n.cut |
Frequency cutoff for |
pri.cut |
PRI cutoff for |
extract_mode |
Character. How to handle multiple solutions:
|
return_details |
Logical. If |
Yvar |
Deprecated. Use |
Xvars |
Deprecated. Use |
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 withcombo_id,thrY,thrX_vec,truth_table,solution
Examples
# Load sample data
data(sample_data)
# Quick demonstration with reduced complexity (< 5 seconds)
# Using 2 conditions and 2 threshold levels
sweep_list_X <- list(
X1 = 6:7, # Reduced from 6:8 to 6:7
X2 = 6:7 # Reduced from 6:8 to 6:7
)
sweep_range_Y <- 6:7 # Reduced from 6:8 to 6:7
# Run dual threshold sweep with reduced parameters
# This explores 2 × 2^2 = 8 threshold combinations
result_quick <- dtSweep(
dat = sample_data,
outcome = "Y",
conditions = c("X1", "X2"), # Reduced from 3 to 2 conditions
sweep_list_X = sweep_list_X,
sweep_range_Y = sweep_range_Y
)
head(result_quick$summary)
# Full analysis with all conditions and thresholds
# This explores 3 × 3^3 = 81 threshold combinations (takes ~10-15 seconds)
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
)
# Analyze threshold-dependent causal structures
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
text |
Character. Text to escape. |
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
IC |
IC object from QCA solution. |
sol_obj |
Full solution object (optional, for fallback). |
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
paths |
Character vector of paths |
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 list from QCA object
Description
Extract solution list from QCA object
Usage
extract_solution_list(sol)
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
solutions |
Character vector. Solution expressions. |
var_names |
Character vector. Variable names used in the analysis. |
use_tilde |
Logical. If TRUE, negation is represented as |
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)
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
solution |
Character. A solution expression (e.g., "KSPRVT + ~KPRPRD"). |
var_names |
Character vector. Variable names used in the analysis. |
use_tilde |
Logical. If TRUE, negation is represented as |
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
solutions |
Character vector. Solution expressions from |
var_names |
Character vector. Variable names used in the analysis. |
use_tilde |
Logical. If TRUE, negation is represented as |
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
term |
Character. A single term (e.g., "KSPRVT" or "~KPR*PRD"). |
var_names |
Character vector. Variable names used in the analysis. |
use_tilde |
Logical. If TRUE, negation is represented as |
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
sol |
A solution object returned by |
symbol_set |
Character. One of |
include_metrics |
Logical. Whether to include consistency/coverage metrics in the table. Default is TRUE. |
language |
Character. |
condition_order |
Character vector. Optional ordering of conditions in the table rows. If NULL, conditions are ordered as they appear in paths. |
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
result |
A result object from any Sweep function (otSweep, ctSweepS, ctSweepM, or dtSweep). |
conditions |
Character vector. Condition names for row ordering. If NULL, automatically extracted from expressions. |
symbol_set |
Character. One of |
chart_level |
Character. Chart aggregation level:
|
language |
Character. |
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 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")
)
Arguments
result |
A result object from any Sweep function with
|
output_file |
Character. Path to output markdown file. |
format |
Character. Report format: |
title |
Character. Report title. |
dat |
Optional data frame. Original data for descriptive statistics. |
desc_vars |
Optional character vector. Variables for descriptive statistics. If NULL and dat is provided, uses Yvar and Xvars from params. |
include_chart |
Logical. If TRUE (default), includes configuration charts (Fiss-style tables) in the report for each threshold. |
chart_symbol_set |
Character. Symbol set for configuration charts:
|
chart_level |
Character. Chart aggregation level:
|
solution_note |
Logical. If TRUE (default), adds a note when multiple equivalent solutions exist explaining that M1 is shown. |
solution_note_style |
Character. Style of solution note:
|
solution_note_lang |
Character. Language for solution notes:
|
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 detailed solution notes (including EPIs)
generate_report(result, "my_report.md", format = "full",
solution_note_style = "detailed")
## 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
n_sol |
Integer. Number of solutions. |
epi_list |
Character vector. Essential prime implicants (NULL to omit). |
style |
Character. |
language |
Character. |
format |
Character. |
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
sum_df |
Data frame. Summary data frame from sweep results with expression column and threshold column(s). |
conditions |
Character vector. Condition names for row ordering. |
symbols |
List. Symbol set (present, absent) for the chart. |
language |
Character. Language for labels ("en" or "ja"). |
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
sum_df |
Data frame. Summary data frame from sweep results. |
conditions |
Character vector. Condition names for row ordering. |
symbols |
List. Symbol set (present, absent) for the chart. |
language |
Character. Language for labels ("en" or "ja"). |
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
sol_list |
List of solution character vectors from minimize(). |
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
term |
Character. Single term (e.g., "X1*X2", "~X3"). |
condition |
Character. Condition name (e.g., "X1"). |
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
sol |
A solution object returned by |
Value
Integer. Number of intermediate solutions, or 0 if none.
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
solutions |
List of solution vectors. Each element is a character vector of terms for one solution. |
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")
OTS–QCA: 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,
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., |
conditions |
Character vector. Names of condition variables. |
sweep_range |
Numeric vector. Candidate thresholds for Y. |
thrX |
Named numeric vector. Fixed thresholds for X variables,
with names matching |
dir.exp |
Directional expectations for |
include |
Inclusion rule for |
incl.cut |
Consistency cutoff for |
n.cut |
Frequency cutoff for |
pri.cut |
PRI cutoff for |
extract_mode |
Character. How to handle multiple solutions:
|
return_details |
Logical. If |
Yvar |
Deprecated. Use |
Xvars |
Deprecated. Use |
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 ofthrY,thrX_vec,truth_table,solution
Examples
# Load sample data
data(sample_data)
# Set fixed thresholds for conditions
thrX <- c(X1 = 7, X2 = 7, X3 = 7)
# Run outcome threshold sweep (standard)
result <- otSweep(
dat = sample_data,
outcome = "Y",
conditions = c("X1", "X2", "X3"),
sweep_range = 6:9,
thrX = thrX
)
head(result$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:9,
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
path |
Character. A single path like "AB~C" |
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
expr |
Character. Solution expression (e.g., "X3 + X1*X2"). |
Value
Character vector of terms (e.g., c("X3", "X1*X2")), or NULL if no valid expression.
Print method for TSQCA results
Description
Displays a concise overview of TSQCA 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
x |
A TSQCA result object returned by one of the sweep functions. |
... |
Additional arguments (ignored). |
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)
Binary calibration helper for TSQCA
Description
Converts a numeric vector into a crisp set (0/1) based on a threshold.
Usage
qca_bin(x, thr)
Arguments
x |
Numeric vector. |
thr |
Numeric scalar. Cases with |
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
sol |
A solution object returned by |
extract_mode |
Character. How to handle multiple intermediate solutions:
|
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.
Sample dataset for TSQCA 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.
Split solution expression into terms
Description
Split solution expression into terms
Usage
split_solution_terms(solution)
Arguments
solution |
Character. Solution expression (e.g., "X1*X2 + X3"). |
Value
Character vector of terms.
Summary method for TSQCA 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
object |
A TSQCA result object returned by one of the sweep functions. |
... |
Additional arguments (ignored). |
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)
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"
)
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"
)