skills/ppt-station-skill/reference/layout-waterfall.md

Layout: waterfall — 瀑布图/归因分析

幻灯片尺寸: 13.333 × 7.5 英寸 | 边距: 0.6 英寸 | 内容宽: 12.133 英寸

---

用途

收益归因、成本分解、利润桥图（Profit Bridge）、组合贡献分析。 展示"从起点 → 各因素贡献 → 终点"的累积变化过程。

---

ASCII 线框图

┌─────────────────────────────────────────────────────────────┐
│ [标题]                                          y=0.25       │
│ ▬▬ (accent 装饰线 2.0")                         y=0.90       │
│                                                              │
│  起始值        增加项    增加项    减少项    最终值           │
│  ┌──────┐      ┌──────┐                                     │
│  │      │      │ +██  │ +██      │      │                   │
│  │ 基础 │      │      │          │ -██  │ ┌──────┐          │
│  │      │      │      │          │      │ │ 合计 │          │
│  └──────┘      └──────┘          └──────┘ └──────┘          │
│   8.50%        +2.10%  +1.30%   -1.80%   10.10%            │
│  [期初收益]   [权益贡献] [债券贡献] [汇率拖累] [期末收益]   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

---

数据结构说明

瀑布图数据包含：

• start — 起始值（期初，作为第一个完整柱）
• items — 各贡献因素（浮动柱，正向或负向）
• end — 终止值（期末，作为最后一个完整柱，可自动计算）

---

精确坐标标注

固定元素

元素	x	y	w	h	字号	颜色	对齐
页面标题	0.60	0.25	12.133	0.60	title_size-2	text_dark	左
装饰线	0.60	0.90	2.00	0.04	—	accent	—
零基准线	0.60	图表区中心	12.133	0.02	—	text_muted	—

图表区域

参数	值	说明
chart_x	0.60	图表左边界
chart_y	1.30	图表顶部（内容区起始）
chart_w	12.133	图表宽度
chart_h	5.50	图表高度（到 y=6.80）
bar_area_h	4.00	柱体绘制区高度（y=1.50 ~ y=5.50）
label_y	5.60	标签行 y（柱下方）
value_y	1.20	数值标注 y（柱上方，浮动）
footer_y	6.20	数据来源行

柱体尺寸计算

N = len(items) + 2    # 总柱数（start + items + end）
bar_gap = 0.20        # 柱间距（英寸）
bar_w = (chart_w - bar_gap * (N - 1)) / N   # 每柱宽

# N=5: bar_w = (12.133 - 0.80) / 5 = 2.267"
# N=6: bar_w = (12.133 - 1.00) / 6 = 1.856"
# N=7: bar_w = (12.133 - 1.20) / 7 = 1.562"
# N=8: bar_w = (12.133 - 1.40) / 8 = 1.342"

bar_x[i] = chart_x + i * (bar_w + bar_gap)

柱体高度计算

# 图表坐标系
y_axis_max = max(所有累积值的最大值) * 1.15    # 留 15% 上边距
y_axis_min = min(所有累积值的最小值) * 1.15    # 留 15% 下边距（负值时）
y_range = y_axis_max - y_axis_min

# 将数据值映射到像素（英寸）
def value_to_y(v):
    return chart_y + bar_area_h * (1 - (v - y_axis_min) / y_range)

# 起始柱（完整柱，从0到start_value）
start_bar_top = value_to_y(start_value)
start_bar_bottom = value_to_y(0)
start_bar_h = start_bar_bottom - start_bar_top

# 贡献柱（浮动柱，从累积值到累积值+delta）
for item in items:
    bar_top = value_to_y(max(cumsum, cumsum + item.value))
    bar_bottom = value_to_y(min(cumsum, cumsum + item.value))
    bar_h = bar_bottom - bar_top
    cumsum += item.value

# 连接虚线（前一柱的浮动底部 → 当前柱底部）
连接线: w=bar_gap, h=0.01, 颜色=text_muted, 虚线样式

颜色规则

柱类型	条件	颜色变量
起始柱	—	primary
正向贡献柱	item.value > 0	positive
负向贡献柱	item.value < 0	negative
终止柱	—	primary
连接虚线	—	text_muted

数值标注（柱顶/底 + 数值）

元素	位置	字号	颜色	格式
起始/终止数值	柱顶上方 0.10"	body_size	text_dark	"X.XX%"
正向贡献值	柱顶上方 0.10"	body_size	positive	"+X.XX%"
负向贡献值	柱底下方 0.10"	body_size	negative	"-X.XX%"
柱体内标注（高柱时）	柱体垂直居中	body_size-1	text_light	同上

底部标签行

元素	x	y	w	h	字号	颜色	对齐
柱体标签	bar_x[i]	5.60	bar_w	0.45	caption_size	text_muted	中

---

数据接口

data = {
    "title": str,                    # 页面标题
    "subtitle": str,                 # 可选，如 "2024年全年收益归因分析"
    "start": {
        "label": str,                # 如 "期初收益"
        "value": float,              # 如 8.50
        "value_fmt": str,            # 如 "8.50%" 或 "850亿"
    },
    "items": [
        {
            "label": str,            # 贡献因素名称（8字以内）
            "value": float,          # 数值（正=向上，负=向下）
            "value_fmt": str,        # 显示文字（如 "+2.10%"）
            "direction": "up" | "down",  # 可选，若不传则根据 value 符号判断
        },
        ...
    ],
    "end": {
        "label": str,                # 如 "期末收益"
        "value": float | None,       # None则自动计算(start + sum(items))
        "value_fmt": str | None,
    },
    "unit": str,                     # 可选，如 "%" 或 "亿元"，用于Y轴标注
    "show_connector": bool,          # 是否显示连接虚线，默认 True
}

---

实现伪代码

def layout_waterfall(slide, data, theme):
    m = theme["margin"]
    sw = 13.333
    cw = sw - 2 * m    # 12.133

    set_slide_bg(slide, theme["bg_light"])
    add_text(slide, data["title"],
             x=m, y=0.25, w=cw, h=0.60,
             font_size=theme["title_size"]-2, color=theme["text_dark"],
             bold=True, font_name=theme["header_font"])
    add_rect(slide, m, 0.90, 2.0, 0.04, fill=theme["accent"])

    # 计算柱体布局
    all_bars = [data["start"]] + data["items"] + [data["end"]]
    N = len(all_bars)
    bar_gap = 0.20
    bar_w = (cw - bar_gap * (N - 1)) / N

    chart_y = 1.50
    bar_area_h = 4.00

    # 计算值域
    cumsum = data["start"]["value"]
    all_values = [0, cumsum]
    for item in data["items"]:
        cumsum += item["value"]
        all_values.append(cumsum)
    end_val = data["end"].get("value") or cumsum
    all_values.append(end_val)

    y_max = max(all_values) * 1.15
    y_min = min(all_values) * 1.15 if min(all_values) < 0 else 0
    y_range = y_max - y_min

    def val_to_y(v):
        return chart_y + bar_area_h * (1 - (v - y_min) / y_range)

    # 绘制零线
    zero_y = val_to_y(0)
    add_rect(slide, m, zero_y, cw, 0.015, fill=theme["text_muted"])

    # 绘制柱体
    cumsum = 0
    prev_top_y = None
    for i, bar in enumerate(all_bars):
        bx = m + i * (bar_w + bar_gap)
        is_total = (i == 0 or i == N - 1)

        if is_total:
            v = bar.get("value", cumsum)
            top_y = val_to_y(max(v, 0))
            bot_y = val_to_y(min(v, 0))
            color = theme["primary"]
        else:
            v = bar["value"]
            base = cumsum
            top_y = val_to_y(max(base, base + v))
            bot_y = val_to_y(min(base, base + v))
            color = theme["positive"] if v >= 0 else theme["negative"]
            cumsum += v

        bar_h = bot_y - top_y
        add_rect(slide, bx, top_y, bar_w, bar_h, fill=color)

        # 连接线
        if prev_top_y is not None and data.get("show_connector", True) and not is_total:
            add_rect(slide, bx - bar_gap, prev_top_y, bar_gap, 0.01,
                     fill=theme["text_muted"])
        prev_top_y = bot_y if v >= 0 else top_y

        # 数值标注
        fmt = bar.get("value_fmt", f"{v:+.2f}%")
        label_y = top_y - 0.30 if v >= 0 else bot_y + 0.05
        add_text(slide, fmt,
                 x=bx, y=label_y, w=bar_w, h=0.28,
                 font_size=theme["body_size"], color=color,
                 bold=True, align="center", font_name=theme["body_font"])

        # 底部标签
        add_text(slide, bar["label"],
                 x=bx, y=5.60, w=bar_w, h=0.45,
                 font_size=theme["caption_size"], color=theme["text_muted"],
                 align="center", font_name=theme["body_font"])

---

设计要点

1. 柱间连接虚线 从前一柱的"累积底部"水平延伸到当前柱，帮助读者追踪累积过程
2. 数值标注位置: 正向柱标在顶部上方，负向柱标在底部下方（避免遮挡柱体）
3. 起始/终止柱（汇总柱）用 primary 色，与贡献柱颜色形成视觉区分
4. 最多 8 个柱（含起始和终止）；超过时建议合并小贡献项为"其他"
5. 含负值时：零线显示并加粗（0.02"），负值柱延伸到零线以下

---

测试数据示例

data = {
    "title": "2024年组合收益归因分析",
    "subtitle": "单位: 百分点（%）",
    "start": {"label": "期初基准", "value": 0, "value_fmt": "0%"},
    "items": [
        {"label": "权益资产", "value": 3.20, "value_fmt": "+3.20%"},
        {"label": "债券资产", "value": 1.80, "value_fmt": "+1.80%"},
        {"label": "另类资产", "value": 0.90, "value_fmt": "+0.90%"},
        {"label": "汇率影响", "value": -0.60, "value_fmt": "-0.60%"},
        {"label": "费用扣除", "value": -0.30, "value_fmt": "-0.30%"},
    ],
    "end": {"label": "期末收益", "value": None, "value_fmt": None},  # 自动计算=5.00%
}

---

与 投行级研报 GTM 的对应

投行级研报 P4（GDP分解）、P44（EPS贡献）等页面均使用堆叠柱变体。 真正的"利润桥"瀑布图（浮动柱）在收益归因报告中极为常见，需单独布局支持。