做临床研究、meta 分析或者 NMA 的人，森林图是绑定出图。R 里现有的工具不少——forestplot、forestploter、forester、meta::forest()——但用下来都多少有些不顺手：

• 很多包的 API 偏”配置式”，参数一多就变成巨长的函数调用，想调整布局得翻文档猜参数名
• 想要的面板组合经常不在预设里：比如左边文本、中间 CI、右边再来一列柱状图，基本要自己拼
• 分组行、汇总行、条纹、分隔线这些装饰性元素，每个包的处理方式都不一样
• 想给特定行换颜色、换形状，往往要改底层数据或者用很 hack 的方式

所以我写了 panelforest。

核心想法很简单：森林图本质上就是几列面板横向拼在一起，每列有自己的渲染逻辑。 那就不要把它当成一个”森林图函数”来设计，而是让用户自己声明”我要哪些列、每列长什么样”，剩下的事情交给引擎。

项目地址：https://github.com/lenardar/panelforest

长什么样

先看结果：

这张图是一个 NMA 安全性数据的森林图，包含：

• 左侧文本列（亚组标签）
• 中间文本列（OR 数值）
• 右侧 CI 面板（对数刻度、参考线、截断箭头、favors 标注）
• 分组行加粗、行间分隔线、条纹背景
• 不同比较用不同颜色和形状区分

生成这张图的代码大概 30 行，全部是管道式组合。

怎么用

基本结构

1
2
3
4
5
6
7
8
9

library(panelforest)

forest_plot(df) |>            # 传入数据
  add_stripe(...) |>          # 条纹背景
  add_group(...) |>           # 分组行
  add_hline(...) |>           # 分隔线
  add_text(...) |>            # 文本列
  add_ci(...) |>              # CI 面板
  fp_render()                 # 渲染

每个 add_*() 就是往布局里追加一列面板。顺序决定了从左到右的排列。想调整布局，移动调用顺序就行。

面板类型

目前内置了这些面板：

• add_text() / fp_text() — 纯文本列，支持对齐、缩进、格式化函数
• add_text_ci() / fp_text_ci() — 把 est/lower/upper 三列自动格式化成 “0.45 (0.32, 0.61)”
• add_ci() / fp_ci() — 置信区间可视化，支持对数刻度、截断箭头、菱形汇总、favors 标注
• add_bar() / fp_bar() — 水平柱状图
• add_dot() / fp_dot() — 散点 + 误差线
• add_gap() / fp_gap() — 固定宽度间距
• add_spacer() / fp_spacer() — 绝对单位间距（mm）
• fp_custom() — 自定义面板，传入一个返回 ggplot 的函数

不够用的时候，fp_custom() 加上 fp_register() 可以注册自定义面板类型，引擎会自动纳入渲染流程。

列驱动的美学映射

跟 ggplot2 的 aes() 思路类似，panelforest 用 fp_aes() 把数据列映射到视觉属性：

1
2
3
4
5
6

# 数据里有 ci_colour 和 ci_shape 两列
forest_plot(df) |>
  add_ci("OR", "LCI", "UCI",
    mapping = fp_aes(colour = "ci_colour", shape = "ci_shape")
  ) |>
  fp_render()

这样每一行可以有不同的颜色和形状，不需要手动逐行设置。

统一的 edit() 编辑层

想给某些行做特殊处理？一个 edit() 函数搞定行级、单元格级、行高调整：

1
2
3
4
5
6
7
8
9
10

forest_plot(df) |>
  add_text("label", header = "Subgroup") |>
  add_ci("HR", "LCI", "UCI", header = "HR") |>
  # 第 1 行用菱形
  edit(row = 1, panel = "HR", glyph = "diamond", fill = "#dbeafe") |>
  # 第 2-4 行斜体
  edit(row = 2:4, fontface = "italic") |>
  # 第 5 行加高
  edit(row = 5, height = 1.5) |>
  fp_render()

panel 参数可以用索引、标题字符串或列名来定位，不需要记面板编号。

跨列分组标题

多个面板可以用 add_header_group() 加父级标题，层级自动推断：

1
2
3
4
5
6

forest_plot(df) |>
  add_text("label", header = "Drug A") |>
  add_text("n_events", header = "Drug B") |>
  add_ci("HR", "LCI", "UCI", header = "HR") |>
  add_header_group("Treatment", panels = 1:2, border = TRUE) |>
  fp_render()

支持多层嵌套——包含其他分组的分组会自动升至更高层。

设计上的一些取舍

为什么基于 ggplot2 + patchwork

每个面板本质上是一个独立的 ggplot 对象，最终用 patchwork 横向拼接。这个选择有几个好处：

• 继承 ggplot2 的渲染质量和主题系统
• 每个面板的坐标系独立，CI 面板可以用对数刻度，文本面板用 [0, 1] 坐标，互不干扰
• patchwork 的布局系统天然支持比例宽度和固定宽度混合
• 输出是标准 ggplot 对象，ggsave() 直接用

缺点是性能——面板多、行数多的时候渲染会慢。但森林图通常几十行到一两百行，这个量级下完全没有问题。

为什么不做 ggplot2 的 geom

另一条路是写 geom_forest() 这样的扩展。我没走这条路，因为森林图的本质是”多列异构面板”，每列的坐标系和渲染逻辑完全不同。硬塞进一个 ggplot 的 facet 或者 annotation 系统里会很别扭。

patchwork 的多面板方案更自然——每列是独立的 ggplot，互不干扰但共享行坐标。

fp_size() 的存在意义

森林图的尺寸应该由内容决定，不应该让用户猜 width 和 height。fp_size() 根据面板数量、行数和行高自动计算出精确的英寸尺寸：

1
2
3

size <- fp_size(plot_obj)
ggsave("forest.png", fp_render(plot_obj),
  width = size["width"], height = size["height"])

这样不管你加几列面板、数据有多少行，出图的密度和比例都是一致的。

CI 面板的细节

fp_ci() 是功能最密集的面板，支持的东西比较多：

• 对数刻度：trans = "log"，自动处理正值约束和刻度标签
• 截断箭头：CI 超出显示范围时，用箭头提示截断方向，箭头类型可配置 (arrow_type = "open" / "closed")
• 菱形汇总：add_summary() 标记的行自动渲染为菱形
• favors 标注：favors_left / favors_right 在坐标轴下方画方向箭头和标签
• 参考线：ref_line 画虚线
• 美学映射：通过 fp_aes() 让每行有不同的颜色、形状、大小

这些功能单独看都不复杂，但组合起来就能覆盖绝大多数临床研究的森林图需求。

一个完整例子

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

library(panelforest)

df <- data.frame(
  label = c("Overall", "Age < 65", "Age >= 65", "Male", "Female"),
  HR = c(0.72, 0.68, 0.81, 0.75, 0.69),
  LCI = c(0.58, 0.49, 0.61, 0.55, 0.48),
  UCI = c(0.89, 0.94, 1.07, 1.02, 0.99)
)

plot_obj <- forest_plot(df) |>
  add_stripe(c("white", "#f4f7f5")) |>
  add_summary(1) |>
  add_hline(1) |>
  add_text("label", header = "Subgroup", width = 2, align = "left") |>
  add_text_ci("HR", "LCI", "UCI", header = "HR (95% CI)", width = 2) |>
  add_ci("HR", "LCI", "UCI",
    header = "Hazard Ratio",
    trans = "log",
    width = 3,
    show_axis = TRUE,
    favors_left = "Favors treatment",
    favors_right = "Favors control"
  )

size <- fp_size(plot_obj)
ggsave("forest.png", fp_render(plot_obj),
  width = size["width"], height = size["height"],
  dpi = 300, bg = "white")

从数据到出图，代码结构很清晰：数据 → 装饰 → 面板 → 渲染。想调整布局就移动 add_*() 的顺序，想改样式就加 edit()。

后续计划

panelforest 目前是 v0.2.0，核心功能已经稳定。后续打算做的事情：

• forest_plot_from() — 模型直出森林图：传入 glm、coxph、lm 等模型对象，自动生成森林图。底层基于 broom::tidy()，根据模型类型自动推断效应量（OR/HR/β）和坐标变换。逐步适配 lme4、metafor、brms 等更多包。
• add_rule() — 条件样式：声明式规则批量高亮，替代逐行 edit()
• 更多坐标变换：sqrt、logit 等
• 文本自动换行、导出助手、脚注系统等体验优化

最重要的是模型直出这个方向——让 panelforest 不只是一个画图工具，而是能直接对接统计建模的输出，减少”跑完模型还要手动整理数据再画图”这个环节。

项目地址：https://github.com/lenardar/panelforest

做数据分析的人，大概率都在 pandas 和 tidyverse 之间摇摆过。

如果你长期写 R，dplyr / tidyr / stringr 那套东西会很顺手：选列有 selector，批量变换有 across()，宽长表转换、字符串处理、缺失值处理都有比较统一的入口。

但一旦切到 Python，虽然 pandas 功能很强，日常清洗时还是经常会冒出几个问题：

• 想按前缀、类型、条件批量选列，不够统一
• 想对一批列做同样的处理，assign(...) 经常要自己手搓字典
• 想把清洗步骤写成稳定、可复用、可读的链，容易堆很多一次性 lambda
• 从 tidyverse 迁移过来时，肌肉记忆没地方放

所以我写了 TidyPy4DS。

它不是想重写 pandas，也不是想做另一个复杂框架，而是只补一小块真正不够顺手的地方：列选择、批量变换、字符串处理、宽长表转换，以及更自然的 .pipe() 链式体验。

项目地址：https://github.com/lenardar/TidyPy4DS

这个项目想解决什么

一句话说，函数名尽量跟 tidyverse，接口行为坚持 Python / pandas。

也就是说：

• 不做 SQL DSL
• 不做惰性执行引擎
• 不替代 groupby、merge、assign 这些已经很成熟的 pandas 原生能力
• 只把最容易重复、最容易写散的那部分动作收成统一入口

目前项目里最核心的几组能力是：

• selector 系统：starts_with、contains、numeric、where 等
• 批量变换：mutate_across
• 批量改名：rename_with
• 汇总：summarize
• 结构查看：glimpse
• 条件映射：case_when、if_else、recode
• 宽长表转换：pivot_longer、pivot_wider
• 缺失值处理：drop_na、fill_na、replace_na
• 表头清理：clean_names、remove_empty、row_to_names

一个简单对比：纯 pandas vs tidypy

先看一份很常见的数据：

1
2
3
4
5
6
7
8
9

import pandas as pd

df = pd.DataFrame({
    "employee_id": [101, 102, 103, 104, 105],
    "dept": ["Sales", "Sales", "Tech", "Tech", "HR"],
    "score_math": [92.0, None, 88.0, 79.0, None],
    "score_eng": [85.0, 90.0, None, 82.0, 87.0],
    "name": [" Alice ", "Bob ", " Carol", "David", " Frank "],
})

目标很普通：

• 只保留 ID、分组、分数字段和名字
• 用每列中位数填补缺失值
• 去掉 score_ 前缀
• 去掉名字前后空格
• 按数学成绩做一个等级
• 最后按分组汇总

纯 pandas 写法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

pandas_result = (
    df.loc[:, ["employee_id", "dept", "score_math", "score_eng", "name"]]
    .assign(
        score_math=lambda x: x["score_math"].fillna(x["score_math"].median()),
        score_eng=lambda x: x["score_eng"].fillna(x["score_eng"].median()),
    )
    .rename(columns={"score_math": "math", "score_eng": "eng"})
    .assign(
        name=lambda x: x["name"].str.strip(),
        level=lambda x: pd.Series(
            ["A" if v >= 90 else "B" if v >= 80 else "C" for v in x["math"]],
            index=x.index,
        ),
    )
)

这段代码当然没问题，而且完全是标准 pandas。

但你会发现几个特点：

• 分数字段被显式写了两遍
• 改名前后的列名都要手动维护
• 当类似列变多时，改动面会越来越大

tidypy 写法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

from tidypy.tidy import (
    case_when,
    clean_names,
    mutate_across,
    rename_with,
    select,
    starts_with,
)

tidypy_result = (
    clean_names(df)
    .pipe(
        select,
        "employee_id",
        "dept",
        starts_with("score_"),
        "name",
    )
    .pipe(
        mutate_across,
        starts_with("score_"),
        lambda s: s.fillna(s.median()),
    )
    .pipe(
        rename_with,
        lambda c: c.replace("score_", ""),
        starts_with("score_"),
    )
    .assign(
        name=lambda x: x["name"].str.strip(),
        level=lambda x: case_when(
            (x["math"] >= 90, "A"),
            (x["math"] >= 80, "B"),
            default="C",
        ),
    )
)

它并不是神奇地比 pandas 少很多代码。

真正的区别在于：你开始把“哪些列属于同一类”和“这批列要做什么”分开表达了。

这个分离在小数据上可能只是“看着顺一点”，但一旦你多加一个 score_logic 列，差别就出来了：

• 纯 pandas 版本通常要改多处显式列名
• selector 版本通常只要让新列符合 score_ 规则，主流程基本不用改

如果再往真实一点的数据走，差异会更明显。比如很多 Excel 导出来的原始表根本不是“干净 DataFrame”，而是：

• 列名里有空格、括号和标点
• 第一行才是真正的表头
• 后面还夹着全空行、全空列

这时候我最近补进去的一批 janitor 风格函数就比较顺手了：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

from tidypy.tidy import clean_names, remove_empty, row_to_names

raw = pd.DataFrame(
    [
        ["Patient ID", "Score Math", None],
        [1, 90, None],
        [2, 88, None],
        [None, None, None],
    ]
)

result = (
    raw
    .pipe(row_to_names, row=0)
    .pipe(remove_empty, axis="both")
    .pipe(clean_names)
)

这类东西单看都不复杂，但它们经常正好卡在“pandas 原生当然能做，只是每次都要重写一遍”的位置上。

核心设计：先把列选择系统做对

这个项目里最重要的抽象其实不是 mutate_across()，而是 ColSelector。

所有 helper 都返回一个 selector 对象，真正操作时再结合 df 解析出列名。

比如：

1
2
3

select(df, numeric() | starts_with("id"))
select(df, everything() - contains("tmp"))
mutate_across(df, where(lambda s: s.isnull().any()), lambda s: s.fillna(0))

这样做有几个明显好处：

• helper 可以访问列名，也可以访问 dtype 或数据本身
• selector 可以组合
• 列选择逻辑可以复用，而不是散落在各处

我最后定下来的规则也比较简单：

• | 表示并集
• - 表示排除
• 结果去重且保序
• 解析不到列时直接报错，不静默忽略

这套东西一旦稳定下来，后面的 select、mutate_across、rename_with、pivot_longer 都会自然顺很多。

一个我刻意没有做的东西：裸列名 NSE

如果熟悉 tidyverse，可能第一反应会问：

能不能做成 mutate(df, total=a + b) 这种效果？

答案是：理论上可以硬做，实际上不值得。

在 R 里，mutate() 这种体验背后是 tidy evaluation；Python 没有这一层语言机制。真要做，只能走 eval、AST 改写、代理对象这些路线。

这种东西最大的风险不是“写不出来”，而是：

• 报错不直观
• 调试很差
• 和 pandas 生态不一致
• 一旦边界复杂起来，很容易变成一套脆弱的语法魔法

所以我最后的取舍是：

• 不做裸列名 NSE
• 保留 assign(...) 处理少量显式新列
• 用 mutate_across(...) 解决批量变换
• 用 case_when(...)、if_else(...)、recode(...) 解决条件映射和重编码

这套方案不花哨，但更稳。

glimpse() 也是我很想要的一个小东西

在 notebook 里，head() 看值，info() 看结构，但两者之间总觉得差一口气。

所以我顺手加了一个 glimpse()：

1
2
3

from tidypy.tidy import glimpse

glimpse(df)

它会给出：

• 行数、列数
• 每列 dtype
• 非空数、缺失数
• 唯一值数量
• 前几条样本值预览

而且支持：

1
2

glimpse(df, cols=starts_with("score_"))
print(glimpse(df, as_text=True, display=False))

这玩意不大，但在实际 notebook 里非常顺手。

现在这个项目是什么状态

目前 TidyPy4DS 已经有一版可以直接用的实现，仓库里也把几件基础设施补上了：

• 双语 README
• 双语函数文档
• 双语 notebook 示例
• unittest 测试
• GitHub Actions CI
• 一批偏 janitor 风格的小函数

示例 notebook 分成了三类：

• Why tidypy：直接对比纯 pandas 和 tidypy
• Core APIs：看 selector、mutate_across、summarize 这些核心能力
• Reshape and missing values：看 pivot_longer、pivot_wider、separate、unite、缺失值处理

项目整体还在早期阶段，但核心方向已经比较清楚：

• selector 系统要稳定
• API 要尽量少而清晰
• 不做多余包装
• 不和 Python 自身的直觉打架
• 单文件实现先保持，但内部已经按模块整理，后续可拆

最后

这个项目本质上不是在和 pandas 对抗，而是在承认一件事：

pandas 很强，但确实有一些高频清洗动作，写起来就是不够顺。

如果能用一层很薄的 helper，把这些动作收成更统一、可复用、可读的入口，那它就值得存在。

如果你也经常在 pandas 和 tidyverse 的思路之间切换，TidyPy4DS 也许会正好补上你手感里缺的那一块。

最近我自己的感受也更明确了：这个项目最有价值的地方，不是“把 tidyverse 完整搬到 Python”，而是把那些每天都会写、但又总写得零碎的数据清洗动作，收成一套尽量干净的小工具。

项目地址：https://github.com/lenardar/TidyPy4DS