本文详解如何基于美国财政部拍卖数据，使用 pandas 高效计算按日、按证券类型划分的国债净发行量（issued − maturing），提供简洁可复用的代码实现与关键注意事项。
本文详解如何基于美国财政部拍卖数据，使用 pandas 高效计算按日、按证券类型划分的国债净发行量（issued − maturing），提供简洁可复用的代码实现与关键注意事项。
美国国债净发行量（Net Issuance）是衡量财政融资动态的核心指标，定义为当日新发行总额减去当日到期兑付总额，即：
$$ \text{Net Issuance} = \text{Issued} - \text{Maturing} $$
该指标按证券类型（如 Bill、Note、Bond、CMB 等）分层统计，能清晰反映不同期限结构的供给变化，对利率分析、流动性预测及宏观政策研判具有重要参考价值。
数据准备与预处理
首先需从美国财政部公开 API 获取拍卖记录。推荐使用 treasury-gov-pandas 库（或自行封装请求逻辑），获取包含 issue_date、maturity_date、security_type 和 total_accepted 字段的数据集。关键预处理步骤如下：
import pandas as pd
import requests
# 示例：手动下载（替代 treasury-gov-pandas）
def download_auctions(start_date='2024-01-01'):
url = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v1/accounting/od/auctions_query"
params = {
'filter': f'record_date:gt:{start_date}',
'page[size]': 10000
}
response = requests.get(url, params=params)
if response.status_code == 200:
data = response.json()['data']
return pd.DataFrame(data)
else:
raise ConnectionError(f"API request failed: {response.status_code}")
df = download_auctions('2024-03-01')
# 类型转换与清洗
df['issue_date'] = pd.to_datetime(df['issue_date'])
df['maturity_date'] = pd.to_datetime(df['maturity_date'])
df['total_accepted'] = pd.to_numeric(df['total_accepted'], errors='coerce')
df = df.dropna(subset=['issue_date', 'maturity_date', 'total_accepted', 'security_type'])✅ 注意：total_accepted 值为字符串格式（含逗号），必须用 pd.to_numeric(..., errors='coerce') 安全转换；缺失或异常值应主动剔除，避免影响聚合结果。
核心计算：一步式净发行量生成
相比原始代码中多次 groupby + merge 的显式连接，更符合 Pandas “向量化思维”的写法是——将发行与到期分别映射到同一日期维度后横向拼接，再统一计算差值：
# 构建发行表（按 issue_date 聚合）
issued = (
df.assign(date=df['issue_date'])
.groupby(['date', 'security_type'])['total_accepted']
.sum()
.rename('issued')
)
# 构建到期表（按 maturity_date 聚合）
maturing = (
df.assign(date=df['maturity_date'])
.groupby(['date', 'security_type'])['total_accepted']
.sum()
.rename('maturing')
)
# 合并并计算净发行量（自动对齐，缺失补0）
net_issuance = (
pd.concat([issued, maturing], axis=1, join='outer')
.fillna(0)
.eval('net_issuance = issued - maturing')
.reset_index()
)
# 透视为宽表：每列为证券类型，每行为日期
result = net_issuance.pivot_table(
index='date',
columns='security_type',
values='net_issuance',
fill_value=0
).round(2) # 可选：保留两位小数提升可读性
print(result.tail())输出示例（截取部分）：
security_type Bill Bond CMB Note date 2024-03-19 2.452518e+11 0.000000e+00 1.600022e+11 1.280000e+11 2024-03-20 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00
关键优势与最佳实践
- 语义清晰：pd.concat(..., join='outer') 自动处理“仅发行”“仅到期”“两者兼有”三类情形，无需手动 merge 与 fillna 多次调用；
- 性能高效：避免中间 DataFrame 创建与列重命名，减少内存开销；
- 健壮性强：eval() 直接支持表达式运算，且 pivot_table(fill_value=0) 比 pivot().fillna(0) 更鲁棒（自动处理未出现的证券类型组合）；
- 可扩展友好：若需添加“再融资比例”“加权平均期限”等衍生指标，只需在 net_issuance DataFrame 上追加列即可。
注意事项总结
- 时间粒度一致性：确保 issue_date 与 maturity_date 均为 datetime64[ns] 类型，否则 groupby 可能因精度问题导致分组失败；
- 证券类型标准化：原始数据中 security_type 可能存在大小写混用（如 'bill' vs 'Bill'）或空格，建议统一 .str.strip().str.title()；
- 历史数据完整性：财政部 API 默认仅返回近期记录，如需长期序列（如1980年至今），需分批次拉取并合并去重；
- 单位统一：total_accepted 单位为美元，结果默认为“美元”，若需“十亿美元”显示，可在最终结果上调用 div(1e9).round(3)。
通过上述方法，你可在数秒内完成万级记录的净发行量计算，并无缝集成至自动化监控或量化研究流程中。
