Macro Economic Causal Network (MECN) - 一个用于分析宏观经济指标间因果关系的复杂网络模型。
MECN 将常规经济指标视为一个相互连接、动态演化的复杂网络，通过先进的因果发现算法（LASSO、Granger、PCMCI）捕捉指标间的因果关系，并支持涟漪效应模拟，分析单个指标波动对整个经济网络的连锁反应。
- LASSO 回归：L1 正则化识别稀疏因果结构
- Granger 因果检验：基于 VAR 模型的 F 统计量检验
- PCMCI 算法：PC 阶段 + MCI 阶段的先进因果发现
- 集成融合策略：投票机制、置信度加权、混合策略
- 5 种中心性指标：度中心性、入度、出度、接近中心性、中介中心性、PageRank、特征向量中心性
- 社区检测：基于连通性的社区发现算法
- 系统重要性识别：识别对网络整体效率影响最大的节点
- FRED API：圣路易斯联邦储备经济数据库（50+ 指标）
- World Bank API：世界银行公开数据库
- 增强模拟数据：40 个经济指标，150 期历史数据
- 季节性调整：X-13ARIMA 方法
- 平稳性检验：ADF 单位根检验
- 缺失值处理：多种插值方法
- 冲击传播算法：模拟指标波动在网络中的传导
- 风险路径查找：DFS 搜索所有影响路径
- 衰减因子控制：可配置的传播衰减机制
- PDF 分析报告：包含执行摘要、网络统计、中心性分析、关键发现
- 可视化导出：D3.js 力导向图 JSON 格式
- 完整的 CLI 界面：支持 analyze、preprocess、visualize 等命令
- 灵活的参数配置：长短参数格式、等号格式支持
- CSV 数据导入：支持从 CSV 文件读取时间序列数据
- 实时进度显示：美观的控制台输出和进度提示
- 详细文档：完整的使用指南和示例
- Java 17+ (推荐 JDK 17 或更高版本)
- Maven 3.6+
# 使用脚本设置 JDK 17+
./scripts/setup-jdk17.shcd mecn
mvn clean install第一步：启动 Spring Boot 后端
# 使用 Maven 启动
mvn spring-boot:run
# 或直接运行 jar
java -jar target/mecn-1.jar后端服务将在 http://localhost:8080 启动，提供以下 API：
| 接口 | 方法 | 描述 |
|---|---|---|
/api/network/build |
POST | 构建因果网络 |
/api/network/ripple |
POST | 执行涟漪模拟 |
/api/network/systemic-importance |
GET | 获取系统重要性节点 |
/api/health |
GET | 健康检查 |
/api/docs |
GET | API 文档 |
第二步：打开前端页面
- 直接打开:
open src/main/resources/static/index.html - 或使用 HTTP 服务器:
python3 -m http.server 8080 -d src/main/resources/static
注意: 前端默认使用模拟数据，如需连接后端 API，需修改
index.html中的 API 调用。
快速开始：
# 编译项目
mvn clean package -DskipTests
# 显示帮助信息
java -cp target/classes:$(mvn dependency:build-classpath -q -Dmdep.outputFile=/dev/stdout) \
com.mecn.MECNCLI --help
# 使用模拟数据执行分析
java -cp target/classes:$(mvn dependency:build-classpath -q -Dmdep.outputFile=/dev/stdout) \
com.mecn.MECNCLI
# 从 CSV 文件执行分析
java -cp target/classes:$(mvn dependency:build-classpath -q -Dmdep.outputFile=/dev/stdout) \
com.mecn.MECNCLI -i examples/sample_data.csv
# 指定算法和参数
java -cp target/classes:$(mvn dependency:build-classpath -q -Dmdep.outputFile=/dev/stdout) \
com.mecn.MECNCLI \
--algorithm ensemble \
--max-lag 3 \
-i examples/sample_data.csv详细文档: CLI 使用指南
快速启动：
# 构建并启动（仅应用）
docker-compose up --build
# 后台运行
docker-compose up -d
# 查看日志
docker-compose logs -f mecn-app
# 停止服务
docker-compose down启动后访问：http://localhost:8080
使用 Nginx 反向代理（可选）：
# 启动应用 + Nginx
docker-compose --profile with-nginx up -d访问：http://localhost（Nginx 监听 80 端口）
手动 Docker 操作：
# 1. 构建镜像
docker build -t mecn:latest .
# 2. 运行容器
docker run -d -p 8080:8080 \
-e JAVA_OPTS="-Xms512m -Xmx1024m" \
--name mecn \
mecn:latest
# 3. 查看日志
docker logs -f mecn
# 4. 进入容器
docker exec -it mecn sh配置文件挂载：
# 复制配置示例
cp config/application-prod.yml.example config/application-prod.yml
# 编辑配置后挂载运行
docker run -d -p 8080:8080 \
-v $(pwd)/config/application-prod.yml:/app/config/application-prod.yml:ro \
-v $(pwd)/logs:/app/logs \
--name mecn \
mecn:latest环境变量配置：
| 变量名 | 说明 | 默认值 |
|---|---|---|
JAVA_OPTS |
JVM 参数 | -Xms512m -Xmx1024m |
SPRING_PROFILES_ACTIVE |
Spring 激活 profile | prod |
SERVER_PORT |
服务端口 | 8080 |
MECN_LEGACY_MODE |
兼容模式 | false |
MECN_EDGE_THRESHOLD |
边阈值 | 0.08 |
MECN_DECAY_FACTOR |
衰减因子 | 0.9 |
配置文件位于 src/main/resources/application.yml：
mecn:
legacy-mode: false # true=仅 LASSO, false=多算法集成
default-data-source: simulated # simulated/fred/worldbank
causal-methods:
- lasso
- granger
- pcmci
edge-threshold: 0.08 # 网络边过滤阈值
ripple-time-steps: 20 # 涟漪模拟时间步数
decay-factor: 0.9 # 冲击传播衰减因子mecn/
├── src/main/java/com/mecn/
│ ├── model/ # 数据模型
│ │ ├── EconomicIndicator # 经济指标定义
│ │ ├── TimeSeriesData # 时间序列数据
│ │ ├── CausalEdge # 因果边
│ │ ├── NetworkGraph # 网络图封装
│ │ └── CentralityResult # 中心性结果
│ ├── data/ # 数据层
│ │ ├── provider/ # 数据提供者接口
│ │ ├── generator/ # 数据生成器
│ │ └── repository/ # 数据仓储
│ ├── preprocess/ # 数据预处理
│ ├── causal/ # 因果发现引擎
│ │ ├── CausalEngine # 因果引擎接口
│ │ ├── LassoRegression # LASSO 实现
│ │ ├── GrangerCausality # Granger 因果检验
│ │ ├── PCMCIAlgorithm # PCMCI 算法
│ │ └── EnsembleFusionStrategy # 集成融合策略
│ ├── network/ # 网络分析模块
│ │ ├── NetworkBuilder # 网络构建器
│ │ ├── CentralityAnalyzer # 中心性分析
│ │ ├── CommunityDetector # 社区检测
│ │ └── RippleSimulator # 涟漪效应模拟器
│ ├── visualize/ # 可视化服务
│ ├── report/ # 报告生成
│ ├── api/ # REST API 控制器
│ └── config/ # 配置类
└── src/main/resources/
├── application.yml # 应用配置
└── static/
├── index.html # Web 主页面
└── js/ # D3.js 脚本
- LASSO 回归：通过 L1 正则化进行变量选择，识别稀疏因果结构
- Granger 因果检验：基于 VAR 模型的 F 检验，判断时间序列因果关系
- PCMCI 算法：处理混淆变量的先进因果发现方法
- 投票机制：至少 N 个方法认为存在因果关系才保留
- 置信度加权：综合各方法的 p-value 和系数大小
- 混合策略：先投票筛选，再加权平均
δ(t+1, vⱼ) = Σᵢ wᵢⱼ × δ(t, vᵢ) × decay_factor
其中：
- wᵢⱼ: 从节点 i 到 j 的边权重
- decay_factor: 衰减因子 (默认 0.9)
- 迭代直到收敛或达到最大时间步
POST /api/network/build
Content-Type: application/json
{
"dataSource": "simulated",
"numPeriods": 150,
"edgeThreshold": 0.08
}GET /api/network/visualizePOST /api/network/ripple
Content-Type: application/json
{
"shockNode": "CMD_0",
"magnitude": 1.0,
"timeSteps": 20
}# 运行所有测试
mvn test
# 运行特定测试类
mvn test -Dtest=LassoRegressionTest文档索引: docs/README.md - 完整的文档导航和分类
- 项目进展报告 - 当前开发状态和进度
- CLI使用指南 - 命令行工具完整文档
- API 使用指南 - 详细的 API 使用说明
- 部署指南 - Docker 部署和配置
- CI/CD指南 - 持续集成/部署流程
- 测试指南 - 测试模块说明和覆盖率报告
- 模块结构说明 - 模块架构详情
- TDD实践记录 - TDD开发实践记录
- 贡献指南 - 如何参与项目贡献
- 变更日志 - 版本历史记录
本项目使用 MkDocs 构建现代化的文档网站，提供：
- 📖 结构化的导航和搜索
- 🎨 响应式设计和深色模式
- 📱 移动端适配
- 🔍 全文搜索（中英文）
- 📊 交互式示例和代码高亮
构建本地文档站点：
# 一键构建
./build-docs.sh
# 本地预览
./serve-docs.sh访问 http://localhost:8000 查看文档网站。
欢迎提交 Issue 和 Pull Request！
MIT License
如有问题或建议，请创建 Issue 或 发送email到niuyanno.1@outlook.com。
最后更新: 2026-03-25 版本: 1.0.0-SNAPSHOT