做什么（One-liner）

美国产出缺口：FRED GDPC1 → HP 滤波 λ=1600 → gap_pct = (actual - trend) / trend * 100。Canvas 经 macro_snapshot_v1 暴露的 output_gap_pct 字段来源。正值 → 扩张过热；负值 → 经济松弛。

怎么用

Canvas 间接使用（macro_snapshot_v1 → output_gap_pct）。也可直接调用内部 Python：

from services.mfle.output_gap import get_output_gap
result = get_output_gap(limit_quarters=80)
# {available, output_gap_pct, trend_latest, actual_latest, as_of_date, logic_lineage}

核心公式

if not fred_available():
  return {available: False, reason: 'FRED_API_KEY not set', ...}

gdp = fetch_series('GDPC1', limit=80)
trend = hp_filter(gdp, λ=1600)          # see hp_filter card
cycle = gdp.reindex(trend.index).ffill().bfill() - trend
gap_pct = (cycle / trend) * 100

return {
  output_gap_pct:  round(gap_pct[-1], 2),
  trend_latest:    round(trend[-1], 2),
  actual_latest:   round(gdp[-1], 2),
  as_of_date:      YYYY-MM-DD,
  logic_lineage:   ['hp_filter', 'GDPC1']
}

Rounding 契约：所有 numeric 字段 round(2)。

假设与适用场景

假设：US FRED GDPC1 + HP λ=1600 quarterly 标准 + ≥5 obs + percent-of-trend (非 dollar)。

适用：Canvas 宏观 overlay 的 output_gap 字段、macro_snapshot 组件、经济过热 vs 松弛判断。

不适用：monthly / intraday、非美国、CBO-style 精确复现、需要 real-time 稳定的 endpoint 估计。

输入 / 输出契约

get_output_gap(limit_quarters?=80) → {available, output_gap_pct, trend_latest, actual_latest, as_of_date, logic_lineage} (primary) 或 {available: False, reason} (failure).

已知局限

1. 端点偏差（inherited from HP）：最新季度 gap 不稳；2-3 季度后 revise
2. Only GDPC1 / 非美国不支持
3. vs CBO 差异显著：CBO 用 production function，本 operator 是 HP simplified
4. gap 是 percent of trend（不是 dollar）
5. HP 过滤 lookahead default full-sample（实时应用需每期重跑，结果 revise）
6. limit_quarters=80 default — 更长 lookback 增 HP cost
7. No bootstrap CI / structural break（Hamilton 2018 批判）

参考文献

Hodrick-Prescott (1997) HP 原 paper + CBO (2024) 官方产出缺口方法 + Orphanides-van Norden (2002) 实时估计不可靠性。详见 frontmatter。

Golden Test

tests/golden/fixtures/tier3/output_gap/，captured_snapshot（HP primitive 独立 cross-validated）。1e-6 tolerance. 11 tests:

• compute_positive_gap — 正缺口场景 byte-equal
• compute_negative_gap — 负缺口场景
• compute_short_series_insufficient — len<5 → available=False
• compute_none_input — None → available=False
• get_output_gap_fred_ok — 完整路径（monkey-patched FRED）
• get_output_gap_fred_unavail — FRED 断 → reason='FRED_API_KEY not set'
• get_output_gap_fetch_none — fetch=None → reason='fetch GDPC1 failed'
• determinism — 5 reruns 一致
• rounding_contract — round(2) on all numeric
• logic_lineage — fixed ['hp_filter', 'GDPC1']
• formula_contract — gap == (actual - trend) / trend * 100

Changelog

• 1.0.0 (2026-04-21) — 首次 Active（Tier 3 batch 3.2, HP composition）