ssci-subagent-skills 1.0.0

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

@@ -0,0 +1,438 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+多值定性比较分析(msQCA) - 真值表构建模块
+提供真值表生成、逻辑余项识别和矛盾组合处理功能
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, List, Tuple, Optional, Union, Set
+import itertools
+from collections import defaultdict, Counter
+import warnings
+
+
+class TruthTableBuilder:
+    """QCA真值表构建类"""
+    
+    def __init__(self):
+        self.truth_table = None
+        self.logical_remainders = []
+        self.contradictory_cases = []
+        self.consistency_scores = {}
+        
+    def build_truth_table(self, 
+                         data: pd.DataFrame, 
+                         conditions: List[str], 
+                         outcome: str,
+                         outcome_threshold: float = 0.8) -> pd.DataFrame:
+        """
+        构建真值表
+        
+        Parameters:
+        -----------
+        data : pd.DataFrame
+            校准后的数据
+        conditions : List[str]
+            条件变量列表
+        outcome : str
+            结果变量
+        outcome_threshold : float
+            结果一致性阈值
+            
+        Returns:
+        --------
+        pd.DataFrame
+            构建的真值表
+        """
+        # 按条件组合分组
+        grouped = data.groupby(conditions)
+        
+        truth_table_data = []
+        
+        for condition_combo, group in grouped:
+            # 计算每个组合的一致性
+            consistency = self._calculate_consistency(group[outcome], outcome_threshold)
+            
+            # 计算案例数量
+            n_cases = len(group)
+            
+            # 识别结果类型
+            if consistency >= outcome_threshold:
+                result_type = 1  # 正面结果
+            elif consistency <= (1 - outcome_threshold):
+                result_type = 0  # 负面结果
+            else:
+                result_type = -1  # 矛盾结果
+            
+            row_data = {
+                'condition_combo': condition_combo if len(conditions) > 1 else [condition_combo],
+                'consistency': consistency,
+                'n_cases': n_cases,
+                'result_type': result_type,
+                'cases': group.index.tolist()
+            }
+            
+            # 添加条件列
+            if len(conditions) == 1:
+                row_data[conditions[0]] = condition_combo
+            else:
+                for i, condition in enumerate(conditions):
+                    row_data[condition] = condition_combo[i]
+            
+            truth_table_data.append(row_data)
+        
+        self.truth_table = pd.DataFrame(truth_table_data)
+        
+        # 识别逻辑余项和矛盾组合
+        self._identify_logical_remainders(conditions)
+        self._identify_contradictory_cases()
+        
+        return self.truth_table
+    
+    def _calculate_consistency(self, outcome_values: pd.Series, threshold: float) -> float:
+        """
+        计算一致性分数
+
+        Parameters:
+        -----------
+        outcome_values : pd.Series
+            结果变量值
+        threshold : float
+            阈值
+
+        Returns:
+        --------
+        float
+            一致性分数
+        """
+        if len(outcome_values) == 0 or outcome_values.isna().all():
+            return 0.0
+
+        # 计算达到阈值的案例比例
+        consistent_cases = (outcome_values >= threshold).sum()
+        total_cases = len(outcome_values.dropna())  # 只考虑非空值
+
+        consistency = consistent_cases / total_cases if total_cases > 0 else 0.0
+
+        # 确保结果是有效的数值
+        if np.isnan(consistency) or np.isinf(consistency):
+            consistency = 0.0
+
+        return consistency
+    
+    def _identify_logical_remainders(self, conditions: List[str]):
+        """
+        识别逻辑余项（未观察到的条件组合）
+        
+        Parameters:
+        -----------
+        conditions : List[str]
+            条件变量列表
+        """
+        if self.truth_table is None:
+            return
+        
+        # 获取每个条件的所有可能值
+        condition_values = {}
+        for condition in conditions:
+            unique_values = sorted(self.truth_table[condition].unique())
+            condition_values[condition] = unique_values
+        
+        # 生成所有可能的组合
+        all_combinations = list(itertools.product(*[
+            condition_values[condition] for condition in conditions
+        ]))
+        
+        # 获取已观察到的组合
+        observed_combinations = set()
+        for _, row in self.truth_table.iterrows():
+            if len(conditions) == 1:
+                combo = (row[conditions[0]],)
+            else:
+                combo = tuple(row[condition] for condition in conditions)
+            observed_combinations.add(combo)
+        
+        # 识别逻辑余项
+        self.logical_remainders = [
+            combo for combo in all_combinations 
+            if combo not in observed_combinations
+        ]
+    
+    def _identify_contradictory_cases(self):
+        """识别矛盾组合"""
+        if self.truth_table is None:
+            return
+        
+        contradictory_rows = self.truth_table[
+            self.truth_table['result_type'] == -1
+        ]
+        
+        self.contradictory_cases = contradictory_rows.to_dict('records')
+    
+    def handle_contradictions(self, 
+                            method: str = 'remove',
+                            consistency_threshold: float = 0.6) -> pd.DataFrame:
+        """
+        处理矛盾组合
+        
+        Parameters:
+        -----------
+        method : str
+            处理方法: 'remove', 'recode', 'split'
+        consistency_threshold : float
+            一致性阈值
+            
+        Returns:
+        --------
+        pd.DataFrame
+            处理后的真值表
+        """
+        if self.truth_table is None or len(self.contradictory_cases) == 0:
+            return self.truth_table
+        
+        if method == 'remove':
+            # 移除矛盾组合
+            filtered_table = self.truth_table[
+                self.truth_table['result_type'] != -1
+            ].copy()
+            
+        elif method == 'recode':
+            # 重新编码为最接近的结果类型
+            filtered_table = self.truth_table.copy()
+            for idx, row in self.contradictory_cases:
+                if row['consistency'] >= consistency_threshold:
+                    filtered_table.loc[idx, 'result_type'] = 1
+                else:
+                    filtered_table.loc[idx, 'result_type'] = 0
+                    
+        elif method == 'split':
+            # 分裂矛盾组合为正负两种结果
+            new_rows = []
+            for idx, row in self.contradictory_cases:
+                # 创建正面结果行
+                pos_row = row.copy()
+                pos_row['result_type'] = 1
+                pos_row['n_cases'] = int(row['n_cases'] * row['consistency'])
+                new_rows.append(pos_row)
+                
+                # 创建负面结果行
+                neg_row = row.copy()
+                neg_row['result_type'] = 0
+                neg_row['n_cases'] = int(row['n_cases'] * (1 - row['consistency']))
+                new_rows.append(neg_row)
+            
+            # 移除原始矛盾行并添加新行
+            filtered_table = self.truth_table[
+                self.truth_table['result_type'] != -1
+            ].copy()
+            filtered_table = pd.concat([filtered_table, pd.DataFrame(new_rows)], 
+                                     ignore_index=True)
+        else:
+            raise ValueError(f"不支持的矛盾处理方法: {method}")
+        
+        self.truth_table = filtered_table
+        return self.truth_table
+    
+    def add_logical_remainders(self, 
+                             method: str = 'all',
+                             consistency: float = 0.0) -> pd.DataFrame:
+        """
+        添加逻辑余项到真值表
+        
+        Parameters:
+        -----------
+        method : str
+            添加方法: 'all', 'positive', 'negative'
+        consistency : float
+            逻辑余项的一致性分数
+            
+        Returns:
+        --------
+        pd.DataFrame
+            包含逻辑余项的真值表
+        """
+        if self.truth_table is None:
+            return pd.DataFrame()
+        
+        new_rows = []
+        
+        for combo in self.logical_remainders:
+            # 确定结果类型
+            if method == 'all':
+                result_type = -1  # 逻辑余项
+            elif method == 'positive':
+                result_type = 1
+            elif method == 'negative':
+                result_type = 0
+            else:
+                raise ValueError(f"不支持的逻辑余项添加方法: {method}")
+            
+            # 创建新行
+            row_data = {
+                'condition_combo': combo,
+                'consistency': consistency,
+                'n_cases': 0,  # 逻辑余项没有实际案例
+                'result_type': result_type,
+                'cases': []
+            }
+            
+            # 添加条件列
+            for i, condition in enumerate(self.get_condition_columns()):
+                row_data[condition] = combo[i]
+            
+            new_rows.append(row_data)
+        
+        # 添加到真值表
+        if new_rows:
+            extended_table = pd.concat([self.truth_table, pd.DataFrame(new_rows)], 
+                                     ignore_index=True)
+        else:
+            extended_table = self.truth_table.copy()
+        
+        return extended_table
+    
+    def get_condition_columns(self) -> List[str]:
+        """获取条件变量列名"""
+        if self.truth_table is None:
+            return []
+        
+        # 排除非条件列
+        exclude_columns = {
+            'condition_combo', 'consistency', 'n_cases', 
+            'result_type', 'cases'
+        }
+        
+        condition_columns = [
+            col for col in self.truth_table.columns 
+            if col not in exclude_columns
+        ]
+        
+        return condition_columns
+    
+    def calculate_quality_metrics(self) -> Dict:
+        """
+        计算真值表质量指标
+
+        Returns:
+        --------
+        Dict
+            质量指标字典
+        """
+        if self.truth_table is None:
+            return {}
+
+        # 安全计算各项指标
+        total_cases = self.truth_table['n_cases'].sum() if 'n_cases' in self.truth_table.columns else 0
+        positive_cases = 0
+        negative_cases = 0
+        contradictory_cases = 0
+
+        if 'result_type' in self.truth_table.columns and 'n_cases' in self.truth_table.columns:
+            positive_cases = self.truth_table[
+                self.truth_table['result_type'] == 1
+            ]['n_cases'].sum()
+            negative_cases = self.truth_table[
+                self.truth_table['result_type'] == 0
+            ]['n_cases'].sum()
+            contradictory_cases = self.truth_table[
+                self.truth_table['result_type'] == -1
+            ]['n_cases'].sum()
+
+        # 计算矛盾率和覆盖度，避免除零错误
+        contradiction_rate = contradictory_cases / total_cases if total_cases > 0 else 0
+        coverage = (positive_cases + negative_cases) / total_cases if total_cases > 0 else 0
+
+        metrics = {
+            'total_cases': total_cases,
+            'positive_cases': positive_cases,
+            'negative_cases': negative_cases,
+            'contradictory_cases': contradictory_cases,
+            'contradiction_rate': contradiction_rate,
+            'coverage': coverage,
+            'logical_remainders_count': len(self.logical_remainders),
+            'unique_combinations': len(self.truth_table) if self.truth_table is not None else 0
+        }
+
+        return metrics
+    
+    def export_truth_table(self, 
+                          filename: str,
+                          format: str = 'csv') -> bool:
+        """
+        导出真值表
+        
+        Parameters:
+        -----------
+        filename : str
+            文件名
+        format : str
+            导出格式: 'csv', 'excel', 'json'
+            
+        Returns:
+        --------
+        bool
+            导出是否成功
+        """
+        if self.truth_table is None:
+            return False
+        
+        try:
+            if format == 'csv':
+                self.truth_table.to_csv(filename, index=False, encoding='utf-8')
+            elif format == 'excel':
+                self.truth_table.to_excel(filename, index=False)
+            elif format == 'json':
+                self.truth_table.to_json(filename, orient='records', force_ascii=False, indent=2)
+            else:
+                raise ValueError(f"不支持的导出格式: {format}")
+            
+            return True
+        except Exception as e:
+            print(f"导出失败: {e}")
+            return False
+
+
+def main():
+    """示例用法"""
+    # 创建示例数据
+    np.random.seed(42)
+    n_cases = 100
+    
+    data = pd.DataFrame({
+        'A': np.random.choice([0, 1, 2], n_cases),
+        'B': np.random.choice([0, 1, 2], n_cases),
+        'C': np.random.choice([0, 1, 2], n_cases),
+        'Y': np.random.uniform(0, 1, n_cases)
+    })
+    
+    # 初始化真值表构建器
+    builder = TruthTableBuilder()
+    
+    # 构建真值表
+    truth_table = builder.build_truth_table(
+        data=data,
+        conditions=['A', 'B', 'C'],
+        outcome='Y',
+        outcome_threshold=0.8
+    )
+    
+    print("真值表:")
+    print(truth_table[['A', 'B', 'C', 'consistency', 'n_cases', 'result_type']].head(10))
+    
+    # 处理矛盾组合
+    filtered_table = builder.handle_contradictions(method='remove')
+    print(f"\n移除矛盾组合后: {len(filtered_table)} 行")
+    
+    # 计算质量指标
+    metrics = builder.calculate_quality_metrics()
+    print("\n质量指标:")
+    for key, value in metrics.items():
+        print(f"{key}: {value}")
+    
+    print(f"\n逻辑余项数量: {len(builder.logical_remainders)}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/network-computation/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: network-computation
+description: 社会网络计算分析工具，提供网络构建、中心性测量、社区检测、网络可视化等完整的网络分析支持
+version: 1.0.0
+author: socienceAI.com
+tags: [network-analysis, social-networks, centrality, community-detection, visualization]
+---
+
+# Network Computation Analysis Skill
+
+## Overview
+社会网络计算分析技能为社会科学研究提供全面的网络分析支持，包括网络构建、中心性测量、社区检测、网络可视化等，帮助研究者深入理解社会关系结构和动态。
+
+## When to Use This Skill
+Use this skill when the user requests:
+- Social network analysis of relationships
+- Network construction from relational data
+- Centrality analysis (degree, betweenness, closeness, eigenvector)
+- Community detection and clustering
+- Network visualization and mapping
+- Structural hole analysis
+- Brokerage and mediation analysis
+- Network density and cohesion measures
+- Network evolution and change analysis
+- Two-mode network analysis
+
+## Quick Start
+When a user requests network analysis:
+1. **Prepare** network data in appropriate format
+2. **Construct** the network from relational data
+3. **Analyze** key properties (centrality, communities, etc.)
+4. **Visualize** the network structure
+5. **Interpret** findings in social context
+
+## 脚本调用时机
+当需要执行网络计算分析时，调用 `calculate_centrality.py` 脚本，该脚本整合了网络分析的主要功能。
+
+## 输入格式
+```json
+{
+  "network_data": {
+    "nodes": [
+      {
+        "id": "节点唯一ID",
+        "label": "节点标签",
+        "attributes": {
+          "type": "节点类型",
+          "size": "节点大小",
+          "group": "节点分组"
+        }
+      }
+    ],
+    "edges": [
+      {
+        "source": "源节点ID",
+        "target": "目标节点ID",
+        "weight": "边权重",
+        "type": "边类型",
+        "attributes": {
+          "strength": "关系强度",
+          "direction": "方向性"
+        }
+      }
+    ]
+  },
+  "analysis_parameters": {
+    "network_type": "directed/undirected",
+    "is_weighted": true,
+    "centrality_metrics": ["degree", "betweenness", "closeness", "eigenvector"],
+    "community_method": "louvain/modularity/greedy",
+    "visualization_type": "static/interactive",
+    "node_attributes": ["type", "size", "group"],
+    "edge_attributes": ["weight", "strength", "direction"]
+  },
+  "analysis_context": "分析背景和目的",
+  "research_questions": ["研究问题列表"]
+}
+```
+
+## 输出格式
+```json
+{
+  "summary": {
+    "network_size": "网络规模（节点数）",
+    "network_density": "网络密度",
+    "connected_components": "连通分量数",
+    "analysis_time": "分析耗时"
+  },
+  "details": {
+    "network_metrics": {
+      "density": "网络密度",
+      "clustering_coefficient": "聚类系数",
+      "average_path_length": "平均路径长度",
+      "diameter": "网络直径",
+      "components": {
+        "number_of_components": "连通分量数",
+        "largest_component_size": "最大连通分量规模"
+      }
+    },
+    "centrality_analysis": {
+      "degree_centrality": {
+        "node_id": "中心度值"
+      },
+      "betweenness_centrality": {
+        "node_id": "中心度值"
+      },
+      "closeness_centrality": {
+        "node_id": "中心度值"
+      },
+      "eigenvector_centrality": {
+        "node_id": "中心度值"
+      },
+      "top_nodes_by_centrality": {
+        "degree": ["按度中心度排序的节点"],
+        "betweenness": ["按中介中心度排序的节点"],
+        "closeness": ["按接近中心度排序的节点"],
+        "eigenvector": ["按特征向量中心度排序的节点"]
+      }
+    },
+    "community_detection": {
+      "number_of_communities": "社区数量",
+      "communities": [
+        {
+          "id": "社区ID",
+          "size": "社区规模",
+          "nodes": ["节点列表"],
+          "modularity": "模块度值",
+          "description": "社区描述"
+        }
+      ],
+      "node_to_community": {
+        "node_id": "社区ID"
+      }
+    },
+    "structural_analysis": {
+      "structural_holes": ["结构洞分析结果"],
+      "bridges": ["桥接节点"],
+      "brokerage_roles": ["中介角色"]
+    }
+  },
+  "visualization": {
+    "static_image": "静态图像链接",
+    "interactive_graph": "交互图链接",
+    "layout": "布局类型",
+    "color_scheme": "配色方案"
+  },
+  "interpretation": {
+    "key_findings": ["关键发现"],
+    "social_interpretation": "社会学解释",
+    "research_insights": ["研究洞察"]
+  }
+  },
+  "metadata": {
+    "timestamp": "时间戳",
+    "version": "版本号",
+    "skill": "network-computation",
+    "analysis_parameters": "分析参数"
+  }
+}
+```
+
+## Core Functions (Progressive Disclosure)
+
+### Primary Functions
+- **Network Construction**: Create networks from edgelist or matrix data
+- **Centrality Analysis**: Calculate degree, betweenness, and closeness centrality
+- **Basic Visualization**: Generate network diagrams with standard layouts
+- **Network Metrics**: Compute density, clustering coefficient, path length
+
+### Secondary Functions
+- **Community Detection**: Identify clusters using modularity-based methods
+- **Advanced Centrality**: Calculate eigenvector centrality, PageRank
+- **Structural Analysis**: Identify structural holes, components
+- **Interactive Visualization**: Create interactive network diagrams
+
+### Advanced Functions
+- **Multi-layer Networks**: Handle networks with multiple relationship types
+- **Dynamic Networks**: Analyze network evolution over time
+- **Two-mode Networks**: Handle bipartite network structures
+- **Advanced Layouts**: Use specialized layout algorithms for large networks
+
+## Detailed Instructions
+
+### 1. Network Data Preparation
+   - Validate network data format (edgelist, adjacency matrix, etc.)
+   - Clean and preprocess relational data
+   - Identify and handle missing or anomalous connections
+   - Determine appropriate network type (directed/undirected, weighted/unweighted)
+
+### 2. Network Construction
+   - Create network object from data
+   - Validate network properties (connectedness, size, etc.)
+   - Compute basic network metrics (nodes, edges, density)
+   - Visualize initial network structure
+
+### 3. Centrality Analysis
+   - Calculate multiple centrality measures
+   - Rank nodes by different centrality indicators
+   - Identify key players, bridges, and influencers
+   - Interpret centrality in social context
+
+### 4. Community Detection
+   - Apply appropriate clustering algorithms
+   - Validate community structure
+   - Analyze inter-community relationships
+   - Interpret community meaning in social context
+
+### 5. Network Visualization
+   - Create clear, informative network diagrams
+   - Use visual attributes to highlight important features
+   - Generate publication-quality figures
+   - Provide interactive visualization when appropriate
+
+### 6. Interpretation and Reporting
+   - Explain findings in social science terms
+   - Connect network properties to research questions
+   - Consider Chinese social context (guanxi, mianzi, etc.)
+   - Provide actionable insights
+
+## Parameters
+- `network_format`: Input format (edgelist, adjacency matrix, JSON, etc.)
+- `directed`: Whether the network is directed (default: false)
+- `weighted`: Whether the network is weighted (default: true)
+- `centrality_metrics`: List of centrality measures to compute
+- `community_method`: Community detection algorithm to use
+- `visualization_type`: Type of visualization (static, interactive)
+- `node_attributes`: Additional node properties to visualize
+- `edge_attributes`: Additional edge properties to visualize
+
+## Examples
+
+### Example 1: Centrality Analysis
+User: "Analyze this social network and identify the most important actors"
+Response: Calculate all centrality measures, identify key nodes, interpret in social context.
+
+### Example 2: Community Detection
+User: "Find communities within this organization's communication network"
+Response: Apply community detection algorithms, validate structure, interpret meaning.
+
+### Example 3: Network Visualization
+User: "Create a visualization of this collaboration network"
+Response: Generate network diagram with appropriate layout, highlight important nodes.
+
+## Quality Assurance
+
+- Verify network data integrity before analysis
+- Use multiple algorithms when possible for validation
+- Consider social context in interpretation
+- Ensure visualizations are clear and informative
+- Validate community detection results
+
+## Output Format
+
+- Complete network analysis report
+- Standardized network metrics tables
+- Network visualization files (PNG, SVG, interactive HTML)
+- Network data files in various formats
+- Reproducible analysis code
+
+## Resources
+- Social network analysis best practices
+- Network visualization guidelines
+- Community detection algorithm comparisons
+- Chinese social network characteristics (guanxi, etc.)
+- Python toolkit: `skills/network-computation/scripts/calculate_centrality.py`
+
+## Metadata
+- Compatibility: Claude 3.5 Sonnet and above
+- Domain: Social Network Analysis
+- Language: Optimized for Chinese research context