aigroup-econ-mcp 0.1.5__py3-none-any.whl → 0.2.0__py3-none-any.whl

aigroup_econ_mcp/tools/panel_data.py

@@ -0,0 +1,527 @@
+
+"""
+面板数据分析工具
+"""
+
+import numpy as np
+import pandas as pd
+import statsmodels.api as sm
+from linearmodels import PanelOLS, RandomEffects
+from typing import List, Dict, Any, Optional, Tuple
+from pydantic import BaseModel, Field
+import warnings
+
+
+class PanelDataResult(BaseModel):
+    """面板数据模型结果基类"""
+    rsquared: float = Field(description="R²")
+    rsquared_adj: float = Field(description="调整R²")
+    f_statistic: float = Field(description="F统计量")
+    f_pvalue: float = Field(description="F检验p值")
+    aic: float = Field(description="AIC信息准则")
+    bic: float = Field(description="BIC信息准则")
+    n_obs: int = Field(description="观测数量")
+    coefficients: Dict[str, Dict[str, float]] = Field(description="回归系数详情")
+
+
+class FixedEffectsResult(PanelDataResult):
+    """固定效应模型结果"""
+    entity_effects: bool = Field(description="是否包含个体效应")
+    time_effects: bool = Field(description="是否包含时间效应")
+    within_rsquared: float = Field(description="组内R²")
+
+
+class RandomEffectsResult(PanelDataResult):
+    """随机效应模型结果"""
+    entity_effects: bool = Field(description="是否包含个体效应")
+    time_effects: bool = Field(description="是否包含时间效应")
+    between_rsquared: float = Field(description="组间R²")
+
+
+class HausmanTestResult(BaseModel):
+    """Hausman检验结果"""
+    statistic: float = Field(description="检验统计量")
+    p_value: float = Field(description="p值")
+    significant: bool = Field(description="是否显著(5%水平)")
+    recommendation: str = Field(description="模型选择建议")
+
+
+class PanelUnitRootResult(BaseModel):
+    """面板单位根检验结果"""
+    statistic: float = Field(description="检验统计量")
+    p_value: float = Field(description="p值")
+    stationary: bool = Field(description="是否平稳")
+    test_type: str = Field(description="检验类型")
+
+
+def prepare_panel_data(
+    y_data: List[float],
+    X_data: List[List[float]],
+    entity_ids: List[str],
+    time_periods: List[str],
+    feature_names: Optional[List[str]] = None
+) -> pd.DataFrame:
+    """
+    准备面板数据格式
+    
+    Args:
+        y_data: 因变量数据
+        X_data: 自变量数据，二维列表
+        entity_ids: 个体标识符列表
+        time_periods: 时间标识符列表
+        feature_names: 自变量名称列表
+    
+    Returns:
+        pd.DataFrame: 面板数据格式的DataFrame
+    """
+    # 数据验证
+    if len(y_data) != len(X_data):
+        raise ValueError("因变量和自变量的观测数量不一致")
+    if len(y_data) != len(entity_ids):
+        raise ValueError("因变量和个体标识符数量不一致")
+    if len(y_data) != len(time_periods):
+        raise ValueError("因变量和时间标识符数量不一致")
+    
+    # 创建DataFrame
+    data_dict = {
+        'entity': entity_ids,
+        'time': time_periods,
+        'y': y_data
+    }
+    
+    # 添加自变量
+    if feature_names is None:
+        feature_names = [f'x{i}' for i in range(len(X_data[0]))]
+    
+    for i, name in enumerate(feature_names):
+        data_dict[name] = [x[i] for x in X_data]
+    
+    df = pd.DataFrame(data_dict)
+    
+    # 设置多级索引
+    df = df.set_index(['entity', 'time'])
+    
+    return df
+
+
+def fixed_effects_model(
+    y_data: List[float],
+    X_data: List[List[float]],
+    entity_ids: List[str],
+    time_periods: List[str],
+    feature_names: Optional[List[str]] = None,
+    entity_effects: bool = True,
+    time_effects: bool = False
+) -> FixedEffectsResult:
+    """
+    固定效应模型
+    
+    📊 功能说明：
+    固定效应模型假设个体间存在不可观测的固定差异，通过组内变换消除这些固定效应。
+    适用于个体特征不随时间变化的情况。
+    
+    📈 模型形式：
+    y_it = α_i + βX_it + ε_it
+    
+    💡 使用场景：
+    - 研究个体内部随时间变化的影响
+    - 控制个体固定特征的影响
+    - 面板数据中个体间存在系统性差异
+    
+    ⚠️ 注意事项：
+    - 无法估计不随时间变化的变量的系数
+    - 需要较大的时间维度以获得可靠估计
+    - 对个体异质性敏感
+    
+    Args:
+        y_data: 因变量数据
+        X_data: 自变量数据
+        entity_ids: 个体标识符
+        time_periods: 时间标识符
+        feature_names: 自变量名称
+        entity_effects: 是否包含个体效应
+        time_effects: 是否包含时间效应
+    
+    Returns:
+        FixedEffectsResult: 固定效应模型结果
+    """
+    try:
+        # 准备面板数据
+        df = prepare_panel_data(y_data, X_data, entity_ids, time_periods, feature_names)
+        
+        # 分离因变量和自变量
+        y = df['y']
+        X = df.drop('y', axis=1)
+        
+        # 添加常数项
+        X = sm.add_constant(X)
+        
+        # 拟合固定效应模型
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            model = PanelOLS(y, X, entity_effects=entity_effects, time_effects=time_effects)
+            fitted_model = model.fit(cov_type='clustered', cluster_entity=True)
+        
+        # 构建系数详情
+        coefficients = {}
+        conf_int = fitted_model.conf_int()
+        
+        for i, coef_name in enumerate(fitted_model.params.index):
+            coefficients[coef_name] = {
+                "coef": float(fitted_model.params.iloc[i]),
+                "std_err": float(fitted_model.std_errors.iloc[i]),
+                "t_value": float(fitted_model.tstats.iloc[i]),
+                "p_value": float(fitted_model.pvalues.iloc[i]),
+                "ci_lower": float(conf_int.iloc[i, 0]),
+                "ci_upper": float(conf_int.iloc[i, 1])
+            }
+        
+        # 构建结果
+        result = FixedEffectsResult(
+            rsquared=float(fitted_model.rsquared),
+            rsquared_adj=float(fitted_model.rsquared_adj),
+            f_statistic=float(fitted_model.f_statistic.stat),
+            f_pvalue=float(fitted_model.f_statistic.pval),
+            aic=float(fitted_model.aic),
+            bic=float(fitted_model.bic),
+            n_obs=int(fitted_model.nobs),
+            coefficients=coefficients,
+            entity_effects=entity_effects,
+            time_effects=time_effects,
+            within_rsquared=float(fitted_model.rsquared_within)
+        )
+        
+        return result
+        
+    except Exception as e:
+        raise ValueError(f"固定效应模型拟合失败: {str(e)}")
+
+
+def random_effects_model(
+    y_data: List[float],
+    X_data: List[List[float]],
+    entity_ids: List[str],
+    time_periods: List[str],
+    feature_names: Optional[List[str]] = None,
+    entity_effects: bool = True,
+    time_effects: bool = False
+) -> RandomEffectsResult:
+    """
+    随机效应模型
+    
+    📊 功能说明：
+    随机效应模型假设个体间差异是随机的，通过GLS估计同时利用组内和组间变异。
+    适用于个体特征与解释变量不相关的情况。
+    
+    📈 模型形式：
+    y_it = α + βX_it + μ_i + ε_it
+    
+    💡 使用场景：
+    - 个体特征与解释变量不相关
+    - 希望估计不随时间变化的变量的系数
+    - 样本来自更大的总体
+    
+    ⚠️ 注意事项：
+    - 需要满足个体效应与解释变量不相关的假设
+    - 如果假设不成立，估计可能不一致
+    - 比固定效应模型更有效率
+    
+    Args:
+        y_data: 因变量数据
+        X_data: 自变量数据
+        entity_ids: 个体标识符
+        time_periods: 时间标识符
+        feature_names: 自变量名称
+        entity_effects: 是否包含个体效应
+        time_effects: 是否包含时间效应
+    
+    Returns:
+        RandomEffectsResult: 随机效应模型结果
+    """
+    try:
+        # 准备面板数据
+        df = prepare_panel_data(y_data, X_data, entity_ids, time_periods, feature_names)
+        
+        # 分离因变量和自变量
+        y = df['y']
+        X = df.drop('y', axis=1)
+        
+        # 添加常数项
+        X = sm.add_constant(X)
+        
+        # 拟合随机效应模型
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            model = RandomEffects(y, X, entity_effects=entity_effects, time_effects=time_effects)
+            fitted_model = model.fit(cov_type='clustered', cluster_entity=True)
+        
+        # 构建系数详情
+        coefficients = {}
+        conf_int = fitted_model.conf_int()
+        
+        for i, coef_name in enumerate(fitted_model.params.index):
+            coefficients[coef_name] = {
+                "coef": float(fitted_model.params.iloc[i]),
+                "std_err": float(fitted_model.std_errors.iloc[i]),
+                "t_value": float(fitted_model.tstats.iloc[i]),
+                "p_value": float(fitted_model.pvalues.iloc[i]),
+                "ci_lower": float(conf_int.iloc[i, 0]),
+                "ci_upper": float(conf_int.iloc[i, 1])
+            }
+        
+        # 构建结果
+        result = RandomEffectsResult(
+            rsquared=float(fitted_model.rsquared),
+            rsquared_adj=float(fitted_model.rsquared_adj),
+            f_statistic=float(fitted_model.f_statistic.stat),
+            f_pvalue=float(fitted_model.f_statistic.pval),
+            aic=float(fitted_model.aic),
+            bic=float(fitted_model.bic),
+            n_obs=int(fitted_model.nobs),
+            coefficients=coefficients,
+            entity_effects=entity_effects,
+            time_effects=time_effects,
+            between_rsquared=float(fitted_model.rsquared_between)
+        )
+        
+        return result
+        
+    except Exception as e:
+        raise ValueError(f"随机效应模型拟合失败: {str(e)}")
+
+
+def hausman_test(
+    y_data: List[float],
+    X_data: List[List[float]],
+    entity_ids: List[str],
+    time_periods: List[str],
+    feature_names: Optional[List[str]] = None
+) -> HausmanTestResult:
+    """
+    Hausman检验
+    
+    📊 功能说明：
+    Hausman检验用于比较固定效应模型和随机效应模型，判断个体效应是否与解释变量相关。
+    原假设：随机效应模型是一致的（个体效应与解释变量不相关）
+    备择假设：固定效应模型是一致的
+    
+    💡 使用场景：
+    - 在固定效应和随机效应模型之间选择
+    - 检验个体效应是否与解释变量相关
+    - 验证随机效应模型的假设
+    
+    ⚠️ 注意事项：
+    - p值 < 0.05：拒绝原假设，选择固定效应模型
+    - p值 >= 0.05：不能拒绝原假设，选择随机效应模型
+    - 检验统计量服从卡方分布
+    
+    Args:
+        y_data: 因变量数据
+        X_data: 自变量数据
+        entity_ids: 个体标识符
+        time_periods: 时间标识符
+        feature_names: 自变量名称
+    
+    Returns:
+        HausmanTestResult: Hausman检验结果
+    """
+    try:
+        # 拟合固定效应模型
+        fe_result = fixed_effects_model(y_data, X_data, entity_ids, time_periods, feature_names)
+        
+        # 拟合随机效应模型
+        re_result = random_effects_model(y_data, X_data, entity_ids, time_periods, feature_names)
+        
+        # 提取系数（排除常数项）
+        fe_coefs = np.array([fe_result.coefficients[name]["coef"] for name in fe_result.coefficients if name != "const"])
+        re_coefs = np.array([re_result.coefficients[name]["coef"] for name in re_result.coefficients if name != "const"])
+        
+        # 计算差异
+        diff = fe_coefs - re_coefs
+        
+        # 简化Hausman检验统计量计算
+        # 在实际应用中，应该使用更精确的方差-协方差矩阵计算
+        statistic = np.sum(diff ** 2)
+        
+        # 自由度
+        df = len(fe_coefs)
+        
+        # 计算p值
+        from scipy import stats
+        p_value = 1 - stats.chi2.cdf(statistic, df)
+        
+        # 判断显著性
+        significant = p_value < 0.05
+        
+        # 给出建议
+        if significant:
+            recommendation = "拒绝原假设，建议使用固定效应模型（个体效应与解释变量相关）"
+        else:
+            recommendation = "不能拒绝原假设，建议使用随机效应模型（个体效应与解释变量不相关）"
+        
+        return HausmanTestResult(
+            statistic=float(statistic),
+            p_value=float(p_value),
+            significant=significant,
+            recommendation=recommendation
+        )
+        
+    except Exception as e:
+        raise ValueError(f"Hausman检验失败: {str(e)}")
+
+
+def panel_unit_root_test(
+    data: List[float],
+    entity_ids: List[str],
+    time_periods: List[str],
+    test_type: str = "levinlin"
+) -> PanelUnitRootResult:
+    """
+    面板单位根检验
+    
+    📊 功能说明：
+    检验面板数据是否存在单位根，判断序列是否平稳。
+    常用的检验方法包括Levin-Lin-Chu检验、Im-Pesaran-Shin检验等。
+    
+    💡 使用场景：
+    - 面板数据建模前的平稳性检验
+    - 判断是否需要差分处理
+    - 验证面板数据的协整关系
+    
+    ⚠️ 注意事项：
+    - p值 < 0.05：拒绝原假设，序列平稳
+    - p值 >= 0.05：不能拒绝原假设，序列非平稳
+    - 不同检验方法适用于不同的数据特征
+    
+    Args:
+        data: 面板数据序列
+        entity_ids: 个体标识符
+        time_periods: 时间标识符
+        test_type: 检验类型 ("levinlin", "ips", "fisher")
+    
+    Returns:
+        PanelUnitRootResult: 面板单位根检验结果
+    """
+    try:
+        # 准备数据
+        df = pd.DataFrame({
+            'entity': entity_ids,
+            'time': time_periods,
+            'value': data
+        })
+        
+        # 设置面板格式
+        df = df.set_index(['entity', 'time'])
+        
+        # 简化实现：使用ADF检验的扩展版本
+        # 在实际应用中，应该使用专门的panel unit root测试库
+        
+        # 对每个个体分别进行ADF检验
+        entities = df.index.get_level_values('entity').unique()
+        p_values = []
+        
+        for entity in entities:
+            entity_data = df.xs(entity, level='entity')['value'].values
+            if len(entity_data) > 4:  # ADF检验需要足够的数据点
+                from statsmodels.tsa.stattools import adfuller
+                try:
+                    adf_result = adfuller(entity_data)
+                    p_values.append(adf_result[1])
+                except:
+                    continue
+        
+        if not p_values:
+            raise ValueError("无法进行面板单位根检验，数据不足")
+        
+        # 使用Fisher组合检验方法（简化版）
+        from scipy import stats
+        combined_stat = -2 * np.sum(np.log(p_values))
+        df_fisher = 2 * len(p_values)
+        p_value = 1 - stats.chi2.cdf(combined_stat, df_fisher)
+        
+        # 判断平稳性
+        stationary = p_value < 0.05
+        
+        return PanelUnitRootResult(
+            statistic=float(combined_stat),
+            p_value=float(p_value),
+            stationary=stationary,
+            test_type=f"fisher_{test_type}"
+        )
+        
+    except Exception as e:
+        raise ValueError(f"面板单位根检验失败: {str(e)}")
+
+
+def compare_panel_models(
+    y_data: List[float],
+    X_data: List[List[float]],
+    entity_ids: List[str],
+    time_periods: List[str],
+    feature_names: Optional[List[str]] = None
+) -> Dict[str, Any]:
+    """
+    比较不同面板数据模型
+    
+    Args:
+        y_data: 因变量数据
+        X_data: 自变量数据
+        entity_ids: 个体标识符
+        time_periods: 时间标识符
+        feature_names: 自变量名称
+    
+    Returns:
+        Dict[str, Any]: 模型比较结果
+    """
+    try:
+        # 拟合不同模型
+        fe_result = fixed_effects_model(y_data, X_data, entity_ids, time_periods, feature_names)
+        re_result = random_effects_model(y_data, X_data, entity_ids, time_periods, feature_names)
+        hausman_result = hausman_test(y_data, X_data, entity_ids, time_periods, feature_names)
+        
+        # 模型比较
+        comparison = {
+            "fixed_effects": {
+                "rsquared": fe_result.rsquared,
+                "aic": fe_result.aic,
+                "bic": fe_result.bic,
+                "within_rsquared": fe_result.within_rsquared
+            },
+            "random_effects": {
+                "rsquared": re_result.rsquared,
+                "aic": re_result.aic,
+                "bic": re_result.bic,
+                "between_rsquared": re_result.between_rsquared
+            },
+            "hausman_test": hausman_result.model_dump(),
+            "recommendation": hausman_result.recommendation
+        }
+        
+        # 根据AIC和BIC选择最佳模型
+       
+        if fe_result.aic < re_result.aic and fe_result.bic < re_result.bic:
+            comparison["aic_bic_recommendation"] = "根据AIC和BIC，固定效应模型更优"
+        elif re_result.aic < fe_result.aic and re_result.bic < fe_result.bic:
+            comparison["aic_bic_recommendation"] = "根据AIC和BIC，随机效应模型更优"
+        else:
+            comparison["aic_bic_recommendation"] = "AIC和BIC结果不一致，建议参考Hausman检验"
+        
+        return comparison
+        
+    except Exception as e:
+        raise ValueError(f"模型比较失败: {str(e)}")
+
+
+# 导出所有函数
+__all__ = [
+    "FixedEffectsResult",
+    "RandomEffectsResult", 
+    "HausmanTestResult",
+    "PanelUnitRootResult",
+    "fixed_effects_model",
+    "random_effects_model", 
+    "hausman_test",
+    "panel_unit_root_test",
+    "compare_panel_models",
+    "prepare_panel_data"
+]