Lux PandasExecutor 源码级解析:Pandas 执行引擎如何驱动自动化可视化
Lux PandasExecutor 源码级解析:Pandas 执行引擎如何驱动自动化可视化
Lux 的核心卖点是"一行 print 自动可视化 pandas 数据框",而真正把 Vis 规格转成可渲染图表数据的,正是默认执行引擎 lux.executor.PandasExecutor.PandasExecutor。本篇以官方 API 参考文档(doc/source/reference/gen/lux.executor.PandasExecutor.PandasExecutor.rst)为骨架,结合 PandasExecutor.py 源码与 tests/test_executor.py 测试用例,系统讲解它的采样、过滤、聚合、分箱、二维分箱与数据元信息计算等完整执行管线,以及它如何通过 lux.config 参与 Lux 的整体工作流,让读者既会用又能理解底层原理。
PandasExecutor 在 Lux 架构中的定位
Lux 的体系结构分为用户界面层、输入解析校验层、意图处理层、数据执行层和数据分析层,各层均可替换。数据执行层抽象为一个 Executor 基类(见 Executor.py),声明了 execute、execute_aggregate、execute_binning、execute_filter、execute_2D_binning、compute_stats、compute_data_type、compute_dataset_metadata 等接口;PandasExecutor 是该基类的 Pandas 实现,其类文档自述为:
Given a Vis objects with complete specifications, fetch and process data using Pandas dataframe operations.
即:给定一个规格完备的 Vis 对象,用 Pandas 数据框操作来抓取并加工其渲染所需的数据。
当前仓库在初始化 LuxDataFrame 时,默认把执行器设置为 Pandas:
# lux/core/frame.py:73-76
if lux.config.SQLconnection == "":
from lux.executor.PandasExecutor import PandasExecutor
lux.config.executor = PandasExecutor()
如需切换执行后端,通过 lux.config.set_executor_type("Pandas") 或 "SQL" 显式指定(config.py)。以下所有分析均针对 Pandas 后端。
主入口 execute:一条完整的可视化数据管线
PandasExecutor.execute(vislist, ldf, approx=False)(PandasExecutor.py)是每次生成可视化数据的核心入口,其内部按固定顺序执行四步:
- 采样:调用
execute_sampling(ldf),必要时对全量数据框采样; - 过滤:调用
execute_filter(vis),把vis._inferred_intent中的过滤条件作用于数据; - 属性选择:收集所有 clause 中除
"Record"之外的属性,只保留这些列参与后续计算; - 按标记类型分流处理:
bar/line/geographical→execute_aggregatehistogram→execute_binningheatmap→execute_2D_binning(当approx=True时先降级为 scatter 用于早期剪枝)
处理结束后会清空 vis.data._intent,避免意图元数据污染可视化数据。
execute 的调用方遍布整个项目,构成完整的调用链:
- VisList.py:
lux.config.executor.execute(self._collection, ldf, approx=approx),推荐列表渲染时调用; - Vis.py:
refresh_source中实例化单个 Vis 时调用; - frame.py 与 frame.py:
current_vis惰性求值时调用; to_code(language="python")(Vis.py)导出可复现代码时同样会先执行execute再通过 tracer 记录执行行。
大规模数据采样:execute_sampling 与 execute_approx_sample
整体数据采样 execute_sampling
execute_sampling(ldf)(PandasExecutor.py)负责为整张数据框计算并缓存一份样本,阈值由 lux.config 控制:
| 配置项 | 默认值 | 说明 |
|---|---|---|
lux.config.sampling |
True |
是否启用采样 |
lux.config.sampling_start |
100000(10 万行) |
超过该行数开始采样,取 75% 作为样本 |
lux.config.sampling_cap |
1000000(100 万行) |
行数超过该上限时,直接截断到上限行数 |
其逻辑为:
SAMPLE_FRAC = 0.75
if SAMPLE_FLAG and len(ldf) > SAMPLE_CAP:
ldf._sampled = ldf.sample(n=SAMPLE_CAP, random_state=1) # 截断采样
elif SAMPLE_FLAG and len(ldf) > SAMPLE_START:
ldf._sampled = ldf.sample(frac=SAMPLE_FRAC, random_state=1) # 75% 采样
else:
ldf._sampled = ldf # 数据量小,直接使用
样本结果缓存在 ldf._sampled(_sampled is None 时才会重新采样,即备忘化),避免重复计算。触发采样时,Lux 会向用户追加一条提示消息,例如 "Large dataframe detected: Lux is only visualizing a sample capped at 1000000 rows."。两个阈值在 config.py 中定义,且约束 sampling_start <= sampling_cap(setter 中有断言校验,见 config.py)。
近似样本 execute_approx_sample:为有趣度剪枝加速
当可视化搜索空间过大时,Lux 会用一份近似样本(缓存于 ldf._approx_sample)来加速"有趣度"(interestingness)的早期剪枝,从而避免对每张候选图都执行完整计算(PandasExecutor.py):
- 若
len(ldf._sampled) > lux.config.early_pruning_sample_start,则从中抽取early_pruning_sample_cap行作为近似样本; - 否则直接复用
_sampled。
相关配置默认值为 early_pruning_sample_cap = 30000、early_pruning_sample_start = early_pruning_sample_cap * 1.5(即 45000 行,见 config.py)。是否启用近似计算由 VisList.py 决定:当推荐数量超过 lux.config.topk + 3 且数据行数超过 early_pruning_sample_start 时,approx=True 被传入 execute。此时 vis._mark 会被临时改为 "scatter",待剪枝完成后由渲染层(如 AltairRenderer.py)重新调用 execute_2D_binning 恢复为真正的 heatmap。
过滤:execute_filter 与 apply_filter
execute_filter(vis)(PandasExecutor.py)先从 vis._inferred_intent 中筛出所有"带过滤值"的 clause(value != ""),再逐个调用 apply_filter。它返回布尔值标识是否执行过过滤,该返回值随后被传给 execute_aggregate 用于"缺值补零"逻辑。若 vis.data 为空会直接断言报错。
apply_filter(df, attribute, op, val)(PandasExecutor.py)是过滤的底层实现,支持以下运算符:
| 运算符 | 行为 | 示例 |
|---|---|---|
= |
等值过滤 | df[df[attribute] == val] |
< |
小于 | df[df[attribute] < val] |
> |
大于 | df[df[attribute] > val] |
<= |
小于等于 | df[df[attribute] <= val] |
>= |
大于等于 | df[df[attribute] >= val] |
!= |
不等 | df[df[attribute] != val] |
NaN 过滤有特殊处理:当过滤值本身是 NaN(通过 utils.py 的 like_nan 识别)时,只允许使用 = 或 !=,分别等价于 df[attribute].isna() 与 ~df[attribute].isna();若对 NaN 使用 <、> 等运算会发出警告。这与常规 SQL 语义一致:NaN 不可比较大小。
测试验证(tests/test_executor.py):
vis = Vis([lux.Clause(attribute="Horsepower", filter_op=">", value=50),
lux.Clause(attribute="MilesPerGal")])
vis._vis_data = df
PandasExecutor.execute_filter(vis)
assert len(vis.data) == 386 # Horsepower > 50 过滤后的行数
聚合:execute_aggregate(柱状图 / 折线图)
execute_aggregate(vis, isFiltered=True)(PandasExecutor.py)为 bar、line、geographical 标记的图聚合数据点。核心逻辑:
- 通过
vis.get_attr_by_channel("x"/"y")取出 x、y 通道对应的 clause,确定哪个是分组属性(groupby_attr)、哪个是度量属性(measure_attr)以及聚合函数agg_func(如 mean、sum、max); - 若 y 通道有聚合则按 x 分组,反之亦然;两个通道都无聚合则直接返回;
- 支持
color通道:若 Vis 指定了 color 属性,则按[groupby_attr, color_attr]双键分组; - 当度量属性是
"Record"(即"记录数")时,先reset_index(),把索引列重命名为"Record",再对分组结果count(); - 缺值补零:当过滤导致某些分组没有数据点时(
isFiltered or has_color且聚合结果行数少于"分组取值数 × color 基数"),用 right merge 对齐全部取值组合,并把缺失度量值fillna(0),保证过滤后的柱状图/折线图不丢轴刻度。测试 test_filter_aggregation_fillzero_aligned 验证了 Japan 过滤后Cylinders==5/8的均值补零为 0; - 排序与类型兜底:按分组属性升序排序;若排序抛出
TypeError(说明该列混有混合类型),会警告用户并建议df['attr'] = df['attr'].astype(str),随后自动转字符串再排序。
代码在 PandasExecutor.py 中分别实现了带 color 与不带 color 的 "Record" 计数聚合:
vis._vis_data = vis.data.groupby(groupby_attr.attribute, dropna=False, history=False) \
.count().reset_index() \
.rename(columns={index_name: "Record"})
分箱:execute_binning(直方图)
execute_binning(ldf, vis)(PandasExecutor.py)为 histogram 标记生成直方图数据:
- 先把
inf/-inf替换为NaN; - 从
vis._inferred_intent中找到bin_size != 0的 clause,取其bin_size作为分箱数; - 若列含缺失值,会提示 "The column contains missing values, not shown in the displayed histogram." 并
dropna(); - 对象类型列尝试转 float;
timedelta64序列先经timedelta64_to_float_seconds转成秒数; - 用
np.histogram(series, bins=bin_attribute.bin_size)计算频数,输出列为[bin_attr, "Number of Records"]。
测试 test_binning 断言直方图结果行数恰好等于 nbins。
二维分箱:execute_2D_binning(热力图)
execute_2D_binning(vis)(PandasExecutor.py)为散点数据生成 heatmap 单元格数据:
- 先用
pd.cut(..., bins=lux.config.heatmap_bin_size)对 x、y 两列分别分箱(默认 40 箱,见 config.py),生成xBin、yBin; - 若指定了 color 通道,按
["xBin", "yBin"]分组聚合 color 属性:nominal 类型取众数(majority vote,并列时取第一个),quantitative / temporal 类型取均值,并同时统计每组count; - 若没有 color,则对 x 分组计数,生成
count列并剔除 0 值单元格; - 最后把
xBin/yBin的左右边界展开为xBinStart、xBinEnd、yBinStart、yBinEnd四个浮点列,供后续加权相关(weighted_correlation,见 interestingness.py)等有趣度计算使用。
元信息计算:数据框统计与数据类型推断
compute_stats:唯一值、基数与极值
compute_stats(ldf)(PandasExecutor.py)预计算三份元信息并挂载到 LuxDataFrame:
ldf.unique_values:每列的唯一值列表(Timestamp 列以日期字符串作键);ldf.cardinality:每列唯一值个数;ldf._min_max:浮点/整型列的(min, max)极值。
compute_data_type:五类数据类型的启发式推断
compute_data_type(ldf)(PandasExecutor.py)为每个属性推断数据类型,是 Compiler 做视觉编码的依据。推断顺序如下:
- 若属性在
ldf._type_override中,直接采用用户覆盖的类型(可用df.set_data_type(...)手动指定); timedelta64序列 →quantitative(同时换算秒数极值);- 真 datetime 类型(
is_datetime64_any_dtype)→temporal; - 可通过
_is_datetime_string解析的 object 字符串(先尝试pd.to_numeric失败再试pd.to_datetime成功)→temporal; - 列名本身是 Timestamp 对象 →
temporal; - 列名落入
["month", "year", "day", "date", "time", "weekday"]→temporal; _is_datetime_number:整型且pd.to_datetime(astype(str))可解析 →temporal;_is_geographical_attribute:列名匹配{"state", "country"}(utils.py)→geographical;- 浮点列:基数 < 20 且不等于行数 →
nominal,否则quantitative; - 整型列:若
基数/行数 < 0.4且基数 < 20 →nominal,否则quantitative;再经 check_if_id_like(高基数 + 名称含 id/ID + 字符串长度均匀)识别为id; - 字符串列:去掉 NaN 后能
astype("float")→quantitative(并补算 min/max),否则按 id/ nominal 处理; - 其余一律
nominal。
推断完成后,若存在"疑似 temporal 但并非 datetime 类型"的列,会发出详细警告,给出 pd.to_datetime 转换模板,并提示可用 df.set_data_type({'attr': 'quantitative'}) 覆盖自动推断的类型。
compute_dataset_metadata:元信息入口
compute_dataset_metadata(ldf)(PandasExecutor.py)清空 ldf._data_type 后调用 compute_data_type,是元数据计算的统一入口。它经由 frame.py 的 compute_metadata 被 maintain_metadata 调用,并受 lux.config.lazy_maintain(默认 True)控制:仅在 _metadata_fresh 为假时才重新计算,配合 expire_metadata 实现惰性维护。
数据模型换算:invert_data_type 与 compute_data_model
PandasExecutor 从基类 Executor 继承了数据模型换算能力(Executor.py),API 参考文档中列出的 mapping、reverseMapping、invert_data_type、compute_data_model、compute_data_model_lookup 均在此实现:
| 方法 | 作用 |
|---|---|
mapping(rmap) |
把 {属性: 数据类型} 字典按 quantitative / id / nominal / temporal / geographical 五类反向分组为 {类型: [属性列表]} |
reverseMapping(map) |
把分组字典还原为 {属性: 类型} 查询表 |
invert_data_type(data_type) |
即 mapping(data_type),得到按类型分组的属性字典 |
compute_data_model(data_type) |
生成数据模型:measure = quantitative;dimension = nominal + temporal + id + geographical |
compute_data_model_lookup(data_type) |
返回 {属性: measure/dimension} 的查找表 |
measure/dimension 数据模型决定了属性在视觉编码中的角色:度量列进入数值轴,维度列进入分类轴。该模型在编译阶段被 Compiler.py(compute_data_model_lookup(ldf.data_type))与 Compiler.py(invert_data_type + compute_data_model)广泛使用;frame.py 也用它识别 id 类字段并在生成推荐时提示 "is not visualized since it resembles an ID field."
配置与实战:如何观察、调参与验证
关键配置速查(config.py)
| 配置 | 默认值 | 影响 |
|---|---|---|
lux.config.sampling |
True |
是否启用整体采样 |
lux.config.sampling_start |
100000 |
触发 75% 采样的行数阈值 |
lux.config.sampling_cap |
1000000 |
采样截断上限(需 ≥ sampling_start) |
lux.config.early_pruning |
True |
是否启用有趣度早期剪枝 |
lux.config.early_pruning_sample_cap |
30000 |
近似样本行数上限 |
lux.config.heatmap_bin_size |
40 |
heatmap 分箱数 |
lux.config.lazy_maintain |
True |
元数据/推荐是否惰性维护 |
lux.config.topk |
15 |
每个 action 展示的可视化数量上限 |
手动触发执行管线
在 Jupyter 环境中,可以通过构造 Vis 直接驱动执行器,观察 vis.data 中的加工结果:
import lux
from lux.vis.Vis import Vis
from lux.executor.PandasExecutor import PandasExecutor
df = lux.LuxDataFrame(pd.read_csv("lux/data/car.csv"))
vis = Vis([lux.Clause(attribute="Horsepower", aggregation="mean"),
lux.Clause(attribute="Origin")])
PandasExecutor.execute([vis], df)
print(vis.data.head()) # 分组聚合后的 LuxDataFrame
PandasExecutor 的方法均可被外部模块直接复用,例如 interestingness.py 在计算过滤后行数时直接调用 PandasExecutor.apply_filter;custom.py 在自定义 action 中调用 lux.config.executor.execute(vlist, ldf)。
导出可复现代码
得益于 execute 与 tracer 的结合,vis.to_code("python")(Vis.py)会把本次执行涉及的 Pandas 操作还原成可独立运行的 Python 代码;也可通过 vis.to_code("altair"/"vegalite"/"matplotlib") 导出对应绘图库的代码。
用测试用例印证行为
仓库的 tests/test_executor.py 是理解 PandasExecutor 行为的最佳参考,覆盖了惰性执行、属性选择、聚合正确性、彩色柱状图/折线图维度、过滤器、分箱、Record 计数与过滤补零等场景,例如 test_aggregation 验证 mean/sum/max 聚合值与手工 groupby 结果一致。此外 test_zexport.py 之外的 tests/test_zexport.py 也大量以 PandasExecutor.execute([vis], df) 作为导出功能的前置准备。
小结
PandasExecutor 是 Lux 默认且最常用的数据执行引擎,它以"采样 → 过滤 → 属性选择 → 按标记分流加工"的四步管线,把用户意图编译出的 Vis/VisList 规格物化为可直接渲染的图表数据;同时承担了数据框统计、数据类型推断与 measure/dimension 数据模型换算等元信息职责。理解它的每个方法(execute_sampling、execute_filter、execute_aggregate、execute_binning、execute_2D_binning、compute_stats、compute_data_type 等)与对应配置项,既能帮助你读懂 Lux 的可视化生成链路,也为在自定义 action 或分析流程中直接复用这些数据加工能力提供了依据。