---
title: "TSQCA Reproducible Code (English)"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{TSQCA Reproducible Code (English)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```{r, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

This document provides **reproducible code** for TSQCA analyses.  
It is designed to be inserted directly into a research article's appendix  
or provided as supplementary analysis documentation.
All code is fully executable and ordered for reproducibility.

---

# 1. Load Packages
```{r}
library(TSQCA)
library(QCA)
```

---

# 2. Load Data
```{r}
# Adjust the file name as needed
library(TSQCA)
data("sample_data")
dat <- sample_data

# Outcome and conditions
outcome  <- "Y"
conditions <- c("X1", "X2", "X3")

# Quick inspection
str(dat)
summary(dat)
```

---

# 3. Baseline Thresholds
```{r}
thrY_base <- 7
thrX_base <- 7

# Fixed X thresholds (for OTS–QCA)
thrX_vec <- c(
  X1 = thrX_base,
  X2 = thrX_base,
  X3 = thrX_base
)
thrX_vec
```

---

# 4. CTS–QCA (ctSweepS)

Sweep a **single condition X** (example: X3).
```{r, error=TRUE}
sweep_var   <- "X3"   # Condition (X) whose threshold is swept
sweep_range <- 6:9    # Candidate threshold values to evaluate
thrY         <- 7     # Outcome (Y) threshold (fixed)
thrX_default <- 7     # Threshold for other X conditions (fixed)

res_cts <- ctSweepS(
  dat            = dat,
  outcome        = "Y",
  conditions     = c("X1", "X2", "X3"),
  sweep_var      = "X3",
  sweep_range    = 6:9,
  thrY           = 7,
  thrX_default   = 7,
  dir.exp        = c(1, 1, 1),
  return_details = TRUE
)

summary(res_cts)
```

Export:
```{r, eval=FALSE}
write.csv(res_cts$summary, file = "TSQCA_CTS_results.csv", row.names = FALSE)
```

---

# 5. MCTS–QCA (ctSweepM)

Sweep **multiple X thresholds simultaneously**.
```{r, error=TRUE}
# Create a sweep list specifying thresholds for each condition
sweep_list <- list(
  X1 = 6:7,
  X2 = 6:7,
  X3 = 6:7
)

res_mcts <- ctSweepM(
  dat            = dat,
  outcome        = "Y",
  conditions     = c("X1", "X2", "X3"),
  sweep_list     = sweep_list,
  thrY           = 7,
  dir.exp        = c(1, 1, 1),
  return_details = TRUE
)

summary(res_mcts)
```

Export:
```{r, eval=FALSE}
write.csv(res_mcts$summary, file = "TSQCA_MCTS_results.csv", row.names = FALSE)
```

---

# 6. OTS–QCA (otSweep)

Sweep **only the outcome threshold (Y)**.
```{r}
sweep_range_ots <- 6:8

res_ots <- otSweep(
  dat            = dat,
  outcome        = "Y",
  conditions     = c("X1", "X2", "X3"),
  sweep_range    = sweep_range_ots,
  thrX           = thrX_vec,
  dir.exp        = c(1, 1, 1),
  return_details = TRUE
)

summary(res_ots)

```

Export:
```{r, eval=FALSE}
write.csv(res_ots$summary, file = "TSQCA_OTS_results.csv", row.names = FALSE)
```

---

# 7. DTS–QCA (dtSweep)

Two-dimensional sweep: **X thresholds × Y thresholds**.
```{r}
sweep_list_dts_X <- list(
  X1 = 6:7,
  X2 = 6:7,
  X3 = 6:7
)

sweep_range_dts_Y <- 6:7

res_dts <- dtSweep(
  dat            = dat,
  outcome        = "Y",
  conditions     = c("X1", "X2", "X3"),
  sweep_list_X   = sweep_list_dts_X,
  sweep_range_Y  = sweep_range_dts_Y,
  dir.exp        = c(1, 1, 1),
  return_details = TRUE
)

summary(res_dts)

```

Export:
```{r, eval=FALSE}
write.csv(res_dts$summary, file = "TSQCA_DTS_results.csv", row.names = FALSE)
```

---

# 8. Using extract_mode (New in v0.2.0)

Extract all solutions or essential prime implicants for robustness analysis.

## Extract All Solutions
```{r, eval=FALSE}
res_all <- otSweep(
  dat            = dat,
  outcome        = "Y",
  conditions     = c("X1", "X2", "X3"),
  sweep_range    = 6:8,
  thrX           = thrX_vec,
  dir.exp        = c(1, 1, 1),
  extract_mode   = "all",
  return_details = TRUE
)

# View results with n_solutions column
head(res_all$summary)
```

## Extract Essential Prime Implicants
```{r, eval=FALSE}
res_essential <- otSweep(
  dat            = dat,
  outcome        = "Y",
  conditions     = c("X1", "X2", "X3"),
  sweep_range    = 6:8,
  thrX           = thrX_vec,
  dir.exp        = c(1, 1, 1),
  extract_mode   = "essential",
  return_details = TRUE
)

# View results with essential prime implicants, selective terms, and unique terms
head(res_essential$summary)
```

---

# 9. Generating Reports (New in v0.2.0)

Create comprehensive markdown reports for documentation.

## Full Report
```{r, eval=FALSE}
generate_report(res_ots, "TSQCA_OTS_report_full.md", dat = dat, format = "full")
```

## Simple Report (for manuscripts)
```{r, eval=FALSE}
generate_report(res_ots, "TSQCA_OTS_report_simple.md", dat = dat, format = "simple")
```

---

# 10. Negated Outcome Analysis (New in v0.3.0)

Analyze conditions sufficient for the **absence** of the outcome.

## Standard vs Negated Outcome
```{r, eval=FALSE}
# Standard: conditions for Y >= threshold
res_Y <- otSweep(
  dat            = dat,
  outcome        = "Y",
  conditions     = c("X1", "X2", "X3"),
  sweep_range    = 6:8,
  thrX           = thrX_vec,
  dir.exp        = c(1, 1, 1)
)

# Negated: conditions for Y < threshold
res_negY <- otSweep(
  dat            = dat,
  outcome        = "~Y",
  conditions     = c("X1", "X2", "X3"),
  sweep_range    = 6:8,
  thrX           = thrX_vec,
  dir.exp        = c(1, 1, 1)
)

# Compare results
res_Y$summary
res_negY$summary

# Check negation flag
res_negY$params$negate_outcome
# [1] TRUE
```

---

# 11. Accessing Analysis Parameters

All parameters are stored for reproducibility.
```{r, eval=FALSE}
# View stored parameters
res_ots$params

# Example output:
# $outcome
# [1] "Y"
# $conditions
# [1] "X1" "X2" "X3"
# $thrX
# X1 X2 X3 
#  7  7  7 
# $incl.cut
# [1] 0.8
# $n.cut
# [1] 1
# $pri.cut
# [1] 0
```

---

## Configuration Charts (New in v0.5.0)

Configuration charts are now automatically included in reports. You can also generate them separately:

```{r}
# From path strings
paths <- c("A*B*~C", "A*D")
chart <- config_chart_from_paths(paths)
cat(chart)
```

For reports:
```{r, eval=FALSE}
# Charts are included by default
generate_report(result, "report.md", dat = dat, format = "full")

# Use LaTeX symbols for academic papers
generate_report(result, "report.md", dat = dat, chart_symbol_set = "latex")
```

---

## References

For more information on TS-QCA methodology, see:

- Ragin, C. C. (2008). *Redesigning Social Inquiry: Fuzzy Sets and Beyond*. University of Chicago Press. DOI: [10.7208/chicago/9780226702797.001.0001](https://doi.org/10.7208/chicago/9780226702797.001.0001)
- Duşa, A. (2019). *QCA with R: A Comprehensive Resource*. Springer. DOI: [10.1007/978-3-319-75668-4](https://doi.org/10.1007/978-3-319-75668-4)
- Oana, I.-E., & Schneider, C. Q. (2024). A Robustness Test Protocol for Applied QCA: Theory and R Software Application. *Sociological Methods & Research*, 53(1), 57–88. DOI: [10.1177/00491241211036158](https://doi.org/10.1177/00491241211036158)



# 12. Session Information
```{r}
sessionInfo()
```