aigroup-econ-mcp 1.3.3__py3-none-any.whl → 2.0.1__py3-none-any.whl

econometrics/distribution_analysis/variance_decomposition.py

@@ -0,0 +1,179 @@
+"""
+方差分解 (Variance Decomposition / ANOVA)
+基于 scipy 和 statsmodels 实现
+"""
+
+from typing import List, Optional, Dict
+from pydantic import BaseModel, Field
+import numpy as np
+
+try:
+    from scipy import stats
+    import statsmodels.api as sm
+    from statsmodels.formula.api import ols
+    SCIPY_AVAILABLE = True
+except ImportError:
+    SCIPY_AVAILABLE = False
+    stats = None
+    sm = None
+
+
+class VarianceDecompositionResult(BaseModel):
+    """方差分解结果"""
+    total_variance: float = Field(..., description="总方差")
+    between_group_variance: float = Field(..., description="组间方差")
+    within_group_variance: float = Field(..., description="组内方差")
+    f_statistic: float = Field(..., description="F统计量")
+    p_value: float = Field(..., description="P值")
+    eta_squared: float = Field(..., description="Eta平方（效应量）")
+    omega_squared: float = Field(..., description="Omega平方（偏效应量）")
+    group_means: Dict[str, float] = Field(..., description="各组均值")
+    group_variances: Dict[str, float] = Field(..., description="各组方差")
+    group_sizes: Dict[str, int] = Field(..., description="各组样本量")
+    n_groups: int = Field(..., description="组数")
+    total_n: int = Field(..., description="总样本量")
+    summary: str = Field(..., description="摘要信息")
+
+
+def variance_decomposition(
+    values: List[float],
+    groups: List[str],
+    group_names: Optional[List[str]] = None
+) -> VarianceDecompositionResult:
+    """
+    方差分解 / 单因素ANOVA
+    
+    Args:
+        values: 观测值列表
+        groups: 组别标识列表
+        group_names: 组名称映射
+        
+    Returns:
+        VarianceDecompositionResult: 方差分解结果
+        
+    Raises:
+        ImportError: scipy库未安装
+        ValueError: 输入数据无效
+    """
+    if not SCIPY_AVAILABLE:
+        raise ImportError("scipy和statsmodels库未安装。请运行: pip install scipy statsmodels")
+    
+    # 输入验证
+    if not values or not groups:
+        raise ValueError("values和groups不能为空")
+    
+    if len(values) != len(groups):
+        raise ValueError(f"values长度({len(values)})与groups长度({len(groups)})不一致")
+    
+    # 数据准备
+    y = np.array(values, dtype=np.float64)
+    g = np.array(groups)
+    
+    # 获取唯一组别
+    unique_groups = np.unique(g)
+    n_groups = len(unique_groups)
+    
+    if n_groups < 2:
+        raise ValueError("至少需要2个组进行方差分解")
+    
+    # 计算总体统计量
+    grand_mean = y.mean()
+    total_variance = y.var(ddof=1)
+    total_n = len(y)
+    
+    # 计算各组统计量
+    group_means = {}
+    group_variances = {}
+    group_sizes = {}
+    
+    # 按组分组数据
+    groups_data = []
+    for group_id in unique_groups:
+        mask = g == group_id
+        group_data = y[mask]
+        groups_data.append(group_data)
+        
+        group_key = str(group_id)
+        group_means[group_key] = float(group_data.mean())
+        group_variances[group_key] = float(group_data.var(ddof=1))
+        group_sizes[group_key] = int(len(group_data))
+    
+    # 执行单因素ANOVA
+    f_stat, p_value = stats.f_oneway(*groups_data)
+    
+    # 计算组间方差和组内方差
+    # SS_between = Σnᵢ(ȳᵢ - ȳ)²
+    ss_between = sum(
+        group_sizes[str(gid)] * (group_means[str(gid)] - grand_mean)**2 
+        for gid in unique_groups
+    )
+    
+    # SS_within = Σ(nᵢ - 1)sᵢ²
+    ss_within = sum(
+        (group_sizes[str(gid)] - 1) * group_variances[str(gid)] 
+        for gid in unique_groups
+    )
+   
+    # SS_total
+    ss_total = (total_n - 1) * total_variance
+    
+    # 自由度
+    df_between = n_groups - 1
+    df_within = total_n - n_groups
+    
+    # 均方
+    ms_between = ss_between / df_between
+    ms_within = ss_within / df_within
+    
+    # 组间方差和组内方差（作为总方差的比例）
+    between_group_var = ss_between / (total_n - 1)
+    within_group_var = ss_within / (total_n - 1)
+    
+    # 效应量
+    # Eta平方 = SS_between / SS_total
+    eta_squared = ss_between / ss_total if ss_total > 0 else 0.0
+    
+    # Omega平方（偏效应量）
+    omega_squared = (ss_between - df_between * ms_within) / (ss_total + ms_within)
+    omega_squared = max(0.0, omega_squared)  # 确保非负
+    
+    # 生成摘要
+    summary = f"""方差分解 (ANOVA) 分析:
+- 总样本量: {total_n}
+- 组数: {n_groups}
+- 总方差: {total_variance:.4f}
+
+方差分解:
+- 组间方差: {between_group_var:.4f} ({eta_squared*100:.1f}%)
+- 组内方差: {within_group_var:.4f} ({(1-eta_squared)*100:.1f}%)
+
+F检验:
+- F统计量: {f_stat:.4f}
+- P值: {p_value:.4f}
+- 结论: {'组间差异显著' if p_value < 0.05 else '组间差异不显著'}
+
+效应量:
+- Eta²: {eta_squared:.4f}
+- Omega²: {omega_squared:.4f}
+
+各组均值:
+"""
+    for gid in unique_groups:
+        gkey = str(gid)
+        summary += f"  {gkey}: {group_means[gkey]:.4f} (n={group_sizes[gkey]}, s²={group_variances[gkey]:.4f})\n"
+    
+    return VarianceDecompositionResult(
+        total_variance=float(total_variance),
+        between_group_variance=float(between_group_var),
+        within_group_variance=float(within_group_var),
+        f_statistic=float(f_stat),
+        p_value=float(p_value),
+        eta_squared=float(eta_squared),
+        omega_squared=float(omega_squared),
+        group_means=group_means,
+        group_variances=group_variances,
+        group_sizes=group_sizes,
+        n_groups=n_groups,
+        total_n=total_n,
+        summary=summary
+    )

econometrics/missing_data/__init__.py

@@ -0,0 +1,18 @@
+"""
+缺失数据处理模块
+提供多种插补和处理缺失数据的方法
+"""
+
+from .imputation_methods import (
+    simple_imputation,
+    multiple_imputation,
+    SimpleImputationResult,
+    MultipleImputationResult
+)
+
+__all__ = [
+    'simple_imputation',
+    'multiple_imputation',
+    'SimpleImputationResult',
+    'MultipleImputationResult'
+]

econometrics/missing_data/imputation_methods.py

@@ -0,0 +1,219 @@
+"""
+缺失数据插补方法
+基于 sklearn.impute 实现
+"""
+
+from typing import List, Optional, Dict
+from pydantic import BaseModel, Field
+import numpy as np
+
+try:
+    from sklearn.impute import SimpleImputer, IterativeImputer
+    from sklearn.experimental import enable_iterative_imputer
+    SKLEARN_AVAILABLE = True
+except ImportError:
+    SKLEARN_AVAILABLE = False
+    SimpleImputer = None
+    IterativeImputer = None
+
+
+class SimpleImputationResult(BaseModel):
+    """简单插补结果"""
+    imputed_data: List[List[float]] = Field(..., description="插补后的数据")
+    missing_mask: List[List[bool]] = Field(..., description="缺失值掩码")
+    n_missing: int = Field(..., description="缺失值总数")
+    missing_rate: float = Field(..., description="缺失率")
+    imputation_method: str = Field(..., description="插补方法")
+    fill_values: List[float] = Field(..., description="填充值（每列）")
+    n_observations: int = Field(..., description="观测数量")
+    n_features: int = Field(..., description="特征数量")
+    summary: str = Field(..., description="摘要信息")
+
+
+class MultipleImputationResult(BaseModel):
+    """多重插补结果"""
+    imputed_datasets: List[List[List[float]]] = Field(..., description="多个插补数据集")
+    n_imputations: int = Field(..., description="插补次数")
+    missing_mask: List[List[bool]] = Field(..., description="缺失值掩码")
+    n_missing: int = Field(..., description="缺失值总数")
+    missing_rate: float = Field(..., description="缺失率")
+    convergence_info: Dict = Field(..., description="收敛信息")
+    n_observations: int = Field(..., description="观测数量")
+    n_features: int = Field(..., description="特征数量")
+    summary: str = Field(..., description="摘要信息")
+
+
+def simple_imputation(
+    data: List[List[float]],
+    strategy: str = "mean",
+    fill_value: Optional[float] = None
+) -> SimpleImputationResult:
+    """
+    简单插补方法
+    
+    Args:
+        data: 含缺失值的数据（二维列表，NaN表示缺失）
+        strategy: 插补策略 - "mean"(均值), "median"(中位数), 
+                  "most_frequent"(众数), "constant"(常数)
+        fill_value: 当strategy="constant"时使用的填充值
+        
+    Returns:
+        SimpleImputationResult: 简单插补结果
+        
+    Raises:
+        ImportError: sklearn库未安装
+        ValueError: 输入数据无效
+    """
+    if not SKLEARN_AVAILABLE:
+        raise ImportError("sklearn库未安装。请运行: pip install scikit-learn")
+    
+    # 输入验证
+    if not data:
+        raise ValueError("data不能为空")
+    
+    # 转换为numpy数组
+    X = np.array(data, dtype=np.float64)
+    
+    if X.ndim == 1:
+        X = X.reshape(-1, 1)
+    
+    n, k = X.shape
+    
+    # 创建缺失值掩码
+    missing_mask = np.isnan(X)
+    n_missing = int(missing_mask.sum())
+    missing_rate = float(n_missing / (n * k))
+    
+    # 简单插补
+    if strategy == "constant":
+        if fill_value is None:
+            fill_value = 0.0
+        imputer = SimpleImputer(strategy=strategy, fill_value=fill_value)
+    else:
+        imputer = SimpleImputer(strategy=strategy)
+    
+    # 执行插补
+    X_imputed = imputer.fit_transform(X)
+    
+    # 填充值
+    fill_values = imputer.statistics_.tolist()
+    
+    # 生成摘要
+    summary = f"""简单插补:
+- 观测数量: {n}
+- 特征数量: {k}
+- 缺失值数量: {n_missing}
+- 缺失率: {missing_rate*100:.2f}%
+- 插补策略: {strategy}
+
+各列填充值:
+"""
+    for i, val in enumerate(fill_values):
+        col_missing = int(missing_mask[:, i].sum())
+        summary += f"  列{i+1}: {val:.4f} (缺失{col_missing}个)\n"
+    
+    return SimpleImputationResult(
+        imputed_data=X_imputed.tolist(),
+        missing_mask=missing_mask.tolist(),
+        n_missing=n_missing,
+        missing_rate=missing_rate,
+        imputation_method=strategy,
+        fill_values=fill_values,
+        n_observations=n,
+        n_features=k,
+        summary=summary
+    )
+
+
+def multiple_imputation(
+    data: List[List[float]],
+    n_imputations: int = 5,
+    max_iter: int = 10,
+    random_state: Optional[int] = None
+) -> MultipleImputationResult:
+    """
+    多重插补 (MICE - Multivariate Imputation by Chained Equations)
+    
+    Args:
+        data: 含缺失值的数据
+        n_imputations: 生成的插补数据集数量
+        max_iter: 最大迭代次数
+        random_state: 随机种子
+        
+    Returns:
+        MultipleImputationResult: 多重插补结果
+    """
+    if not SKLEARN_AVAILABLE:
+        raise ImportError("sklearn库未安装")
+    
+    # 输入验证
+    if not data:
+        raise ValueError("data不能为空")
+    
+    X = np.array(data, dtype=np.float64)
+    
+    if X.ndim == 1:
+        X = X.reshape(-1, 1)
+    
+    n, k = X.shape
+    
+    # 缺失值统计
+    missing_mask = np.isnan(X)
+    n_missing = int(missing_mask.sum())
+    missing_rate = float(n_missing / (n * k))
+    
+    # 执行多重插补
+    imputed_datasets = []
+    convergence_info = {"iterations": [], "converged": []}
+    
+    for i in range(n_imputations):
+        # 设置随机种子
+        seed = random_state + i if random_state is not None else None
+        
+        # 创建迭代插补器
+        imputer = IterativeImputer(
+            max_iter=max_iter,
+            random_state=seed,
+            verbose=0
+        )
+        
+        # 执行插补
+        X_imputed = imputer.fit_transform(X)
+        imputed_datasets.append(X_imputed.tolist())
+        
+        # 记录收敛信息
+        convergence_info["iterations"].append(imputer.n_iter_)
+        convergence_info["converged"].append(imputer.n_iter_ < max_iter)
+    
+    # 计算平均收敛迭代数
+    avg_iter = np.mean(convergence_info["iterations"])
+    n_converged = sum(convergence_info["converged"])
+    
+    # 生成摘要
+    summary = f"""多重插补 (MICE):
+- 观测数量: {n}
+- 特征数量: {k}
+- 缺失值数量: {n_missing}
+- 缺失率: {missing_rate*100:.2f}%
+- 插补次数: {n_imputations}
+- 最大迭代: {max_iter}
+
+收敛信息:
+- 平均迭代数: {avg_iter:.1f}
+- 收敛数据集: {n_converged}/{n_imputations}
+
+说明: 生成{n_imputations}个完整的插补数据集，
+可用于后续分析并合并结果（Rubin规则）
+"""
+    
+    return MultipleImputationResult(
+        imputed_datasets=imputed_datasets,
+        n_imputations=n_imputations,
+        missing_mask=missing_mask.tolist(),
+        n_missing=n_missing,
+        missing_rate=missing_rate,
+        convergence_info=convergence_info,
+        n_observations=n,
+        n_features=k,
+        summary=summary
+    )

econometrics/model_specification_diagnostics_robust_inference/README.md

@@ -0,0 +1,173 @@
+# 模型规范、诊断和稳健推断工具
+
+本模块提供了完整的模型规范检验、诊断测试和稳健推断方法工具集。
+
+## 工具列表
+
+### 1. 模型诊断检验 (Model Diagnostic Tests)
+**工具名称**: `model_diagnostic_tests`
+
+**功能**: 执行综合的模型诊断测试，包括：
+- 异方差检验（Breusch-Pagan、White检验）
+- 自相关检验（Durbin-Watson检验）
+- 正态性检验（Jarque-Bera检验）
+- 多重共线性诊断（方差膨胀因子VIF）
+
+**使用场景**: 
+- OLS回归后的模型验证
+- 检测模型假设是否满足
+- 识别数据质量问题
+
+### 2. 广义最小二乘法 (Generalized Least Squares - GLS)
+**工具名称**: `generalized_least_squares`
+
+**功能**: 处理异方差性和自相关的回归方法
+
+**主要特点**:
+- 可指定误差项协方差矩阵
+- 在满足GLS假设时比OLS更有效
+- 适用于存在异方差或自相关的数据
+
+**使用场景**:
+- 时间序列数据回归
+- 存在已知异方差模式的数据
+
+### 3. 加权最小二乘法 (Weighted Least Squares - WLS)
+**工具名称**: `weighted_least_squares`
+
+**功能**: 使用权重处理已知异方差性的回归方法
+
+**主要特点**:
+- 需要提供观测值权重
+- 权重通常为方差的倒数
+- 适用于分组数据或调查数据
+
+**使用场景**:
+- 调查数据分析
+- 分组数据回归
+- 已知误差方差的数据
+
+### 4. 稳健标准误回归 (Robust Standard Errors)
+**工具名称**: `robust_errors_regression`
+
+**功能**: 计算异方差稳健的标准误
+
+**主要特点**:
+- 支持多种协方差矩阵类型（HC0、HC1、HC2、HC3）
+- 不改变系数估计，只调整标准误
+- 在存在异方差时提供有效推断
+
+**使用场景**:
+- 横截面数据分析
+- 异方差问题明显但形式未知
+- 需要稳健推断的场景
+
+### 5. 模型选择准则 (Model Selection Criteria)
+**工具名称**: `model_selection_criteria`
+
+**功能**: 计算多种模型选择信息准则
+
+**提供指标**:
+- AIC（赤池信息准则）
+- BIC（贝叶斯信息准则）
+- HQIC（汉南-奎因信息准则）
+- 交叉验证得分（可选）
+
+**使用场景**:
+- 比较不同模型规格
+- 变量选择
+- 确定最优模型
+
+### 6. 正则化回归 (Regularized Regression)
+**工具名称**: `regularized_regression`
+
+**功能**: 处理多重共线性和高维数据的正则化方法
+
+**支持方法**:
+- 岭回归（Ridge）：L2惩罚
+- LASSO：L1惩罚，可进行变量选择
+- 弹性网络（Elastic Net）：L1和L2的组合
+
+**使用场景**:
+- 高维数据回归
+- 变量选择
+- 处理多重共线性
+
+### 7. 联立方程模型 (Simultaneous Equations Model)
+**工具名称**: `simultaneous_equations_model`
+
+**功能**: 两阶段最小二乘法（2SLS）处理联立方程系统
+
+**主要特点**:
+- 处理内生性问题
+- 需要有效的工具变量
+- 支持多方程系统
+
+**使用场景**:
+- 供需模型
+- 宏观经济模型
+- 存在双向因果关系的模型
+
+## 使用示例
+
+### 诊断检验示例
+```python
+# 使用MCP工具
+{
+  "y_data": [1.0, 2.0, 3.0, 4.0, 5.0],
+  "x_data": [[1.0, 2.0], [2.0, 3.0], [3.0, 4.0], [4.0, 5.0], [5.0, 6.0]],
+  "feature_names": ["x1", "x2"],
+  "constant": true
+}
+```
+
+### 稳健标准误回归示例
+```python
+{
+  "y_data": [1.0, 2.0, 3.0, 4.0, 5.0],
+  "x_data": [[1.0, 2.0], [2.0, 3.0], [3.0, 4.0], [4.0, 5.0], [5.0, 6.0]],
+  "cov_type": "HC1",
+  "confidence_level": 0.95
+}
+```
+
+### 正则化回归示例
+```python
+{
+  "y_data": [1.0, 2.0, 3.0, 4.0, 5.0],
+  "x_data": [[1.0, 2.0], [2.0, 3.0], [3.0, 4.0], [4.0, 5.0], [5.0, 6.0]],
+  "method": "ridge",
+  "alpha": 1.0
+}
+```
+
+## 技术细节
+
+### 实现架构
+- **核心算法**: 位于各子模块的 `*_model.py` 文件
+- **MCP适配器**: `tools/model_specification_adapter.py`
+- **工具注册**: `tools/mcp_tool_groups/model_specification_tools.py`
+
+### 依赖库
+- `statsmodels`: 用于统计模型和诊断检验
+- `scikit-learn`: 用于正则化方法
+- `linearmodels`: 用于联立方程模型
+- `numpy`, `pandas`: 基础数据处理
+
+### 数据格式支持
+- **输入**: JSON、CSV、Excel、TXT
+- **输出**: JSON、Markdown、HTML
+
+## 注意事项
+
+1. **诊断检验**: 应在OLS回归后使用，检验模型假设
+2. **GLS/WLS**: 需要正确指定协方差矩阵或权重
+3. **稳健标准误**: 不改变系数估计，仅影响推断
+4. **正则化**: alpha参数需要通过交叉验证选择
+5. **联立方程**: 需要有效且足够数量的工具变量
+
+## 贡献者
+AIGroup Economics Team
+
+## 许可证
+MIT License

econometrics/model_specification_diagnostics_robust_inference/__init__.py

@@ -0,0 +1,78 @@
+"""
+模型设定、诊断与稳健推断 (Model Specification, Diagnostics and Robust Inference)
+
+当基础模型的理想假设不成立时，修正模型或调整推断；对模型进行诊断和选择。
+
+主要方法包括：
+- 稳健标准误（处理异方差/自相关）
+- 广义最小二乘法 (GLS)
+- 加权最小二乘法 (WLS)
+- 岭回归/LASSO/弹性网络（处理多重共线性/高维数据）
+- 联立方程模型（处理双向因果关系）
+
+模型诊断：
+- 异方差检验（White、Breusch-Pagan）
+- 自相关检验（Durbin-Watson、Ljung-Box）
+- 正态性检验（Jarque-Bera）
+- 多重共线性诊断（VIF）
+- 内生性检验（Durbin-Wu-Hausman）
+- 残差诊断、影响点分析
+
+模型选择：
+- 信息准则（AIC/BIC/HQIC）
+- 交叉验证（K折、留一法）
+- 格兰杰因果检验
+"""
+
+# 导入子模块
+from .robust_errors import (
+    RobustErrorsResult,
+    robust_errors_regression
+)
+
+from .diagnostic_tests import (
+    DiagnosticTestsResult,
+    diagnostic_tests
+)
+
+from .model_selection import (
+    ModelSelectionResult,
+    model_selection_criteria
+)
+
+from .generalized_least_squares import (
+    GLSResult,
+    gls_regression
+)
+
+from .weighted_least_squares import (
+    WLSResult,
+    wls_regression
+)
+
+from .regularization import (
+    RegularizationResult,
+    regularized_regression
+)
+
+from .simultaneous_equations import (
+    SimultaneousEquationsResult,
+    two_stage_least_squares
+)
+
+__all__ = [
+    "RobustErrorsResult",
+    "robust_errors_regression",
+    "DiagnosticTestsResult", 
+    "diagnostic_tests",
+    "ModelSelectionResult",
+    "model_selection_criteria",
+    "GLSResult",
+    "gls_regression",
+    "WLSResult",
+    "wls_regression",
+    "RegularizationResult",
+    "regularized_regression",
+    "SimultaneousEquationsResult",
+    "two_stage_least_squares"
+]

econometrics/model_specification_diagnostics_robust_inference/diagnostic_tests/__init__.py

@@ -0,0 +1,20 @@
+"""
+模型诊断测试 (Diagnostic Tests) 模块
+
+包括各种统计检验方法：
+- 异方差检验（White、Breusch-Pagan）
+- 自相关检验（Durbin-Watson、Ljung-Box）
+- 正态性检验（Jarque-Bera）
+- 多重共线性诊断（VIF）
+- 内生性检验（Durbin-Wu-Hausman）
+"""
+
+from .diagnostic_tests_model import (
+    DiagnosticTestsResult,
+    diagnostic_tests
+)
+
+__all__ = [
+    "DiagnosticTestsResult",
+    "diagnostic_tests"
+]