time-series-model-analysis-and-diagnostic-tool 0.1.2

时间序列模型分析与诊断工具 - 提供AR模型平稳性检验和MA模型可逆性检验功能

English | 中文

时间序列模型分析与诊断工具

一个专业的时间序列模型分析与诊断工具，提供AR模型平稳性检验和MA模型可逆性检验功能。

🚀 功能特性

核心功能

• AR模型平稳性检验: 检验自回归模型的平稳性条件
• MA模型可逆性检验: 检验移动平均模型的可逆性条件
• 特征根分析: 计算特征多项式的根并判断其位置
• 稳定性边际分析: 量化分析模型的稳定性程度
• 修改建议: 为不满足条件的模型提供调整建议

使用方式

• Python库: 可作为Python包导入使用
• 命令行工具: 提供友好的命令行接口
• 批量处理: 支持批量模型分析和比较

📦 安装

使用uv（推荐）

uv add time-series-model-analysis-and-diagnostic-tool

使用pip

pip install time-series-model-analysis-and-diagnostic-tool

从源码安装

git clone https://github.com/zym9863/time-series-model-analysis-and-diagnostic-tool.git
cd time-series-model-analysis-and-diagnostic-tool
uv sync

🔧 快速开始

命令行使用

AR模型平稳性检验

# 基本检验
tsdiag stationarity -c "0.5,-0.3"

# 带分析和建议
tsdiag stationarity -c "0.8,0.15" --analysis --suggest

# 检验非平稳模型
tsdiag stationarity -c "1.1" --suggest

MA模型可逆性检验

# 基本检验
tsdiag invertibility -c "0.5,-0.3"

# 带分析和建议
tsdiag invertibility -c "0.8,0.15" --analysis --suggest

ARMA模型综合检验

# 同时检验AR和MA部分
tsdiag check --ar "0.5,-0.3" --ma "0.4,0.2"

查看使用示例

tsdiag examples

Python库使用

基本使用

import tsdiag

# AR模型平稳性检验
ar_result = tsdiag.stationarity_check([0.5, -0.3])
print(f"模型是否平稳: {ar_result.is_stationary}")
print(f"特征根: {[root.magnitude for root in ar_result.roots]}")

# MA模型可逆性检验
ma_result = tsdiag.invertibility_check([0.5, -0.3])
print(f"模型是否可逆: {ma_result.is_invertible}")

高级功能

import tsdiag

# 使用高级API
diagnostic = tsdiag.TSModelDiagnostic()

# 检验ARMA模型
ar_result, ma_result = diagnostic.check_arma_model(
    ar_coefficients=[0.5, -0.3],
    ma_coefficients=[0.4, 0.2]
)

# 获取摘要
summary = diagnostic.get_summary()
print(summary)

# 快速检验（只返回布尔值）
is_stationary = tsdiag.quick_ar_check([0.5, -0.3])
is_invertible = tsdiag.quick_ma_check([0.4, 0.2])

批量分析

import tsdiag

# 批量AR模型分析
ar_models = [
    [0.5],
    [1.1],
    [0.5, -0.3]
]
results = tsdiag.batch_stationarity_check(ar_models)

for result in results:
    print(f"{result['model_name']}: {result['is_stationary']}")

# 模型比较
ma_models = [[0.5], [1.1], [0.3]]
comparison = tsdiag.compare_ma_models(ma_models)
print(f"可逆性比率: {comparison['invertibility_rate']}")

📊 理论背景

AR模型平稳性

AR(p)模型: $X_t = \phi_1 X_{t-1} + \phi_2 X_{t-2} + \cdots + \phi_p X_{t-p} + \varepsilon_t$

平稳性条件: 特征方程 $1 - \phi_1 z - \phi_2 z^2 - \cdots - \phi_p z^p = 0$ 的所有根都在单位圆外。

MA模型可逆性

MA(q)模型: $X_t = \varepsilon_t + \theta_1 \varepsilon_{t-1} + \theta_2 \varepsilon_{t-2} + \cdots + \theta_q \varepsilon_{t-q}$

可逆性条件: 特征方程 $1 + \theta_1 z + \theta_2 z^2 + \cdots + \theta_q z^q = 0$ 的所有根都在单位圆外。

📖 详细文档

输入格式

系数可以使用多种格式输入：

• 列表: [0.5, -0.3, 0.1]
• numpy数组: np.array([0.5, -0.3, 0.1])
• 字符串: "0.5,-0.3,0.1" 或 "0.5 -0.3 0.1"

输出结果

StationarityResult

@dataclass
class StationarityResult:
    is_stationary: bool              # 是否平稳
    roots: List[RootInfo]           # 特征根信息
    ar_coefficients: List[float]    # AR系数
    characteristic_polynomial: List[float]  # 特征多项式系数
    message: str                    # 结果消息

InvertibilityResult

@dataclass
class InvertibilityResult:
    is_invertible: bool             # 是否可逆
    roots: List[RootInfo]          # 特征根信息
    ma_coefficients: List[float]   # MA系数
    characteristic_polynomial: List[float]  # 特征多项式系数
    message: str                   # 结果消息

风险等级

• low: 所有根远离单位圆（距离 > 0.1）
• medium: 有根接近单位圆（0 < 距离 ≤ 0.1）
• high: 有根在单位圆内或单位圆上（距离 ≤ 0）

🧪 测试

运行测试套件：

# 运行所有测试
uv run pytest

# 运行测试并显示覆盖率
uv run pytest --cov=tsdiag

# 运行特定测试文件
uv run pytest tests/test_core.py -v

📝 示例

常见AR模型

import tsdiag

# AR(1)模型示例
models = {
    "平稳": [0.5],
    "非平稳": [1.1],
    "单位根": [1.0],
    "边界情况": [0.99]
}

for name, coeffs in models.items():
    result = tsdiag.stationarity_check(coeffs)
    print(f"{name}: {result.is_stationary}")

常见MA模型

import tsdiag

# MA(1)模型示例
models = {
    "可逆": [0.5],
    "不可逆": [1.1],
    "单位根": [1.0],
    "边界情况": [0.99]
}

for name, coeffs in models.items():
    result = tsdiag.invertibility_check(coeffs)
    print(f"{name}: {result.is_invertible}")

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• 感谢所有贡献者
• 基于经典时间序列分析理论
• 使用 NumPy 进行数值计算
• 使用 Click 构建命令行界面