美国财政部国际资本流动数据 · 外国居民持有的美国长期证券
一键抓取、清洗、分析并生成图表
Fetch, clean and visualize the U.S. Treasury TIC Table 1 — U.S. long-term securities held by foreign residents. One command from download to charts.
本工具自动抓取美国财政部 TIC (Treasury International Capital) 发布的 Table 1: U.S. Long-Term Securities Held by Foreign Residents（外国居民持有的美国长期证券）月度数据，完成清洗后输出：
- 📊 6 张专业风格图表（持仓排名 / 持仓走势 / 净买卖构成 / 品种构成 / 中日单国走势）
- 📄 清理后的 CSV 数据 + 文本分析报告（Top 20 持仓、环比/同比、近 12 个月净买卖排名）
图表遵循数据可视化规范设计：统一浅色面板、发丝级网格线、经校验的色盲安全配色（相邻色对 CVD ΔE ≥ 8）、颜色跟随实体而非排名、单图单轴。
- 数据获取 — urllib 下载官方数据，本地缓存避免重复下载（
--refresh可强制更新） - 数据清洗 — pandas 解析表格，剔除脚注/说明行，图表分析时自动排除汇总行，覆盖 80+ 国家/地区 × 月度长表
- 分析统计 — 最新持仓截面、环比（MoM）/同比（YoY）变动、近 12 个月累计净买卖
- 可视化 — 6 张 160 dpi 高清 PNG，中文标签，可直接用于公众号/报告排版
- 结果导出 — UTF-8-BOM 编码 CSV（Excel 直接打开不乱码）+ 文本报告
| 项目 | 内容 |
|---|---|
| 数据源 | ticdata.treasury.gov |
| 含义 | 外国居民持有的美国长期证券（月度） |
| 单位 | 百万美元（图表中转换为亿美元） |
| 频率 | 月度更新，数据滞后约 2 个月 |
| 口径 | 持仓余额（pos）/ 净买入（net，正数=外国增持）/ 估值变动（valchg） |
证券品种：美国国债（Treasuries）、机构债（Agency Bonds）、公司债及其他（Corp. & Other Bonds）、公司股票（Corp. Equity）。
- Python 3.9+（在 Windows + Python 3.13 / pandas 2.2 / matplotlib 3.10 上验证）
- 依赖安装：
pip install -r requirements.txt方式一：Windows 双击运行（开箱即用）
双击 run.bat：启动器会自动探测本机 Python（跳过微软商店占位程序，兼容官方安装版 / Anaconda / 常见路径），依赖缺失时自动执行 pip install，然后完成全流程。
方式二：命令行（任意 Python 3.9+ 环境）
pip install -r requirements.txt
python tic_table1_analysis.py方式三：Jupyter
直接打开本目录的 tic_table1_analysis.ipynb 运行即可。也可以把脚本整段复制进任意 notebook（已兼容：忽略内核参数、路径自动回退到工作目录）。
方式四：VSCode
打开本文件夹，右下角选择任意 Python 3.9+ 解释器，点击 ▶ 运行 tic_table1_analysis.py 即可。
| 参数 | 说明 |
|---|---|
--refresh |
强制重新下载数据（默认使用本地缓存） |
--country "China, Mainland" |
额外绘制指定国家的持仓/净买卖双面板走势图 |
.
├── tic_table1_analysis.py # 主脚本：抓取 → 清洗 → 分析 → 出图 → 导出
├── tic_table1_analysis.ipynb # Jupyter 一键运行入口
├── run.bat # Windows 一键运行入口（自动探测 Python + 装依赖）
├── slt_table1.html # 原始数据缓存（首次运行自动下载）
├── requirements.txt # Python 依赖
├── docs/
│ └── images/ # README 图表预览
└── output/ # 运行输出（gitignore）
├── tic_table1_clean.csv # 清理后的完整数据
├── 1_~5_*.png # 6 张图表
└── report.txt # 文本分析报告
Q: 图表的配色规则是什么？ A: 颜色跟随实体：每个国家/地区在所有图表中固定一种颜色（如「中国大陆」固定为深红），条形图 Top 12 逐国着色，与走势图、净买卖图完全一致。配色经色盲安全校验（相邻色对 CVD ΔE ≥ 8、正常视力 ΔE ≥ 15）。
Q: 持仓与净买卖为什么不用双轴图？ A: 双轴图的两个刻度对齐是任意的，会人为制造视觉相关。本工具将两者拆为共享 x 轴的双面板，各用各的 y 轴刻度，如实呈现。
Q: 无法连接数据源（下载失败）？
A: ticdata.treasury.gov 在部分网络环境（如国内直连）下不可达。可开启系统代理后重试；或直接用浏览器打开数据源页面，另存为 slt_table1.html 放到脚本同目录，脚本会自动使用该文件。下载失败时脚本也会给出此提示。
Q: 数据更新滞后？
A: TIC 官方发布节奏为月度数据滞后约 2 个月，属正常现象。运行 --refresh 即可拉取最新发布版本。
Q: Excel 打开 CSV 乱码？ A: 导出已使用 UTF-8-BOM 编码，Excel 直接打开即可正常显示中文。
本项目仅用于数据研究、学习与内容创作参考，不构成任何投资建议。数据版权归美国财政部所有，使用时请遵守数据源的官方条款。