# 便捷全功能fsQCA

**Repository Path**: HarryJWC/Convenientfullfeatured-fsQCA

## Basic Information

- **Project Name**: 便捷全功能fsQCA
- **Description**: 比官方界面更优化操作更方便的fsQCA
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-11-30
- **Last Updated**: 2025-12-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarryC's Convenient Full-Featured fsQCA V8.1 JW❤QX @小红书drharry
-----
- 这是一个基于 Python 的图形化（GUI）模糊集定性比较分析（fsQCA）全流程工具。
- 它集成了 数据校准、必要性分析、真值表构建、标准分析、稳健性检验 以及 tQCA (时序QCA) 等高级功能。
- 本工具专为社会科学领域的科研人员设计，旨在通过“傻瓜式”操作替代老旧的官方软件，解决官方软件不支持中文、无法撤销、画图难、导出难等痛点，支持交互式可视化和全量数据一键导出 Excel。

## 0. 核心声明：与官方软件对比 (Comparison)
✅ **我们做到了什么 (Achieved)**
经过多轮数值对比测试（Benchmark），本工具在核心算法上与官方 fsQCA 3.0/3.1 保持高度一致：
- **数值对比**: 在保留足够小数位的情况下，校准 (Calibration)、必要性检验 (Necessity) 的结果与官方完全一致。
- **真值表 (Truth Table)**: 各项核心指标（Raw Cons., PRI Cons.）与官方仅存在极微弱的精度差异（通常在小数点后 5-6 位），不影响最终组态判定。
- **标准分析 (Standard Analysis)**: 复杂解、简约解、中间解的生成逻辑一致，覆盖度 (Coverage) 与一致性 (Consistency) 的数值仅存在微弱精度差异。
- **解决方案**: 在相同阈值设置下，生成的组态路径与官方版完全一致。

⚠️ **已知差异与局限 (Discrepancies & Limitations)**
- **SYM 指标差异**: 在单真值表中，本工具计算的 SYM 指标与官方软件在某些特定数据下存在较大差异。这可能是由于官方软件内部未公开的计算逻辑或本工具自身数据测试量的局限性导致的未知误差。
- **高级功能测试**: 由于受限于官方版功能范围（官方版无 tQCA、无高级回归稳健性等）以及作者自身的数据和知识水平，Step 6 (tQCA) 和 Step 8 (高级工具箱) 中的部分功能未能与官方或权威文献结果进行大规模对齐测试。
- **使用建议**: 请各位用户在使用高级功能时自行判断，建议结合具体论文复核结果，最好交叉验证。
- **具体比对请参照项目文件中的对比文件**：
```bash
和官方fsQCA分析的基础结果对比.xlsx
```
## 0  详细对比说明
## 0.1 核心原理与计算方法对比表

| 维度 | 比较项目 | Hfsqca Pro V8.5 (Python脚本) | 官方 fsQCA 4.1 | 差异/备注 |
| --- | --- | --- | --- | --- |
| **底层架构** | 运行环境 | Python 3 (基于 NumPy, Pandas, SymPy) | Windows 应用程序 (C++/Delphi等底层) | Python 浮点数精度为双精度 (64-bit)，与官方基本一致，但在极小值处理上可能存在微小精度差异。 |
| **变量校准** | 直接校准法 | 使用 Log-Odds 转换。<br><br>公式: m = exp(L)/(1+exp(L))。<br><br>边界处理: 强制截断在 [0.001, 0.999]。<br><br>0.5处理: 遇到 0.5 自动加 0.001 变为 0.501。 | 使用 Log-Odds 转换。<br><br>标准逻辑一致。<br><br>0.5处理: 通常建议用户手动处理或加常数。 | 高度一致（存在微小差异）。<br><br>Hfsqca 自动化的 0.001 偏移可能导致校准值在第3-4位小数上有极其微小的差异。 |
| **必要性分析** | 一致性 (Cons) | Formula: $\sum \min(X, Y) / \sum Y$ | 同左 | 高度一致（存在微小精度差异）。 |
|  | 覆盖率 (Cov) | Formula: $\sum \min(X, Y) / \sum X$ | 同左 | 高度一致（存在微小精度差异）。 |
| **真值表** | Row Frequency | 统计隶属度 > 0.5 的案例数。 | 同左 | 高度一致。<br><br>若校准值在 0.5 边缘极其接近，可能会因精度导致归类差异，但通常一致。 |
|  | Raw Consistency | Formula: $\sum \min(Cfg, Y) / \sum Cfg$ | 同左 | 高度一致（存在微小精度差异）。 |
|  | PRI Consistency | Formula: $\frac{\sum \min(Cfg, Y) - \sum \min(Cfg, Y, \sim Y)}{\sum Cfg - \sum \min(Cfg, Y, \sim Y)}$ | 同左 | 高度一致（存在微小精度差异）。 |
|  | SYM (对称性) | 算法差异点: 代码中使用 $\sqrt{Raw \times PRI}$ (几何平均)。 | 通常指 PRI 或特定集合重叠度，官方真值表默认不显示此特定计算列。 | 差异较大。<br><br>代码中的 SYM 是一种特定的修正算法，而官方软件中对应的概念可能不同，导致数值无法直接对齐。 |
| **组态最小化** | 算法引擎 | Quine-McCluskey (QM) 算法。<br><br>使用 sympy.logic 库进行布尔代数化简。 | Quine-McCluskey (QM) 算法。<br><br>内部实现的化简引擎。 | 原理一致。<br><br>SymPy 的处理非常标准，但在处理 "Prime Implicant Chart" (质蕴涵图) 的Tie-breaking（相同覆盖能力的解的选择）时，可能与官方默认策略不同。 |
|  | 中间解 (Intermediate) | 自动化处理。<br><br>基于用户设定的预期 (Directional Expectations)，自动保留符合预期的条件。 | 半交互式。<br><br>用户在 Standard Analysis 界面手动确认 Easy Counterfactuals。 | 方案数量可能不同（概率低）。<br><br>代码逻辑较为严格（保守），严格遵循预期方向。若官方软件中用户进行了额外的人工干预，结果会有出入。 |

## 0.2 数值一致性与差异统计分析

基于项目中的独立测试数据逻辑（生成 N=100, T=3 的模拟面板数据或导入外部数据），以下是各项指标的详细统计对比：

## 0.2.1 必要性统计 (Necessity Analysis)

- **一致性结论**: 高度一致（存在微小精度差异）。
- **数值差异**: $\Delta < 10^{-6}$。
- **分析**: 必要性计算公式简单（向量点积），仅涉及基础的加法和除法。Python NumPy 的精度足以复现官方结果。任何微小差异仅来源于校准阶段对 0.5 的处理方式（0.5 vs 0.501）以及浮点数运算的累积误差。

## 0.2.2 校准值 (Calibration Values)

- **一致性结论**: 高度一致（存在微小精度差异）。
- **数值差异**: 在锚点附近可能存在 $\pm 0.001$ 的差异。
- **原因**: 代码中显式执行了 `if 0.499 < m < 0.501: return 0.501` 以及 `min(max(m, 0.001), 0.999)` 的截断。官方软件如果在数据导入阶段没有做同样的预处理，原始数据校准后的隶属度在极值（0和1）附近可能保留更多小数位，或者对交叉点处理不同。

## 0.2.3 真值表的一致性 (Truth Table Consistency)

- **Raw Consistency**: 高度一致（存在微小精度差异） ($\Delta < 10^{-5}$)。
- **PRI Consistency**: 高度一致（存在微小精度差异） ($\Delta < 10^{-5}$)。
- **SYM (差异较大)**:
  - **代码逻辑**: `sym_val = np.sqrt(raw_loc * pri)`
  - **现象**: 代码计算出的 SYM 值通常介于 Raw 和 PRI 之间。
  - **原因**: 这是一个自定义的指标（可能是为了综合考量原始一致性和PRI）。官方 fsQCA 4.1 的 Truth Table 默认列通常是 raw consist. 和 PRI consist.。如果官方软件输出了 SYM，其定义通常是基于集合重叠度或其他算法，而非简单的几何平均。因此，这一列数值无法对齐是预期的，属算法定义不同。

## 0.2.4 解决方案数量与组合 (Solutions & Combinations)

- **复杂解 (Complex) & 简约解 (Parsimonious)**:
  - **组合**: 完全一致（在模型无歧义情况下）。
  - **数量**: 通常一致。但在极少数存在“模型歧义性 (Model Ambiguity)”的情况下（即存在多个覆盖能力相同的质蕴涵项），sympy 返回的解可能包含 Or(...) 形式的所有可能性，或者默认展示其中一种；而 fsQCA 4.1 可能会列出所有 Prime Implicants 供选择。
- **中间解 (Intermediate)**:
  - **组合**: 基本一致，但取决于预期设置。
  - **差异点**: 代码中的 `_generate_intermediate_solution` 函数实现了标准的“简单反事实 (Easy Counterfactuals)”纳入逻辑。代码注释提到：“针对 Present or Absent (Either, -1) 的情况，采取保守策略 (保留条件)”。这与 fsQCA 4.1 的默认逻辑力求对齐，但如果用户在官方软件中对“Either”类条件的处理有不同理解（官方有时会将其剔除以追求更简），则会导致解的项数不同。

## 0.2.5 对应案例 (Covered Cases)

- **一致性**: 高度一致（存在微小判定差异）。
- **判定逻辑**: 代码与官方均使用隶属度 $Membership > 0.5$ 作为案例归属判定标准。对于绝大多数案例，判定结果是一致的。但对于校准后隶属度恰好在 0.500000 附近的边缘案例，Python 的浮点精度处理与官方软件可能导致其归属（0或1）发生翻转，从而导致覆盖案例列表存在个别差异。

## 0.2.6 解决方案的一致性与覆盖率 (Solution Consistency & Coverage)

- **原始一致性 (Raw Cons.)**: 高度一致（存在微小精度差异） ($\Delta \approx 0.0001 - 0.001$)。
- **覆盖率 (Raw Cov. & Unique Cov.)**: 高度一致（存在微小精度差异）。
- **原因**:
  - 浮点数累加误差: Python `sum()` 与 C++ 累加器的底层差异。
  - 分母微差: 代码中为了防止除以零，分母加了 `1e-9` 或 `1e-6` (如 `inters / (vec.sum() + 1e-9)` )。这种平滑处理会导致结果在小数点后 4-6 位出现微小抖动，但在社会科学统计意义上可忽略不计。

# 0.3. 总结

| 指标 | 匹配度 | 说明 |
| --- | --- | --- |
| **必要性 (NCA)** | ⭐⭐⭐⭐⭐ | 算法简单，结果高度一致（微小精度差异）。 |
| **校准数据** | ⭐⭐⭐⭐⭐ | 逻辑相同，仅存在边界值截断策略带来的微扰。 |
| **真值表 (Raw/PRI)** | ⭐⭐⭐⭐⭐ | 核心指标高度一致（微小精度差异）。 |
| **真值表 (SYM)** | ⭐⭐ | 算法定义不同。代码使用了几何平均修正，官方使用不同定义。 |
| **组态路径 (Solution)** | ⭐⭐⭐⭐ | 复杂解和简约解匹配度极高。中间解依赖于对“Either”条件的自动化处理策略，大多数情况下一致。 |
| **拟合参数 (Fit)** | ⭐⭐⭐⭐⭐ | 一致性与覆盖率存在浮点精度级别的微小差异，不影响解释。 |

**结论**: 该 Python 脚本 (Hfsqca Pro) 在核心分析功能上（必要性、真值表构建、最小化求解）是对 fsQCA 4.1 的高保真复刻。除 SYM 指标外，其他所有统计结果在保留 3 位小数的精度下通常与官方软件结果保持高度一致，存在的细微差别主要源于浮点数运算精度和边界值处理策略。




## 2. 新手入门与数据准备 (Quick Start)
### 2.1 获取与运行
下载主程序 `HfsqcaV8.py`。建议新建一个文件夹，将程序放入其中，因为软件会自动生成 `FsQCA_Report` 结果文件夹。本项目随附了 自动生成测试数据 的功能，点击软件主界面的“🎲 生成测试数据”即可快速上手体验。

### 2.2 数据格式说明
您的数据文件应当是 Excel (.xlsx) 或 CSV 格式。必须包含: 案例 ID 列（可选，但推荐）、结果变量列、条件变量列。
- **面板数据**: 如果要进行 Step 6 时序分析，数据需要包含“时间列”和“ID列”。
- **测试数据**：如需测试流程请使用项目目录提供的测试数据，不建议使用软件自带的生成测试数据。

### 2.3 设置工作目录 (Work Directory)
软件启动后，建议点击侧边栏的 [📂 设置工作目录]，选择您希望存放结果的文件夹。所有的模型文件、Excel 报表、HTML 可视化图表都会保存在这个目录下。

## 3. 环境与安装要求 (必读)
### 3.1 操作系统兼容性
- **推荐**: Windows 11 + PyCharm 环境 (已通过完整测试，运行稳定)。
- **警告**: macOS 系统或其他 Linux 发行版可能存在严重的 UI 渲染 Bug（如界面卡死、字体显示错误等）。Mac 用户建议使用虚拟机 (Parallels Desktop/VMware) 运行 Windows 版本。

### 3.2 依赖库安装
如果您是 Python 新手，请在 PyCharm 的 Terminal (终端) 中运行以下命令安装必要依赖：
```bash
pip install pandas numpy matplotlib plotly seaborn statsmodels xlsxwriter openpyxl sympy scipy
```
### 3.3 EXE版本（可能存在BUG）
```bash
通过网盘分享的文件：FsQCA_Pro_V8.zip
链接: https://pan.baidu.com/s/1nbVf6KNZY-F9LzZuOZhMIg 提取码: p8uj 
--来自百度网盘超级会员v7的分享
```

# 4. 核心功能流程详解

### Step 0: 数据预处理 (Data)
- **变量合成**: 支持多指标平均值合成潜变量。
- **类型设定**: 必须正确设置变量类型（Likert7/5, Continuous），特别是将 ID列 和 时间列 设为 Categorical，防止被错误校准。

### Step 1: 变量校准 (Calibration)
- **多模式支持**: Direct (直接法), Indirect, Rank, Linear, Crisp。
- **自动锚点**: 支持一键根据百分位数 (如 95%, 50%, 5%) 计算锚点。
- **偏态数据支持**: 新增“偏态分布推荐”按钮，自动应用 Pappas & Woodside 推荐的 80/50/20 阈值。

### Step 2 & 3: 必要性与真值表
- **NCA**: 一键计算必要性和瓶颈水平。
- **真值表构建**: 支持自定义频数 (Freq)、原始一致性 (Raw Cons) 和 PRI 阈值。
- **PRI 约束**: 可选是否在构建真值表阶段就应用 PRI 约束逻辑。

### Step 4: 标准分析 (Standard Analysis)
- **双向分析**: 自动同时运行正向 (Outcome) 和反向 (~Outcome) 分析。
- **方向性预期**: 支持设置中间解 (Intermediate Solution) 的方向性预期 (Present/Absent/Either)，逻辑严格对齐 fsQCA。
- **稳健性检验**: 集成多种稳健性测试（阈值调整、锚点漂移、案例剔除、噪音变量干扰）。
- **回归稳健性**: 支持分层回归分析 (Hierarchical Regression) 进行方法论三角验证。

### Step 5 & 6: 可视化与时序分析 (Advanced)
- **多模型可视化**: 实验性功能，支持通过画布拖拽定义因果链，批量运行多个 QCA 模型。
- **tQCA (时序QCA)**:
  - 内置面板数据转换器 (Panel Data Converter)。
  - 支持生成 状态演变桑基图 (Sankey)。
  - 支持阶段化组态对比分析。

### Step 8: 高级工具箱 (Tools)
- **Pappas & Woodside 科学性验证**:
  - **预测有效性检验**: 拆分样本 (Split-Sample) 检验。
  - **对立案例分析**: 识别数据中的非主效应案例 (Contrarian Cases)。
  - **特定命题检验**: 自定义布尔表达式验证 (XY Plot)。

# 5. 输出文件与图表深度解读 (Output Files Explained)
点击“一键导出所有结果”后，程序会在工作目录下生成 FsQCA_Report_时间戳 文件夹。以下是对核心文件及其 Sheet 的详细说明。

## 5.1 核心全量报表 (Analysis_Results_FULL.xlsx)
这是最重要的文件，包含了从数据处理到最终稳健性检验的所有数据。文件内包含多个 Sheet（工作表）：

### A. 基础数据类 (Data Sheets)
| Sheet 名称 | 详细解读 |
| ---- | ---- |
| Raw_Data | 原始导入的数据，不做任何修改。 |
| Calibrated_Data_Full | 校准后的全量数据。包含 0-1 之间的模糊集隶属度分数。 |
| Calibration_Log | 记录了每个变量使用的校准锚点 (Full, Cross, Non) 和方法，用于论文汇报参数。 |
| Truth_Table | 真值表。包含 Raw Cons. (原始一致性), PRI Cons. (PRI一致性), SYM (对称一致性) 等关键指标。 |
| Necessity_NCA | 必要性分析结果。包含一致性 (Cons) 和覆盖度 (Cov)，用于判定必要条件。 |

### B. 标准分析类 (Standard Analysis Sheets)
此部分包含正向 (Pos) 和反向 (Neg) 的分析结果。

| Sheet 名称 | 详细解读 |
| ---- | ---- |
| Pos_Complex | 复杂解 (Complex Solution)。不包含逻辑余项的解。 |
| Pos_Parsimonious | 简约解 (Parsimonious Solution)。包含所有逻辑余项的解，用于判定核心条件。 |
| Pos_Intermediate | 中间解 (Intermediate Solution)。基于方向性预期的解，用于论文主要汇报。 |
| Pos_Fiss_Main | 【核心图表】FISS 组态分析表。程序自动对比中间解与简约解，生成的符合 Fiss (2011) 格式的表格。符号说明:  A = 核心条件存在 (Core Present) a = 边缘条件存在 (Peripheral Present) B = 核心条件缺失 (Core Absent) b = 边缘条件缺失 (Peripheral Absent) |
| Neg_... | 同上，对应反向结果 (~Outcome) 的分析。 |

### C. 稳健性与高级分析类 (Robustness & Advanced)
| Sheet 名称 | 详细解读 |
| ---- | ---- |
| Robustness_Summary | 稳健性检验摘要表。对比了不同测试（如调整阈值、剔除案例）下的解的数量、一致性和覆盖度变化。 |
| Pos/Neg_Rob_Fiss | 稳健性测试生成的 FISS 格式组态表，方便直接观察稳健性。 |
| Robustness_Regression | 分层回归结果。模仿顶刊格式，列出 Beta 系数、标准误和 P 值星号 (*)。 |
| Model_Fit_Comparison | 多模型分析中的拟合度对比 (Step 5)。 |
| tQCA_Sequence_Analysis | 时序 QCA 的序列分析结果，包含序列频率和一致性。 |

## 5.2 专项分析报表 (Specific Reports)
使用 Step 8 工具箱时生成的独立 Excel 文件：
- **Predictive_Validity_*.xlsx**: 预测有效性检验结果。对比子样本 (Subsample) 和保留样本 (Holdout) 的一致性差异。
- **Contrarian_*.xlsx**: 对立案例分析交叉表。展示五分位 (Quintile) 下的案例分布，用于识别非主效应案例。
- **PropTest_*.xlsx**: 特定命题检验的一致性和覆盖度指标。

## 5.3 可视化图表解读 (Visualizations)
在 Charts 和 Solution_XY_Plots 文件夹中包含以下图表：

### A. 组态 XY 散点图 (Solution_XY_Plots/)
- **文件格式**: 提供.html (交互式，鼠标悬停显示案例ID) 和.png (静态，适合论文) 两种格式。
- **X轴**: 组态隶属度 (Configuration Membership)。代表案例属于该组态的程度。
- **Y轴**: 结果隶属度 (Outcome Membership)。代表案例在结果变量上的表现。
- **解读**: 大部分点应位于对角线 (Y=X) 上方 (左上角区域)，表示该组态是结果的充分条件。

### B. 时序桑基图 (tQCA_Sankey_*.html)
- **用途**: 展示变量状态随时间的演变路径（tQCA）。
- **节点**: 如 T1_High(1) 表示在 T1 时刻该变量为高水平。
- **连线**: 宽度代表案例数量。
- **颜色**: 绿色代表高水平状态，橙色代表低水平状态。

### C. 隶属度热力图 (Heatmap.html)
- **用途**: 直观展示哪些案例属于哪些组态。
- **颜色**: 颜色越亮/越黄，代表隶属度越高；颜色越暗/越紫，代表隶属度越低。

# 6. 常见问题 (FAQ)
**Q: 为什么生成的中间解和官方软件有细微差别？**
A: 请检查 Step 4 中的“方向性预期”设置是否与官方软件完全一致。对于 "Either" 的处理，本软件采取保守策略（保留条件），以防止过度简化。

**Q: 为什么 FISS 表里的符号是 A/a/B/b？**
A: 这是为了方便 Excel 显示和后续处理。A/B 代表核心条件（存在/缺失），a/b 代表边缘条件（存在/缺失）。您可以直接在 Excel 中将其替换为实心圆 (●) 和空心圆 (⊗)。

**Q: Mac 系统界面显示不全？**
A: 这是 Tkinter 在 macOS 上的已知底层兼容性问题。强烈建议使用 Windows 环境运行。

# 7. 作者声明
## 👨‍💻 作者寄语
我是编程爱好者，开发此工具旨在辅助科研，降低 QCA 方法的使用门槛。代码逻辑尽量贴合主流 QCA 规范，但仍可能存在疏漏。

## ⚠️ 免责声明
本软件提供的分析结果仅供参考。在发表高水平学术论文前，强烈建议使用官方 fsQCA 软件对核心组态进行二次复核。作者不对因使用本软件导致的科研失误承担责任。

Code revised by JW❤QX. Version 8.0