aigroup-econ-mcp 0.4.2__py3-none-any.whl → 1.4.3__py3-none-any.whl

econometrics/basic_parametric_estimation/mle/__init__.py

@@ -0,0 +1,13 @@
+"""
+最大似然估计 (MLE) 模块
+"""
+
+from .mle_model import (
+    MLEResult,
+    mle_estimation
+)
+
+__all__ = [
+    "MLEResult",
+    "mle_estimation"
+]

econometrics/basic_parametric_estimation/mle/mle_model.py

@@ -0,0 +1,241 @@
+"""
+最大似然估计 (MLE) 模型实现
+"""
+
+from typing import List, Dict, Any, Optional, Callable
+from dataclasses import dataclass
+from pydantic import BaseModel, Field
+import numpy as np
+import pandas as pd
+from scipy.optimize import minimize
+from scipy import stats
+import statsmodels.api as sm
+from statsmodels.base.model import GenericLikelihoodModel
+
+
+class MLEResult(BaseModel):
+    """最大似然估计结果"""
+    parameters: List[float] = Field(..., description="估计参数")
+    std_errors: List[float] = Field(..., description="参数标准误")
+    conf_int_lower: List[float] = Field(..., description="置信区间下界")
+    conf_int_upper: List[float] = Field(..., description="置信区间上界")
+    log_likelihood: float = Field(..., description="对数似然值")
+    aic: float = Field(..., description="赤池信息准则")
+    bic: float = Field(..., description="贝叶斯信息准则")
+    convergence: bool = Field(..., description="是否收敛")
+    n_obs: int = Field(..., description="观测数量")
+    param_names: List[str] = Field(..., description="参数名称")
+
+
+def mle_estimation(
+    data: List[float],
+    distribution: str = "normal",
+    initial_params: Optional[List[float]] = None,
+    confidence_level: float = 0.95
+) -> MLEResult:
+    """
+    最大似然估计
+    
+    Args:
+        data: 数据
+        distribution: 分布类型 ('normal', 'poisson', 'exponential')
+        initial_params: 初始参数值
+        confidence_level: 置信水平
+        
+    Returns:
+        MLEResult: 最大似然估计结果
+        
+    Raises:
+        ValueError: 当输入数据无效时抛出异常
+    """
+    # 输入验证
+    if not data:
+        raise ValueError("数据不能为空")
+    
+    data = np.array(data, dtype=np.float64)
+    n = len(data)
+    
+    # 检查数据有效性
+    if np.isnan(data).any():
+        raise ValueError("数据中包含缺失值(NaN)")
+    
+    if np.isinf(data).any():
+        raise ValueError("数据中包含无穷大值")
+    
+    # 分布特定的验证
+    if distribution == "exponential" and np.any(data < 0):
+        raise ValueError("指数分布的数据必须为非负数")
+    
+    if distribution == "poisson" and (np.any(data < 0) or not np.all(data == np.floor(data))):
+        raise ValueError("泊松分布的数据必须为非负整数")
+    
+    if distribution == "normal":
+        # 正态分布的MLE
+        return _normal_mle(data, initial_params, confidence_level)
+    elif distribution == "poisson":
+        # 泊松分布的MLE
+        return _poisson_mle(data, initial_params, confidence_level)
+    elif distribution == "exponential":
+        # 指数分布的MLE
+        return _exponential_mle(data, initial_params, confidence_level)
+    else:
+        raise ValueError(f"不支持的分布类型: {distribution}")
+
+
+def _normal_mle(data: np.ndarray, initial_params: Optional[List[float]], confidence_level: float) -> MLEResult:
+    """正态分布最大似然估计"""
+    # 使用样本均值和标准差作为初始估计
+    mu_hat = np.mean(data)
+    sigma_hat = np.std(data, ddof=1)  # 使用样本标准差
+    
+    # 检查标准差是否为零
+    if sigma_hat == 0:
+        raise ValueError("数据标准差为零，无法进行正态分布MLE估计")
+    
+    # 使用statsmodels的MLE估计
+    try:
+        # 直接使用解析解
+        n = len(data)
+        log_likelihood = float(np.sum(stats.norm.logpdf(data, loc=mu_hat, scale=sigma_hat)))
+        
+        # 标准误
+        std_error_mu = sigma_hat / np.sqrt(n)
+        std_error_sigma = sigma_hat / np.sqrt(2 * n)
+        std_errors = [std_error_mu, std_error_sigma]
+        
+        # 置信区间
+        alpha = 1 - confidence_level
+        z_value = stats.norm.ppf(1 - alpha/2)
+        conf_int_lower = [mu_hat - z_value * std_error_mu, sigma_hat - z_value * std_error_sigma]
+        conf_int_upper = [mu_hat + z_value * std_error_mu, sigma_hat + z_value * std_error_sigma]
+        
+        # 信息准则
+        k = 2  # 参数数量
+        aic = -2 * log_likelihood + 2 * k
+        bic = -2 * log_likelihood + k * np.log(n)
+        
+        return MLEResult(
+            parameters=[float(mu_hat), float(sigma_hat)],
+            std_errors=std_errors,
+            conf_int_lower=conf_int_lower,
+            conf_int_upper=conf_int_upper,
+            log_likelihood=log_likelihood,
+            aic=float(aic),
+            bic=float(bic),
+            convergence=True,
+            n_obs=n,
+            param_names=["mu", "sigma"]
+        )
+    except Exception as e:
+        raise ValueError(f"正态分布MLE估计失败: {str(e)}")
+
+
+def _poisson_mle(data: np.ndarray, initial_params: Optional[List[float]], confidence_level: float) -> MLEResult:
+    """泊松分布最大似然估计"""
+    # 泊松分布的MLE有解析解：lambda_hat = mean(data)
+    lambda_hat = np.mean(data)
+    n = len(data)
+    
+    # 检查均值是否为零
+    if lambda_hat == 0:
+        raise ValueError("数据均值为零，无法进行泊松分布MLE估计")
+    
+    try:
+        # 计算对数似然值
+        log_likelihood = float(np.sum(stats.poisson.logpmf(data, lambda_hat)))
+        
+        # 标准误
+        std_error = np.sqrt(lambda_hat / n)
+        std_errors = [std_error]
+        
+        # 置信区间
+        alpha = 1 - confidence_level
+        z_value = stats.norm.ppf(1 - alpha/2)
+        conf_int_lower = [lambda_hat - z_value * std_error]
+        conf_int_upper = [lambda_hat + z_value * std_error]
+        
+        # 信息准则
+        k = 1  # 参数数量
+        aic = -2 * log_likelihood + 2 * k
+        bic = -2 * log_likelihood + k * np.log(n)
+        
+        return MLEResult(
+            parameters=[float(lambda_hat)],
+            std_errors=std_errors,
+            conf_int_lower=conf_int_lower,
+            conf_int_upper=conf_int_upper,
+            log_likelihood=log_likelihood,
+            aic=float(aic),
+            bic=float(bic),
+            convergence=True,
+            n_obs=n,
+            param_names=["lambda"]
+        )
+    except Exception as e:
+        raise ValueError(f"泊松分布MLE估计失败: {str(e)}")
+
+
+def _exponential_mle(data: np.ndarray, initial_params: Optional[List[float]], confidence_level: float) -> MLEResult:
+    """指数分布最大似然估计"""
+    # 指数分布的MLE有解析解：lambda_hat = 1 / mean(data)
+    mean_data = np.mean(data)
+    if mean_data <= 0:
+        raise ValueError("指数分布的数据均值必须为正数")
+    
+    lambda_hat = 1.0 / mean_data
+    n = len(data)
+    
+    # 检查参数有效性
+    if not np.isfinite(lambda_hat):
+        raise ValueError("计算出的参数值无效")
+    
+    try:
+        # 计算对数似然值
+        log_likelihood = float(np.sum(stats.expon.logpdf(data, scale=1/lambda_hat)))
+        
+        # 标准误计算 (对于指数分布，标准误为lambda/sqrt(n))
+        # 使用更精确的计算方法
+        std_error = lambda_hat / np.sqrt(n)
+        std_errors = [std_error]
+        
+        # 验证标准误的有效性
+        if not np.isfinite(std_error) or std_error <= 0:
+            raise ValueError("计算出的标准误无效")
+        
+        # 置信区间
+        alpha = 1 - confidence_level
+        z_value = stats.norm.ppf(1 - alpha/2)
+        
+        # 检查z值有效性
+        if not np.isfinite(z_value):
+            raise ValueError("计算出的临界值无效")
+            
+        conf_int_lower = [lambda_hat - z_value * std_error]
+        conf_int_upper = [lambda_hat + z_value * std_error]
+        
+        # 检查置信区间边界有效性
+        if not (np.isfinite(conf_int_lower[0]) and np.isfinite(conf_int_upper[0])):
+            raise ValueError("计算出的置信区间无效")
+            
+        # 确保置信区间下限不为负
+        conf_int_lower[0] = max(conf_int_lower[0], 1e-10)
+        
+        # 信息准则
+        k = 1  # 参数数量
+        aic = -2 * log_likelihood + 2 * k
+        bic = -2 * log_likelihood + k * np.log(n)
+        
+        return MLEResult(
+            parameters=[float(lambda_hat)],
+            std_errors=std_errors,
+            conf_int_lower=conf_int_lower,
+            conf_int_upper=conf_int_upper,
+            log_likelihood=log_likelihood,
+            aic=float(aic),
+            bic=float(bic),
+            convergence=True,
+            n_obs=n,
+            param_names=["lambda"]
+        )
+    except Exception as e:
+        raise ValueError(f"指数分布MLE估计失败: {str(e)}")

econometrics/basic_parametric_estimation/ols/__init__.py

@@ -0,0 +1,13 @@
+"""
+普通最小二乘法 (OLS) 模块
+"""
+
+from .ols_model import (
+    OLSResult,
+    ols_regression
+)
+
+__all__ = [
+    "OLSResult",
+    "ols_regression"
+]

econometrics/basic_parametric_estimation/ols/ols_model.py

@@ -0,0 +1,141 @@
+"""
+普通最小二乘法 (OLS) 模型实现
+"""
+
+from typing import List, Dict, Any, Optional, Union
+from dataclasses import dataclass
+from pydantic import BaseModel, Field
+import numpy as np
+import pandas as pd
+from scipy import stats
+import statsmodels.api as sm
+
+
+class OLSResult(BaseModel):
+    """OLS回归结果"""
+    coefficients: List[float] = Field(..., description="回归系数")
+    std_errors: List[float] = Field(..., description="系数标准误")
+    t_values: List[float] = Field(..., description="t统计量")
+    p_values: List[float] = Field(..., description="p值")
+    conf_int_lower: List[float] = Field(..., description="置信区间下界")
+    conf_int_upper: List[float] = Field(..., description="置信区间上界")
+    r_squared: float = Field(..., description="R方")
+    adj_r_squared: float = Field(..., description="调整R方")
+    f_statistic: float = Field(..., description="F统计量")
+    f_p_value: float = Field(..., description="F统计量p值")
+    aic: float = Field(..., description="赤池信息准则")
+    bic: float = Field(..., description="贝叶斯信息准则")
+    n_obs: int = Field(..., description="观测数量")
+    feature_names: List[str] = Field(..., description="特征名称")
+
+
+def ols_regression(
+    y_data: List[float],
+    x_data: List[List[float]], 
+    feature_names: Optional[List[str]] = None,
+    constant: bool = True,
+    confidence_level: float = 0.95
+) -> OLSResult:
+    """
+    普通最小二乘法回归
+    
+    Args:
+        y_data: 因变量数据
+        x_data: 自变量数据
+        feature_names: 特征名称
+        constant: 是否包含常数项
+        confidence_level: 置信水平
+        
+    Returns:
+        OLSResult: OLS回归结果
+        
+    Raises:
+        ValueError: 当输入数据无效时抛出异常
+    """
+    # 输入验证
+    if not y_data or not x_data:
+        raise ValueError("因变量和自变量数据不能为空")
+    
+    # 转换为numpy数组
+    y = np.array(y_data, dtype=np.float64)
+    
+    # 确保X是二维数组
+    if x_data and isinstance(x_data[0], (int, float)):
+        # 单个特征的情况，需要转置
+        X = np.array(x_data, dtype=np.float64).reshape(-1, 1)
+    else:
+        X = np.array(x_data, dtype=np.float64)
+    
+    # 验证数据维度一致性
+    if len(y) != X.shape[0]:
+        raise ValueError(f"因变量长度({len(y)})与自变量长度({X.shape[0]})不一致")
+    
+    # 检查是否有足够的数据点
+    if len(y) < X.shape[1] + (1 if constant else 0):
+        raise ValueError("数据点数量不足以估计模型参数")
+    
+    # 检查是否存在缺失值或无穷大值
+    if np.isnan(y).any() or np.isnan(X).any():
+        raise ValueError("数据中包含缺失值(NaN)")
+    
+    if np.isinf(y).any() or np.isinf(X).any():
+        raise ValueError("数据中包含无穷大值")
+    
+    # 添加常数项
+    if constant:
+        X = sm.add_constant(X)
+        if feature_names:
+            feature_names = ["const"] + feature_names
+        else:
+            feature_names = ["const"] + [f"x{i}" for i in range(X.shape[1]-1)]
+    else:
+        if not feature_names:
+            feature_names = [f"x{i}" for i in range(X.shape[1])]
+    
+    # 使用statsmodels执行OLS回归
+    try:
+        model = sm.OLS(y, X)
+        results = model.fit()
+    except Exception as e:
+        raise ValueError(f"无法拟合OLS模型: {str(e)}")
+    
+    # 提取结果
+    coefficients = results.params.tolist()
+    std_errors = results.bse.tolist()
+    t_values = results.tvalues.tolist()
+    p_values = results.pvalues.tolist()
+    
+    # 计算置信区间
+    alpha = 1 - confidence_level
+    conf_int = results.conf_int(alpha=alpha)
+    conf_int_lower = conf_int[:, 0].tolist()
+    conf_int_upper = conf_int[:, 1].tolist()
+    
+    # 其他统计量
+    r_squared = float(results.rsquared)
+    adj_r_squared = float(results.rsquared_adj)
+    
+    # F统计量
+    f_statistic = float(results.fvalue) if not np.isnan(results.fvalue) else 0.0
+    f_p_value = float(results.f_pvalue) if not np.isnan(results.f_pvalue) else 1.0
+    
+    # 信息准则
+    aic = float(results.aic)
+    bic = float(results.bic)
+    
+    return OLSResult(
+        coefficients=coefficients,
+        std_errors=std_errors,
+        t_values=t_values,
+        p_values=p_values,
+        conf_int_lower=conf_int_lower,
+        conf_int_upper=conf_int_upper,
+        r_squared=r_squared,
+        adj_r_squared=adj_r_squared,
+        f_statistic=f_statistic,
+        f_p_value=f_p_value,
+        aic=aic,
+        bic=bic,
+        n_obs=int(results.nobs),
+        feature_names=feature_names
+    )

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"
+]