aigroup-econ-mcp 0.1.6__py3-none-any.whl → 0.2.1__py3-none-any.whl

aigroup_econ_mcp/tools/time_series.py

@@ -1,260 +1,838 @@
-"""
-时间序列分析工具
-"""
-
-import numpy as np
-import pandas as pd
-from typing import List, Dict, Any, Optional, Tuple
-from pydantic import BaseModel
-import statsmodels.api as sm
-from statsmodels.tsa.stattools import adfuller, kpss, acf, pacf
-from statsmodels.tsa.arima.model import ARIMA
-from statsmodels.tsa.statespace.sarimax import SARIMAX
-
-
-class StationarityTest(BaseModel):
-    """平稳性检验结果"""
-    adf_statistic: float
-    adf_pvalue: float
-    adf_critical_values: Dict[str, float]
-    kpss_statistic: float
-    kpss_pvalue: float
-    is_stationary: bool
-
-
-class ACFPACFResult(BaseModel):
-    """自相关分析结果"""
-    acf_values: List[float]
-    pacf_values: List[float]
-    acf_confidence: List[Tuple[float, float]]
-    pacf_confidence: List[Tuple[float, float]]
-
-
-class ARIMAResult(BaseModel):
-    """ARIMA模型结果"""
-    order: Tuple[int, int, int]
-    aic: float
-    bic: float
-    coefficients: Dict[str, float]
-    fitted_values: List[float]
-    residuals: List[float]
-    forecast: Optional[List[float]] = None
-
-
-def check_stationarity(data: List[float], max_lags: int = None) -> StationarityTest:
-    """平稳性检验（ADF和KPSS）"""
-    series = pd.Series(data)
-
-    # ADF检验
-    adf_result = adfuller(series, maxlag=max_lags, autolag='AIC')
-    adf_stat, adf_pvalue = adf_result[0], adf_result[1]
-    adf_critical = adf_result[4]
-
-    # KPSS检验
-    kpss_result = kpss(series, regression='c', nlags='auto')
-    kpss_stat, kpss_pvalue = kpss_result[0], kpss_result[1]
-
-    # 综合判断平稳性
-    is_stationary = (adf_pvalue < 0.05) and (kpss_pvalue > 0.05)
-
-    return StationarityTest(
-        adf_statistic=adf_stat,
-        adf_pvalue=adf_pvalue,
-        adf_critical_values=adf_critical,
-        kpss_statistic=kpss_stat,
-        kpss_pvalue=kpss_pvalue,
-        is_stationary=is_stationary
-    )
-
-
-def calculate_acf_pacf(
-    data: List[float],
-    nlags: int = 20,
-    alpha: float = 0.05
-) -> ACFPACFResult:
-    """计算自相关和偏自相关函数"""
-    series = pd.Series(data)
-
-    # 计算ACF和PACF
-    acf_values = acf(series, nlags=nlags, alpha=alpha)
-    pacf_values = pacf(series, nlags=nlags, alpha=alpha)
-
-    # 构建置信区间
-    acf_conf = []
-    pacf_conf = []
-
-    for i in range(len(acf_values[1])):
-        acf_conf.append((acf_values[1][i][0], acf_values[1][i][1]))
-        pacf_conf.append((pacf_values[1][i][0], pacf_values[1][i][1]))
-
-    return ACFPACFResult(
-        acf_values=acf_values[0].tolist(),
-        pacf_values=pacf_values[0].tolist(),
-        acf_confidence=acf_conf,
-        pacf_confidence=pacf_conf
-    )
-
-
-def fit_arima_model(
-    data: List[float],
-    order: Tuple[int, int, int] = (1, 1, 1),
-    seasonal_order: Tuple[int, int, int, int] = (0, 0, 0, 0)
-) -> ARIMAResult:
-    """拟合ARIMA模型"""
-    series = pd.Series(data)
-
-    try:
-        if seasonal_order != (0, 0, 0, 0):
-            # 季节性ARIMA
-            model = SARIMAX(series, order=order, seasonal_order=seasonal_order)
-        else:
-            # 普通ARIMA
-            model = ARIMA(series, order=order)
-
-        fitted_model = model.fit()
-
-        return ARIMAResult(
-            order=order,
-            aic=fitted_model.aic,
-            bic=fitted_model.bic,
-            coefficients=fitted_model.params.to_dict(),
-            fitted_values=fitted_model.fittedvalues.tolist(),
-            residuals=fitted_model.resid.tolist()
-        )
-
-    except Exception as e:
-        raise ValueError(f"ARIMA模型拟合失败: {str(e)}")
-
-
-def find_best_arima_order(
-    data: List[float],
-    max_p: int = 3,
-    max_d: int = 2,
-    max_q: int = 3,
-    seasonal: bool = False,
-    max_P: int = 1,
-    max_D: int = 1,
-    max_Q: int = 1,
-    m: int = 12
-) -> Dict[str, Any]:
-    """自动寻找最佳ARIMA模型阶数"""
-    series = pd.Series(data)
-    best_aic = float('inf')
-    best_order = (0, 0, 0)
-    best_seasonal_order = (0, 0, 0, 0)
-    best_model = None
-
-    # 非季节性ARIMA
-    if not seasonal:
-        for p in range(max_p + 1):
-            for d in range(max_d + 1):
-                for q in range(max_q + 1):
-                    try:
-                        model = ARIMA(series, order=(p, d, q))
-                        fitted_model = model.fit()
-                        if fitted_model.aic < best_aic:
-                            best_aic = fitted_model.aic
-                            best_order = (p, d, q)
-                            best_model = fitted_model
-                    except:
-                        continue
-
-    # 季节性ARIMA
-    else:
-        for p in range(max_p + 1):
-            for d in range(max_d + 1):
-                for q in range(max_q + 1):
-                    for P in range(max_P + 1):
-                        for D in range(max_D + 1):
-                            for Q in range(max_Q + 1):
-                                try:
-                                    seasonal_order = (P, D, Q, m)
-                                    model = SARIMAX(series, order=(p, d, q), seasonal_order=seasonal_order)
-                                    fitted_model = model.fit()
-                                    if fitted_model.aic < best_aic:
-                                        best_aic = fitted_model.aic
-                                        best_order = (p, d, q)
-                                        best_seasonal_order = seasonal_order
-                                        best_model = fitted_model
-                                except:
-                                    continue
-
-    if best_model is None:
-        raise ValueError("无法找到合适的ARIMA模型")
-
-    return {
-        "best_order": best_order,
-        "best_seasonal_order": best_seasonal_order if seasonal else None,
-        "best_aic": best_aic,
-        "best_bic": best_model.bic,
-        "coefficients": best_model.params.to_dict(),
-        "model_summary": str(best_model.summary())
-    }
-
-
-def decompose_time_series(
-    data: List[float],
-    model: str = "additive",
-    period: Optional[int] = None
-) -> Dict[str, List[float]]:
-    """时间序列分解"""
-    series = pd.Series(data)
-
-    if period is None:
-        # 自动检测周期（简单方法）
-        from statsmodels.tsa.seasonal import seasonal_decompose
-        decomposition = seasonal_decompose(series, model=model, extrapolate_trend='freq')
-
-        return {
-            "trend": decomposition.trend.fillna(0).tolist(),
-            "seasonal": decomposition.seasonal.fillna(0).tolist(),
-            "residual": decomposition.resid.fillna(0).tolist(),
-            "observed": decomposition.observed.tolist()
-        }
-    else:
-        # 指定周期的分解
-        decomposition = seasonal_decompose(series, model=model, period=period)
-
-        return {
-            "trend": decomposition.trend.fillna(0).tolist(),
-            "seasonal": decomposition.seasonal.fillna(0).tolist(),
-            "residual": decomposition.resid.fillna(0).tolist(),
-            "observed": decomposition.observed.tolist()
-        }
-
-
-def forecast_arima(
-    data: List[float],
-    order: Tuple[int, int, int] = (1, 1, 1),
-    steps: int = 10,
-    seasonal_order: Tuple[int, int, int, int] = (0, 0, 0, 0)
-) -> Dict[str, Any]:
-    """ARIMA模型预测"""
-    series = pd.Series(data)
-
-    try:
-        if seasonal_order != (0, 0, 0, 0):
-            model = SARIMAX(series, order=order, seasonal_order=seasonal_order)
-        else:
-            model = ARIMA(series, order=order)
-
-        fitted_model = model.fit()
-
-        # 生成预测
-        forecast_result = fitted_model.forecast(steps=steps)
-        forecast_values = forecast_result.tolist()
-
-        # 预测置信区间
-        pred_conf = fitted_model.get_forecast(steps=steps)
-        conf_int = pred_conf.conf_int()
-
-        return {
-            "forecast": forecast_values,
-            "conf_int_lower": conf_int.iloc[:, 0].tolist(),
-            "conf_int_upper": conf_int.iloc[:, 1].tolist(),
-            "model_aic": fitted_model.aic,
-            "model_bic": fitted_model.bic
-        }
-
-    except Exception as e:
-        raise ValueError(f"ARIMA预测失败: {str(e)}")
+
+"""
+时间序列分析工具
+"""
+
+import numpy as np
+import pandas as pd
+from typing import List, Dict, Any, Optional, Tuple
+from pydantic import BaseModel
+import statsmodels.api as sm
+from statsmodels.tsa.stattools import adfuller, kpss, acf, pacf
+from statsmodels.tsa.arima.model import ARIMA
+from statsmodels.tsa.statespace.sarimax import SARIMAX
+from statsmodels.tsa.vector_ar.var_model import VAR
+from statsmodels.tsa.vector_ar.vecm import VECM
+from statsmodels.tsa.statespace.varmax import VARMAX
+from statsmodels.tsa.api import VAR as VAR2
+from statsmodels.tsa.statespace.kalman_filter import KalmanFilter
+from statsmodels.tsa.statespace.tools import (
+    constrain_stationary_univariate, 
+    unconstrain_stationary_univariate
+)
+
+
+class StationarityTest(BaseModel):
+    """平稳性检验结果"""
+    adf_statistic: float
+    adf_pvalue: float
+    adf_critical_values: Dict[str, float]
+    kpss_statistic: float
+    kpss_pvalue: float
+    is_stationary: bool
+
+
+class ACFPACFResult(BaseModel):
+    """自相关分析结果"""
+    acf_values: List[float]
+    pacf_values: List[float]
+    acf_confidence: List[Tuple[float, float]]
+    pacf_confidence: List[Tuple[float, float]]
+
+
+class ARIMAResult(BaseModel):
+    """ARIMA模型结果"""
+    order: Tuple[int, int, int]
+    aic: float
+    bic: float
+    coefficients: Dict[str, float]
+    fitted_values: List[float]
+    residuals: List[float]
+    forecast: Optional[List[float]] = None
+
+
+class VARModelResult(BaseModel):
+    """VAR模型结果"""
+    order: int
+    aic: float
+    bic: float
+    hqic: float
+    coefficients: Dict[str, Dict[str, float]]
+    fitted_values: Dict[str, List[float]]
+    residuals: Dict[str, List[float]]
+    forecast: Optional[Dict[str, List[float]]] = None
+    granger_causality: Dict[str, Dict[str, float]]
+
+
+class VECMModelResult(BaseModel):
+    """VECM模型结果"""
+    coint_rank: int
+    aic: float
+    bic: float
+    hqic: float
+    alpha: Dict[str, List[float]]
+    beta: List[List[float]]
+    gamma: Dict[str, Dict[str, float]]
+    cointegration_relations: List[List[float]]
+    adjustment_speed: Dict[str, float]
+
+
+class GARCHModelResult(BaseModel):
+    """GARCH模型结果"""
+    order: Tuple[int, int]
+    aic: float
+    bic: float
+    coefficients: Dict[str, float]
+    conditional_volatility: List[float]
+    standardized_residuals: List[float]
+    persistence: float
+    unconditional_variance: float
+
+
+class StateSpaceModelResult(BaseModel):
+    """状态空间模型结果"""
+    state_names: List[str]
+    observation_names: List[str]
+    log_likelihood: float
+    aic: float
+    bic: float
+    filtered_state: Dict[str, List[float]]
+    smoothed_state: Dict[str, List[float]]
+    forecast: Optional[Dict[str, List[float]]] = None
+    kalman_gain: Optional[List[List[float]]] = None
+
+
+def check_stationarity(data: List[float], max_lags: int = None) -> StationarityTest:
+    """平稳性检验（ADF和KPSS）"""
+    series = pd.Series(data)
+
+    # ADF检验
+    adf_result = adfuller(series, maxlag=max_lags, autolag='AIC')
+    adf_stat, adf_pvalue = adf_result[0], adf_result[1]
+    adf_critical = adf_result[4]
+
+    # KPSS检验
+    kpss_result = kpss(series, regression='c', nlags='auto')
+    kpss_stat, kpss_pvalue = kpss_result[0], kpss_result[1]
+
+    # 综合判断平稳性
+    is_stationary = (adf_pvalue < 0.05) and (kpss_pvalue > 0.05)
+
+    return StationarityTest(
+        adf_statistic=adf_stat,
+        adf_pvalue=adf_pvalue,
+        adf_critical_values=adf_critical,
+        kpss_statistic=kpss_stat,
+        kpss_pvalue=kpss_pvalue,
+        is_stationary=is_stationary
+    )
+
+
+def calculate_acf_pacf(
+    data: List[float],
+    nlags: int = 20,
+    alpha: float = 0.05
+) -> ACFPACFResult:
+    """计算自相关和偏自相关函数"""
+    series = pd.Series(data)
+
+    # 计算ACF和PACF
+    acf_values = acf(series, nlags=nlags, alpha=alpha)
+    pacf_values = pacf(series, nlags=nlags, alpha=alpha)
+
+    # 构建置信区间
+    acf_conf = []
+    pacf_conf = []
+
+    for i in range(len(acf_values[1])):
+        acf_conf.append((acf_values[1][i][0], acf_values[1][i][1]))
+        pacf_conf.append((pacf_values[1][i][0], pacf_values[1][i][1]))
+
+    return ACFPACFResult(
+        acf_values=acf_values[0].tolist(),
+        pacf_values=pacf_values[0].tolist(),
+        acf_confidence=acf_conf,
+        pacf_confidence=pacf_conf
+    )
+
+
+def fit_arima_model(
+    data: List[float],
+    order: Tuple[int, int, int] = (1, 1, 1),
+    seasonal_order: Tuple[int, int, int, int] = (0, 0, 0, 0)
+) -> ARIMAResult:
+    """拟合ARIMA模型"""
+    series = pd.Series(data)
+
+    try:
+        if seasonal_order != (0, 0, 0, 0):
+            # 季节性ARIMA
+            model = SARIMAX(series, order=order, seasonal_order=seasonal_order)
+        else:
+            # 普通ARIMA
+            model = ARIMA(series, order=order)
+
+        fitted_model = model.fit()
+
+        return ARIMAResult(
+            order=order,
+            aic=fitted_model.aic,
+            bic=fitted_model.bic,
+            coefficients=fitted_model.params.to_dict(),
+            fitted_values=fitted_model.fittedvalues.tolist(),
+            residuals=fitted_model.resid.tolist()
+        )
+
+    except Exception as e:
+        raise ValueError(f"ARIMA模型拟合失败: {str(e)}")
+
+
+def find_best_arima_order(
+    data: List[float],
+    max_p: int = 3,
+    max_d: int = 2,
+    max_q: int = 3,
+    seasonal: bool = False,
+    max_P: int = 1,
+    max_D: int = 1,
+    max_Q: int = 1,
+    m: int = 12
+) -> Dict[str, Any]:
+    """自动寻找最佳ARIMA模型阶数"""
+    series = pd.Series(data)
+    best_aic = float('inf')
+    best_order = (0, 0, 0)
+    best_seasonal_order = (0, 0, 0, 0)
+    best_model = None
+
+    # 非季节性ARIMA
+    if not seasonal:
+        for p in range(max_p + 1):
+            for d in range(max_d + 1):
+                for q in range(max_q + 1):
+                    try:
+                        model = ARIMA(series, order=(p, d, q))
+                        fitted_model = model.fit()
+                        if fitted_model.aic < best_aic:
+                            best_aic = fitted_model.aic
+                            best_order = (p, d, q)
+                            best_model = fitted_model
+                    except:
+                        continue
+
+    # 季节性ARIMA
+    else:
+        for p in range(max_p + 1):
+            for d in range(max_d + 1):
+                for q in range(max_q + 1):
+                    for P in range(max_P + 1):
+                        for D in range(max_D + 1):
+                            for Q in range(max_Q + 1):
+                                try:
+                                    seasonal_order = (P, D, Q, m)
+                                    model = SARIMAX(series, order=(p, d, q), seasonal_order=seasonal_order)
+                                    fitted_model = model.fit()
+                                    if fitted_model.aic < best_aic:
+                                        best_aic = fitted_model.aic
+                                        best_order = (p, d, q)
+                                        best_seasonal_order = seasonal_order
+                                        best_model = fitted_model
+                                except:
+                                    continue
+
+    if best_model is None:
+        raise ValueError("无法找到合适的ARIMA模型")
+
+    return {
+        "best_order": best_order,
+        "best_seasonal_order": best_seasonal_order if seasonal else None,
+        "best_aic": best_aic,
+        "best_bic": best_model.bic,
+        "coefficients": best_model.params.to_dict(),
+        "model_summary": str(best_model.summary())
+    }
+
+
+def decompose_time_series(
+    data: List[float],
+    model: str = "additive",
+    period: Optional[int] = None
+) -> Dict[str, List[float]]:
+    """时间序列分解"""
+    series = pd.Series(data)
+
+    if period is None:
+        # 自动检测周期（简单方法）
+        from statsmodels.tsa.seasonal import seasonal_decompose
+        decomposition = seasonal_decompose(series, model=model, extrapolate_trend='freq')
+
+        return {
+            "trend": decomposition.trend.fillna(0).tolist(),
+            "seasonal": decomposition.seasonal.fillna(0).tolist(),
+            "residual": decomposition.resid.fillna(0).tolist(),
+            "observed": decomposition.observed.tolist()
+        }
+    else:
+        # 指定周期的分解
+        decomposition = seasonal_decompose(series, model=model, period=period)
+
+        return {
+            "trend": decomposition.trend.fillna(0).tolist(),
+            "seasonal": decomposition.seasonal.fillna(0).tolist(),
+            "residual": decomposition.resid.fillna(0).tolist(),
+            "observed": decomposition.observed.tolist()
+        }
+
+
+def forecast_arima(
+    data: List[float],
+    order: Tuple[int, int, int] = (1, 1, 1),
+    steps: int = 10,
+    seasonal_order: Tuple[int, int, int, int] = (0, 0, 0, 0)
+) -> Dict[str, Any]:
+    """ARIMA模型预测"""
+    series = pd.Series(data)
+
+    try:
+        if seasonal_order != (0, 0, 0, 0):
+            model = SARIMAX(series, order=order, seasonal_order=seasonal_order)
+        else:
+            model = ARIMA(series, order=order)
+
+        fitted_model = model.fit()
+
+        # 生成预测
+        forecast_result = fitted_model.forecast(steps=steps)
+        forecast_values = forecast_result.tolist()
+
+        # 预测置信区间
+        pred_conf = fitted_model.get_forecast(steps=steps)
+        conf_int = pred_conf.conf_int()
+
+        return {
+            "forecast": forecast_values,
+            "conf_int_lower": conf_int.iloc[:, 0].tolist(),
+            "conf_int_upper": conf_int.iloc[:, 1].tolist(),
+            "model_aic": fitted_model.aic,
+            "model_bic": fitted_model.bic
+        }
+
+    except Exception as e:
+        raise ValueError(f"ARIMA预测失败: {str(e)}")
+
+
+def var_model(
+    data: Dict[str, List[float]],
+    max_lags: int = 5,
+    ic: str = 'aic'
+) -> VARModelResult:
+    """
+    VAR模型 - 向量自回归模型
+    
+    📊 功能说明：
+    向量自回归模型用于分析多个时间序列变量之间的动态关系。
+    每个变量的当前值都依赖于所有变量的滞后值。
+    
+    📈 模型形式：
+    Y_t = A_1 Y_{t-1} + A_2 Y_{t-2} + ... + A_p Y_{t-p} + ε_t
+    
+    💡 使用场景：
+    - 宏观经济变量间的相互影响分析
+    - 金融市场联动性研究
+    - 脉冲响应函数和方差分解
+    - 格兰杰因果关系检验
+    
+    ⚠️ 注意事项：
+    - 所有变量都应该是平稳的
+    - 滞后阶数选择很重要
+    - 变量数量不宜过多（避免维度灾难）
+    - 样本量应足够大
+    
+    Args:
+        data: 多变量时间序列数据字典
+        max_lags: 最大滞后阶数
+        ic: 信息准则 ('aic', 'bic', 'hqic')
+    
+    Returns:
+        VARModelResult: VAR模型结果
+    """
+    try:
+        # 数据验证
+        if not data:
+            raise ValueError("数据不能为空")
+        
+        if len(data) < 2:
+            raise ValueError("VAR模型至少需要2个变量")
+        
+        # 转换为DataFrame
+        df = pd.DataFrame(data)
+        
+        # 检查数据长度
+        if len(df) < max_lags + 10:
+            raise ValueError(f"数据长度({len(df)})不足，至少需要{max_lags + 10}个观测点")
+        
+        # 拟合VAR模型
+        model = VAR(df)
+        
+        # 选择最优滞后阶数
+        lag_order = model.select_order(maxlags=max_lags)
+        best_lag = getattr(lag_order, ic)
+        
+        # 使用最优滞后阶数拟合模型
+        fitted_model = model.fit(best_lag)
+        
+        # 提取系数
+        coefficients = {}
+        for i, col in enumerate(df.columns):
+            coefficients[col] = {}
+            # 提取常数项
+            if hasattr(fitted_model, 'intercept'):
+                coefficients[col]['const'] = float(fitted_model.intercept[i]) if i < len(fitted_model.intercept) else 0.0
+            # 提取滞后项系数
+            for lag in range(1, best_lag + 1):
+                for j, lag_col in enumerate(df.columns):
+                    coef_name = f"{lag_col}.L{lag}"
+                    if hasattr(fitted_model, 'coefs'):
+                        coefficients[col][coef_name] = float(fitted_model.coefs[lag-1][i, j]) if fitted_model.coefs.shape[0] >= lag else 0.0
+                    else:
+                        coefficients[col][coef_name] = 0.0
+        
+        # 拟合值和残差
+        fitted_values = {}
+        residuals = {}
+        for i, col in enumerate(df.columns):
+            fitted_values[col] = fitted_model.fittedvalues[col].tolist() if col in fitted_model.fittedvalues else []
+            residuals[col] = fitted_model.resid[col].tolist() if col in fitted_model.resid else []
+        
+        # 格兰杰因果关系检验
+        granger_causality = {}
+        for cause in df.columns:
+            granger_causality[cause] = {}
+            for effect in df.columns:
+                if cause != effect:
+                    try:
+                        test_result = fitted_model.test_causality(effect, cause, kind='f')
+                        granger_causality[cause][effect] = test_result.pvalue
+                    except:
+                        granger_causality[cause][effect] = 1.0
+        
+        return VARModelResult(
+            order=best_lag,
+            aic=fitted_model.aic,
+            bic=fitted_model.bic,
+            hqic=fitted_model.hqic,
+            coefficients=coefficients,
+            fitted_values=fitted_values,
+            residuals=residuals,
+            granger_causality=granger_causality
+        )
+        
+    except Exception as e:
+        raise ValueError(f"VAR模型拟合失败: {str(e)}")
+
+
+def vecm_model(
+    data: Dict[str, List[float]],
+    coint_rank: int = 1,
+    deterministic: str = 'co',
+    max_lags: int = 5
+) -> VECMModelResult:
+    """
+    VECM模型 - 向量误差修正模型
+    
+    📊 功能说明：
+    用于分析非平稳时间序列之间的长期均衡关系和短期动态调整。
+    适用于存在协整关系的多变量系统。
+    
+    📈 模型形式：
+    ΔY_t = αβ' Y_{t-1} + Γ_1 ΔY_{t-1} + ... + Γ_{p-1} ΔY_{t-p+1} + ε_t
+    
+    💡 使用场景：
+    - 存在长期均衡关系的经济变量分析
+    - 误差修正机制研究
+    - 协整关系检验
+    - 短期动态调整分析
+    
+    ⚠️ 注意事项：
+    - 所有变量应该是一阶单整的I(1)
+    - 协整秩的选择很重要
+    - 需要较大的样本量
+    - 对模型设定敏感
+    
+    Args:
+        data: 多变量时间序列数据字典
+        coint_rank: 协整秩
+        deterministic: 确定性项 ('co', 'ci', 'lo', 'li')
+        max_lags: 最大滞后阶数
+    
+    Returns:
+        VECMModelResult: VECM模型结果
+    """
+    try:
+        # 数据验证
+        if not data:
+            raise ValueError("数据不能为空")
+        
+        if len(data) < 2:
+            raise ValueError("VECM模型至少需要2个变量")
+        
+        # 转换为DataFrame
+        df = pd.DataFrame(data)
+        
+        # 检查数据长度
+        if len(df) < max_lags + 10:
+            raise ValueError(f"数据长度({len(df)})不足，至少需要{max_lags + 10}个观测点")
+        
+        # 拟合VECM模型
+        model = VECM(df, k_ar_diff=max_lags, coint_rank=coint_rank, deterministic=deterministic)
+        fitted_model = model.fit()
+        
+        # 提取系数
+        alpha = {}
+        beta = fitted_model.beta.tolist() if hasattr(fitted_model, 'beta') else []
+        gamma = {}
+        
+        # 提取调整系数alpha
+        if hasattr(fitted_model, 'alpha'):
+            for i, col in enumerate(df.columns):
+                alpha[col] = fitted_model.alpha[i].tolist() if i < len(fitted_model.alpha) else []
+        
+        # 提取短期系数gamma
+        if hasattr(fitted_model, 'gamma'):
+            for i, col in enumerate(df.columns):
+                gamma[col] = {}
+                for j, lag_col in enumerate(df.columns):
+                    if j < len(fitted_model.gamma[i]):
+                        gamma[col][lag_col] = float(fitted_model.gamma[i][j])
+        
+        # 计算协整关系
+        cointegration_relations = []
+        if hasattr(fitted_model, 'beta') and fitted_model.beta is not None:
+            for i in range(min(coint_rank, len(fitted_model.beta))):
+                cointegration_relations.append(fitted_model.beta[i].tolist())
+        
+        # 计算调整速度
+        adjustment_speed = {}
+        if hasattr(fitted_model, 'alpha') and fitted_model.alpha is not None:
+            for i, col in enumerate(df.columns):
+                if i < len(fitted_model.alpha):
+                    adjustment_speed[col] = float(np.mean(np.abs(fitted_model.alpha[i])))
+        
+        return VECMModelResult(
+            coint_rank=coint_rank,
+            aic=fitted_model.aic if hasattr(fitted_model, 'aic') else 0.0,
+            bic=fitted_model.bic if hasattr(fitted_model, 'bic') else 0.0,
+            hqic=fitted_model.hqic if hasattr(fitted_model, 'hqic') else 0.0,
+            alpha=alpha,
+            beta=beta,
+            gamma=gamma,
+            cointegration_relations=cointegration_relations,
+            adjustment_speed=adjustment_speed
+        )
+        
+    except Exception as e:
+        raise ValueError(f"VECM模型拟合失败: {str(e)}")
+
+
+def garch_model(
+    data: List[float],
+    order: Tuple[int, int] = (1, 1),
+    dist: str = 'normal'
+) -> GARCHModelResult:
+    """
+    GARCH模型 - 广义自回归条件异方差模型
+    
+    📊 功能说明：
+    用于建模金融时间序列的波动率聚类现象，捕捉条件方差的时变特征。
+    
+    📈 模型形式：
+    r_t = μ + ε_t, ε_t = σ_t z_t
+    σ_t² = ω + α ε_{t-1}² + β σ_{t-1}²
+    
+    💡 使用场景：
+    - 金融资产波动率建模
+    - 风险管理和VaR计算
+    - 期权定价
+    - 波动率预测
+    
+    ⚠️ 注意事项：
+    - 数据应具有波动率聚类特征
+    - 需要较大的样本量
+    - 对分布假设敏感
+    - 高阶GARCH可能不稳定
+    
+    Args:
+        data: 时间序列数据（通常是收益率）
+        order: GARCH阶数 (p, q)
+        dist: 误差分布 ('normal', 't', 'skewt')
+    
+    Returns:
+        GARCHModelResult: GARCH模型结果
+    """
+    try:
+        # 数据验证
+        if not data:
+            raise ValueError("数据不能为空")
+        
+        if len(data) < 50:
+            raise ValueError("GARCH模型至少需要50个观测点")
+        
+        # 转换为收益率序列（如果数据不是收益率）
+        series = pd.Series(data)
+        
+        # 使用arch包进行GARCH建模
+        try:
+            from arch import arch_model
+        except ImportError:
+            raise ImportError("请安装arch包: pip install arch")
+        
+        # 拟合GARCH模型
+        model = arch_model(series, vol='Garch', p=order[0], q=order[1], dist=dist)
+        fitted_model = model.fit(disp='off')
+        
+        # 提取系数
+        coefficients = {}
+        for param, value in fitted_model.params.items():
+            coefficients[param] = float(value)
+        
+        # 计算条件波动率
+        conditional_volatility = fitted_model.conditional_volatility.tolist()
+        
+        # 标准化残差
+        standardized_residuals = fitted_model.resid / fitted_model.conditional_volatility
+        standardized_residuals = standardized_residuals.tolist()
+        
+        # 计算持久性
+        alpha_sum = sum([fitted_model.params.get(f'alpha[{i}]', 0) for i in range(1, order[0]+1)])
+        beta_sum = sum([fitted_model.params.get(f'beta[{i}]', 0) for i in range(1, order[1]+1)])
+        persistence = alpha_sum + beta_sum
+        
+        # 无条件方差
+        omega = fitted_model.params.get('omega', 0)
+        unconditional_variance = omega / (1 - persistence) if persistence < 1 else float('inf')
+        
+        return GARCHModelResult(
+            order=order,
+            aic=fitted_model.aic,
+            bic=fitted_model.bic,
+            coefficients=coefficients,
+            conditional_volatility=conditional_volatility,
+            standardized_residuals=standardized_residuals,
+            persistence=persistence,
+            unconditional_variance=unconditional_variance
+        )
+        
+    except Exception as e:
+        raise ValueError(f"GARCH模型拟合失败: {str(e)}")
+
+
+def state_space_model(
+    data: List[float],
+    state_dim: int = 1,
+    observation_dim: int = 1,
+    trend: bool = True,
+    seasonal: bool = False,
+    period: int = 12
+) -> StateSpaceModelResult:
+    """
+    状态空间模型 - 卡尔曼滤波
+    
+    📊 功能说明：
+    使用状态空间表示和卡尔曼滤波进行时间序列建模，可以处理不可观测的状态变量。
+    
+    📈 模型形式：
+    状态方程: α_t = T α_{t-1} + R η_t
+    观测方程: y_t = Z α_t + ε_t
+    
+    💡 使用场景：
+    - 不可观测状态变量的估计
+    - 结构时间序列建模
+    - 实时滤波和平滑
+    - 缺失数据处理
+    
+    ⚠️ 注意事项：
+    - 模型设定复杂
+    - 需要先验知识
+    - 计算量较大
+    - 对初始值敏感
+    
+    Args:
+        data: 时间序列数据
+        state_dim: 状态维度
+        observation_dim: 观测维度
+        trend: 是否包含趋势项
+        seasonal: 是否包含季节项
+        period: 季节周期
+    
+    Returns:
+        StateSpaceModelResult: 状态空间模型结果
+    """
+    try:
+        # 数据验证
+        if not data:
+            raise ValueError("数据不能为空")
+        
+        if len(data) < 20:
+            raise ValueError("状态空间模型至少需要20个观测点")
+        
+        series = pd.Series(data)
+        
+        # 构建状态空间模型
+        from statsmodels.tsa.statespace.structural import UnobservedComponents
+        
+        # 模型设定
+        if trend and seasonal:
+            model_spec = 'trend' if not seasonal else 'trend seasonal'
+            seasonal_period = period
+        elif trend:
+            model_spec = 'trend'
+            seasonal_period = None
+        elif seasonal:
+            model_spec = 'seasonal'
+            seasonal_period = period
+        else:
+            model_spec = 'irregular'
+            seasonal_period = None
+        
+        # 拟合模型
+        model = UnobservedComponents(series, level=trend, seasonal=seasonal_period)
+        fitted_model = model.fit(disp=False)
+        
+        # 状态名称
+        state_names = []
+        if trend:
+            state_names.append('level')
+        if seasonal:
+            for i in range(period-1):
+                state_names.append(f'seasonal_{i+1}')
+        
+        # 观测名称
+        observation_names = ['observed']
+        
+        # 滤波状态
+        filtered_state = {}
+        for i, name in enumerate(state_names):
+            if i < fitted_model.filtered_state.shape[0]:
+                filtered_state[name] = fitted_model.filtered_state[i].tolist()
+        
+        # 平滑状态
+        smoothed_state = {}
+        for i, name in enumerate(state_names):
+            if i < fitted_model.smoothed_state.shape[0]:
+                smoothed_state[name] = fitted_model.smoothed_state[i].tolist()
+        
+        return StateSpaceModelResult(
+            state_names=state_names,
+            observation_names=observation_names,
+            log_likelihood=fitted_model.llf,
+            aic=fitted_model.aic,
+            bic=fitted_model.bic,
+            filtered_state=filtered_state,
+            smoothed_state=smoothed_state
+        )
+        
+    except Exception as e:
+        raise ValueError(f"状态空间模型拟合失败: {str(e)}")
+
+
+def forecast_var(
+    data: Dict[str, List[float]],
+    steps: int = 10,
+    max_lags: int = 5
+) -> Dict[str, Any]:
+    """VAR模型预测"""
+    try:
+        # 使用VAR模型进行预测
+        var_result = var_model(data, max_lags=max_lags)
+        
+        # 转换为DataFrame进行预测
+        df = pd.DataFrame(data)
+        model = VAR(df)
+        fitted_model = model.fit(var_result.order)
+        
+        # 生成预测
+        forecast = fitted_model.forecast(df.values[-var_result.order:], steps=steps)
+        
+        # 构建预测结果
+        forecast_dict = {}
+        for i, col in enumerate(df.columns):
+            forecast_dict[col] = forecast[:, i].tolist()
+        
+        return {
+            "forecast": forecast_dict,
+            "model_order": var_result.order,
+            "model_aic": var_result.aic,
+            "model_bic": var_result.bic
+        }
+        
+    except Exception as e:
+        raise ValueError(f"VAR预测失败: {str(e)}")
+
+
+def impulse_response_analysis(
+    data: Dict[str, List[float]],
+    periods: int = 10,
+    max_lags: int = 5
+) -> Dict[str, Any]:
+    """脉冲响应分析"""
+    try:
+        # 拟合VAR模型
+        var_result = var_model(data, max_lags=max_lags)
+        
+        # 转换为DataFrame
+        df = pd.DataFrame(data)
+        model = VAR(df)
+        fitted_model = model.fit(var_result.order)
+        
+        # 计算脉冲响应
+        irf = fitted_model.irf(periods=periods)
+        
+        # 构建脉冲响应结果
+        impulse_responses = {}
+        for i, shock_var in enumerate(df.columns):
+            impulse_responses[shock_var] = {}
+            for j, response_var in enumerate(df.columns):
+                impulse_responses[shock_var][response_var] = irf.irfs[:, j, i].tolist()
+        
+        return {
+            "impulse_responses": impulse_responses,
+            "orthogonalized": irf.orth_irfs.tolist() if hasattr(irf, 'orth_irfs') else None,
+            "cumulative_effects": irf.cum_effects.tolist() if hasattr(irf, 'cum_effects') else None
+        }
+        
+    except Exception as e:
+        raise ValueError(f"脉冲响应分析失败: {str(e)}")
+
+
+def variance_decomposition(
+    data: Dict[str, List[float]],
+    periods: int = 10,
+    max_lags: int = 5
+) -> Dict[str, Any]:
+    """方差分解"""
+    try:
+        # 拟合VAR模型
+        var_result = var_model(data, max_lags=max_lags)
+        
+        # 转换为DataFrame
+        df = pd.DataFrame(data)
+        model = VAR(df)
+        fitted_model = model.fit(var_result.order)
+        
+        # 计算方差分解
+        vd = fitted_model.fevd(periods=periods)
+        
+        # 构建方差分解结果
+        variance_decomp = {}
+        for i, var_name in enumerate(df.columns):
+            variance_decomp[var_name] = {}
+            for j, shock_name in enumerate(df.columns):
+                variance_decomp[var_name][shock_name] = vd.decomposition[var_name][shock_name].tolist()
+        
+        return {
+            "variance_decomposition": variance_decomp,
+            "horizon": periods
+        }
+        
+    except Exception as e:
+        raise ValueError(f"方差分解失败: {str(e)}")