ssci-subagent-skills 1.0.0

package/skills/msqca-analysis/references/METHODOLOGY.md

@@ -0,0 +1,282 @@
+# msQCA方法论详解
+
+## 📋 概述
+
+多值定性比较分析(multi-value Qualitative Comparative Analysis, msQCA)是一种基于集合论和布尔代数的比较研究方法，专门用于分析复杂因果机制。与传统的QCA相比，msQCA能够处理具有多个类别的条件变量，提供更丰富的分析维度。
+
+## 🎯 核心原理
+
+### 集合论基础
+
+msQCA建立在以下集合论原理之上：
+
+1. **子集关系**：如果条件A是结果B的子集，则A是B的充分条件
+2. **超集关系**：如果条件A是结果B的超集，则A是B的必要条件  
+3. **等价关系**：如果A既是B的子集又是B的超集，则A与B等价
+
+### 布尔代数运算
+
+- **合取(AND, *)**：多个条件同时满足
+- **析取(OR, +)**：任一条件满足即可
+- **否定(NOT, ~)**：条件不满足
+
+## 🔬 分析流程详解
+
+### 第一阶段：理论建构
+
+#### 1.1 研究问题界定
+- 明确研究目标和核心问题
+- 确定分析的单位(案例)
+- 界定时间和空间范围
+
+#### 1.2 条件选择
+- **理论驱动**：基于现有理论选择相关条件
+- **案例导向**：从案例特征中提取潜在条件
+- **数量控制**：条件数量一般不超过案例数量的1/3
+
+#### 1.3 结果定义
+- 明确结果变量的操作化定义
+- 确保结果具有理论意义和实践价值
+- 考虑结果的时间维度
+
+### 第二阶段：数据校准
+
+#### 2.1 校准原理
+
+校准是将原始数据转换为集合隶属度的过程，核心是建立经验观察与理论概念之间的桥梁。
+
+#### 2.2 校准方法
+
+##### 直接校准
+```python
+# 基于理论阈值的直接转换
+def direct_calibration(data, thresholds):
+    """
+    直接校准：根据预设阈值将连续变量转换为分类变量
+    
+    Parameters:
+    - data: 原始数据
+    - thresholds: 校准阈值列表
+    
+    Returns:
+    - 校准后的分类数据
+    """
+    calibrated = pd.cut(data, 
+                       bins=[-np.inf] + thresholds + [np.inf],
+                       labels=range(len(thresholds) + 1),
+                       include_lowest=True)
+    return calibrated
+```
+
+##### 间接校准
+```python
+# 通过隶属函数的渐进转换
+def indirect_calibration(data, thresholds):
+    """
+    间接校准：使用隶属函数进行渐进式转换
+    
+    核心思想：
+    - 使用S型隶属函数
+    - 考虑过渡区域的模糊性
+    - 提供更平滑的转换
+    """
+    # 实现细节见calibration.py
+```
+
+##### 多值校准
+```python
+# 处理具有多个类别的变量
+def multi_value_calibration(data):
+    """
+    多值校准：处理分类变量的多值特性
+    
+    适用场景：
+    - 定类变量(如制度类型)
+    - 定序变量(如发展水平)
+    - 名义变量(如地区分类)
+    """
+    # 实现细节见calibration.py
+```
+
+#### 2.3 校准质量检验
+
+- **理论一致性**：校准结果与理论预期的匹配程度
+- **分布合理性**：校准后数据的分布特征
+- **案例代表性**：各类别案例的代表性
+
+### 第三阶段：真值表构建
+
+#### 3.1 真值表结构
+
+| 条件A | 条件B | 条件C | 案例数 | 一致性 | 结果类型 |
+|-------|-------|-------|--------|--------|----------|
+|   0   |   1   |   2   |   5    |  0.9   |    1     |
+|   1   |   0   |   1   |   3    |  0.8   |    1     |
+|   2   |   2   |   0   |   4    |  0.1   |    0     |
+
+#### 3.2 一致性计算
+
+```python
+def calculate_consistency(outcome_values, threshold=0.8):
+    """
+    一致性计算：衡量条件组合与结果的匹配程度
+    
+    公式：一致性 = 达到阈值的案例数 / 总案例数
+    
+    阈值设定：
+    - 严格标准：0.9以上
+    - 标准要求：0.8以上  
+    - 宽松标准：0.7以上
+    """
+    consistent_cases = (outcome_values >= threshold).sum()
+    total_cases = len(outcome_values)
+    return consistent_cases / total_cases
+```
+
+#### 3.3 逻辑余项处理
+
+**逻辑余项**：理论可能但现实中未观察到的条件组合
+
+处理策略：
+- **包含策略**：用于简约解，增加理论解释力
+- **排除策略**：用于复杂解，保证经验基础
+- **选择性包含**：基于理论判断有选择地包含
+
+#### 3.4 矛盾组合处理
+
+**矛盾组合**：一致性介于正负阈值之间的条件组合
+
+处理方法：
+- **移除法**：直接删除矛盾组合
+- **重新编码**：根据一致性倾向重新分类
+- **分裂法**：将矛盾组合分裂为正负两种结果
+
+### 第四阶段：逻辑最小化
+
+#### 4.1 Quine-McCluskey算法
+
+```python
+def quine_mccluskey(combinations):
+    """
+    Quine-McCluskey算法：布尔函数最小化
+    
+    步骤：
+    1. 生成所有蕴含项
+    2. 合并相邻蕴含项
+    3. 识别质蕴含项
+    4. 选择最小覆盖
+    """
+    # 算法实现见minimization.py
+```
+
+#### 4.2 解的类型
+
+##### 复杂解(Complex Solution)
+- 包含所有质蕴含项
+- 最大化经验覆盖
+- 保留最大信息量
+
+##### 最小解(Minimal Solution)  
+- 使用覆盖表算法
+- 平衡复杂性与解释力
+- 提供多种选择方案
+
+##### 简约解(Parsimonious Solution)
+- 包含逻辑余项
+- 最简表达式
+- 最高理论抽象度
+
+#### 4.3 质量指标
+
+- **覆盖度(Coverage)**：解释的案例比例
+- **一致性(Consistency)**：解释的准确程度  
+- **复杂度(Complexity)**：条件的数量
+- **简约度(Parsimony)**：理论抽象程度
+
+## 📊 结果解释
+
+### 因果路径分析
+
+#### 充分条件
+```
+条件组合 → 结果
+含义：当条件组合出现时，结果必然出现
+```
+
+#### 必要条件
+```
+结果 → 条件
+含义：当结果出现时，条件必然存在
+```
+
+#### 等价条件
+```
+条件 ↔ 结果
+含义：条件与结果同时出现或同时不出现
+```
+
+### 理论贡献
+
+#### 1. 因果复杂性
+- **多重因果**：多种路径导致同一结果
+- **并发因果**：多个条件同时作用
+- **时序因果**：条件的时间顺序影响
+
+#### 2. 异质性分析
+- **案例间差异**：不同案例的不同路径
+- **情境依赖性**：条件效果的情境变化
+- **路径多样性**：实现目标的多种方式
+
+## ⚠️ 方法论限制
+
+### 样本规模限制
+- **最小样本**：至少10-15个案例
+- **条件数量**：不超过案例数量的1/3
+- **案例多样性**：确保案例的理论代表性
+
+### 因果推断限制
+- **相关性vs因果性**：QCA揭示的是关联模式
+- **时间维度**：需要额外设计处理时序关系
+- **外部有效性**：结论的推广范围有限
+
+### 主观性挑战
+- **条件选择**：依赖研究者理论判断
+- **校准阈值**：存在主观设定空间
+- **结果解释**：需要深度理论支撑
+
+## 🛠️ 最佳实践
+
+### 研究设计
+1. **理论先行**：坚实的理论基础
+2. **案例选择**：理论抽样而非随机抽样
+3. **三角验证**：多种方法相互印证
+
+### 数据处理
+1. **数据质量**：确保测量可靠性
+2. **校准透明**：明确校准标准和理由
+3. **稳健性检验**：多种校准方案对比
+
+### 结果报告
+1. **透明度**：完整报告分析过程
+2. **可重复性**：提供详细操作步骤
+3. **理论贡献**：明确理论意义和局限
+
+## 📚 延伸阅读
+
+### 经典文献
+- Ragin, C. C. (2000). *Fuzzy-set Qualitative Comparative Analysis*
+- Schneider, C. Q., & Wagemann, C. (2012). *Set-Theoretic Methods for the Social Sciences*
+- Rihoux, B., & Ragin, C. C. (2009). *Configurational Comparative Methods*
+
+### 方法创新
+- 时序QCA(temporal QCA)
+- 贝叶斯QCA(Bayesian QCA)  
+- 多层QCA(multilevel QCA)
+- 混合方法QCA(mixed-methods QCA)
+
+### 应用领域
+- 政策效果评估
+- 组织绩效研究
+- 社会运动分析
+- 技术创新研究
+- 制度变迁分析

package/skills/msqca-analysis/scripts/calibration.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+多值定性比较分析(msQCA) - 校准模块
+提供多种校准方法和一致性检验功能
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, List, Tuple, Optional, Union
+import warnings
+import math
+from collections import Counter
+
+
+class QCACalibration:
+    """QCA校准类，支持多种校准方法"""
+    
+    def __init__(self):
+        self.calibration_methods = {
+            'direct': self._direct_calibration,
+            'indirect': self._indirect_calibration,
+            'multi_value': self._multi_value_calibration,
+            'auto': self._auto_calibration
+        }
+        self.calibration_results = {}
+        
+    def calibrate_variable(self, 
+                         data: pd.Series, 
+                         method: str = 'direct',
+                         thresholds: Optional[Union[float, List[float]]] = None,
+                         fuzzy_sets: bool = False) -> pd.Series:
+        """
+        校准单个变量
+        
+        Parameters:
+        -----------
+        data : pd.Series
+            原始数据
+        method : str
+            校准方法: 'direct', 'indirect', 'multi_value', 'auto'
+        thresholds : Union[float, List[float], None]
+            校准阈值
+        fuzzy_sets : bool
+            是否使用模糊集校准
+            
+        Returns:
+        --------
+        pd.Series
+            校准后的数据
+        """
+        if method not in self.calibration_methods:
+            raise ValueError(f"不支持的校准方法: {method}")
+            
+        return self.calibration_methods[method](data, thresholds, fuzzy_sets)
+    
+    def _direct_calibration(self, 
+                           data: pd.Series, 
+                           thresholds: Optional[Union[float, List[float]]] = None,
+                           fuzzy_sets: bool = False) -> pd.Series:
+        """
+        直接校准方法
+        
+        基于理论或经验阈值直接将连续变量转换为分类变量
+        """
+        if thresholds is None:
+            # 自动确定阈值
+            thresholds = self._auto_thresholds(data)
+        
+        if isinstance(thresholds, (int, float)):
+            thresholds = [thresholds]
+            
+        if fuzzy_sets:
+            return self._fuzzy_calibration(data, thresholds)
+        else:
+            return pd.cut(data, 
+                         bins=[-np.inf] + thresholds + [np.inf],
+                         labels=range(len(thresholds) + 1),
+                         include_lowest=True)
+    
+    def _indirect_calibration(self, 
+                             data: pd.Series, 
+                             thresholds: Optional[Union[float, List[float]]] = None,
+                             fuzzy_sets: bool = False) -> pd.Series:
+        """
+        间接校准方法
+        
+        通过隶属函数进行渐进式转换
+        """
+        if thresholds is None:
+            thresholds = self._auto_thresholds(data)
+            
+        if isinstance(thresholds, (int, float)):
+            thresholds = [thresholds]
+            
+        calibrated = pd.Series(index=data.index, dtype=float)
+        
+        for i, threshold in enumerate(thresholds):
+            if i == 0:
+                # 第一个阈值以下的区域
+                calibrated[data <= threshold] = 0.0
+            elif i == len(thresholds) - 1:
+                # 最后一个阈值以上的区域
+                calibrated[data > threshold] = 1.0
+            else:
+                # 中间区域使用线性插值
+                prev_threshold = thresholds[i-1]
+                mask = (data > prev_threshold) & (data <= threshold)
+                calibrated[mask] = (data[mask] - prev_threshold) / (threshold - prev_threshold)
+        
+        return calibrated
+    
+    def _multi_value_calibration(self, 
+                                data: pd.Series, 
+                                thresholds: Optional[Union[float, List[float]]] = None,
+                                fuzzy_sets: bool = False) -> pd.Series:
+        """
+        多值校准方法
+        
+        处理具有多个类别的变量
+        """
+        unique_values = sorted(data.unique())
+        
+        if len(unique_values) <= 3:
+            # 如果值较少，使用直接校准
+            return self._direct_calibration(data, thresholds, fuzzy_sets)
+        
+        # 对多值变量进行重新编码
+        value_mapping = {val: i for i, val in enumerate(unique_values)}
+        return data.map(value_mapping)
+    
+    def _auto_calibration(self, 
+                         data: pd.Series, 
+                         thresholds: Optional[Union[float, List[float]]] = None,
+                         fuzzy_sets: bool = False) -> pd.Series:
+        """
+        自动校准方法
+        
+        基于数据分布自动确定最优校准方案
+        """
+        # 检测数据类型和分布特征
+        data_type = self._detect_data_type(data)
+        
+        if data_type == 'categorical':
+            return self._multi_value_calibration(data, thresholds, fuzzy_sets)
+        elif data_type == 'continuous':
+            # 使用分位数确定阈值
+            n_categories = min(3, len(data.unique()) // 3)  # 最多3个类别
+            if n_categories < 2:
+                n_categories = 2
+                
+            quantiles = np.linspace(0, 1, n_categories + 1)[1:-1]
+            auto_thresholds = [data.quantile(q) for q in quantiles]
+            
+            return self._direct_calibration(data, auto_thresholds, fuzzy_sets)
+        else:
+            # 默认使用直接校准
+            return self._direct_calibration(data, thresholds, fuzzy_sets)
+    
+    def _fuzzy_calibration(self, 
+                          data: pd.Series, 
+                          thresholds: List[float]) -> pd.Series:
+        """
+        模糊集校准
+        
+        使用模糊隶属函数进行校准
+        """
+        calibrated = pd.Series(index=data.index, dtype=float)
+        
+        for i, threshold in enumerate(thresholds):
+            if i == 0:
+                # 完全不属于集合
+                calibrated[data <= threshold] = 0.0
+            else:
+                # 使用S型隶属函数
+                prev_threshold = thresholds[i-1]
+                x = data[(data > prev_threshold) & (data <= threshold)]
+                
+                # S型函数参数
+                a = prev_threshold
+                b = threshold
+                c = (a + b) / 2
+                
+                # 计算隶属度
+                membership = 1 / (1 + np.exp(-4 * (x - c) / (b - a)))
+                calibrated[x.index] = membership
+        
+        # 最后一个阈值以上的区域
+        calibrated[data > thresholds[-1]] = 1.0
+        
+        return calibrated
+    
+    def _auto_thresholds(self, data: pd.Series) -> List[float]:
+        """
+        自动确定校准阈值
+
+        基于数据分布特征自动选择最优阈值
+        """
+        # 使用分位数方法
+        q25, q75 = data.quantile([0.25, 0.75])
+        median = data.median()
+
+        # 使用分位数作为阈值
+        thresholds = [q25, median, q75]
+
+        return thresholds[:2]  # 返回最多2个阈值
+    
+    def _detect_data_type(self, data: pd.Series) -> str:
+        """
+        检测数据类型
+        
+        Returns:
+        --------
+        str: 'continuous', 'categorical', 'ordinal'
+        """
+        unique_count = data.nunique()
+        total_count = len(data)
+        
+        # 如果唯一值比例小于10%，认为是分类变量
+        if unique_count / total_count < 0.1:
+            return 'categorical'
+        
+        # 检查是否为有序变量
+        if data.dtype in ['int64', 'float64']:
+            if unique_count <= 10:
+                return 'ordinal'
+            else:
+                return 'continuous'
+        
+        return 'categorical'
+    
+    def validate_calibration(self, 
+                           original_data: pd.Series, 
+                           calibrated_data: pd.Series) -> Dict:
+        """
+        验证校准质量
+        
+        Parameters:
+        -----------
+        original_data : pd.Series
+            原始数据
+        calibrated_data : pd.Series
+            校准后数据
+            
+        Returns:
+        --------
+        Dict
+            验证结果指标
+        """
+        validation_results = {
+            'consistency_score': self._calculate_consistency(original_data, calibrated_data),
+            'coverage_score': self._calculate_coverage(calibrated_data),
+            'information_loss': self._calculate_information_loss(original_data, calibrated_data),
+            'thresholds_used': self._extract_thresholds(original_data, calibrated_data)
+        }
+        
+        return validation_results
+    
+    def _calculate_consistency(self, original: pd.Series, calibrated: pd.Series) -> float:
+        """计算校准一致性分数"""
+        # 这里简化处理，实际应该基于理论一致性
+        orig_unique = len(original.unique())
+        cal_unique = len(calibrated.unique())
+
+        if orig_unique == 0:
+            return 0.0
+
+        consistency = min(1.0, cal_unique / max(1, orig_unique))
+
+        # 确保结果是有效的数值
+        if np.isnan(consistency) or np.isinf(consistency):
+            consistency = 0.0
+
+        return consistency
+    
+    def _calculate_coverage(self, calibrated: pd.Series) -> float:
+        """计算覆盖度分数"""
+        return 1.0 - (calibrated.isna().sum() / len(calibrated))
+    
+    def _calculate_information_loss(self, original: pd.Series, calibrated: pd.Series) -> float:
+        """计算信息损失"""
+        # 使用熵的变化来衡量信息损失
+        orig_entropy = self._calculate_entropy(original)
+        cal_entropy = self._calculate_entropy(calibrated)
+
+        return max(0, orig_entropy - cal_entropy)
+
+    def _calculate_entropy(self, series: pd.Series) -> float:
+        """计算序列的熵值"""
+        # 计算值的频率
+        value_counts = series.value_counts()
+        total_count = len(series)
+
+        if total_count == 0:
+            return 0.0
+
+        # 计算概率分布
+        probabilities = value_counts / total_count
+
+        # 计算熵值 (使用自然对数)
+        entropy = 0.0
+        for prob in probabilities:
+            if prob > 0:  # 避免log(0)的错误
+                entropy -= prob * math.log(prob)
+
+        return entropy
+    
+    def _extract_thresholds(self, original: pd.Series, calibrated: pd.Series) -> List[float]:
+        """提取使用的阈值"""
+        if calibrated.dtype in ['int64', 'float64']:
+            if len(calibrated.unique()) <= 3:
+                return sorted(original.groupby(calibrated).mean().values)
+        return []
+
+
+def main():
+    """示例用法"""
+    # 创建示例数据
+    np.random.seed(42)
+    sample_data = pd.Series(np.random.normal(50, 15, 100))
+    
+    # 初始化校准器
+    calibrator = QCACalibration()
+    
+    # 执行校准
+    calibrated = calibrator.calibrate_variable(sample_data, method='auto')
+    
+    # 验证校准质量
+    validation = calibrator.validate_calibration(sample_data, calibrated)
+    
+    print("原始数据统计:")
+    print(sample_data.describe())
+    print("\n校准后数据分布:")
+    print(calibrated.value_counts().sort_index())
+    print("\n校准验证结果:")
+    for key, value in validation.items():
+        print(f"{key}: {value}")
+
+
+if __name__ == "__main__":
+    main()