Lux PandasExecutor 源码级解析:Pandas 执行引擎如何驱动自动化可视化

原创2026-10-12 11:30:241,947 阅读
文章标签:数据可视化数据分析数据科学开发工具

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 数据框操作来抓取并加工其渲染所需的数据。

Lux 系统架构图中包含数据执行层

当前仓库在初始化 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)是每次生成可视化数据的核心入口,其内部按固定顺序执行四步:

  1. 采样:调用 execute_sampling(ldf),必要时对全量数据框采样;
  2. 过滤:调用 execute_filter(vis),把 vis._inferred_intent 中的过滤条件作用于数据;
  3. 属性选择:收集所有 clause 中除 "Record" 之外的属性,只保留这些列参与后续计算;
  4. 按标记类型分流处理:
    • bar / line / geographical → execute_aggregate
    • histogram → execute_binning
    • heatmap → 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 标记的图聚合数据点。核心逻辑:

  1. 通过 vis.get_attr_by_channel("x"/"y") 取出 x、y 通道对应的 clause,确定哪个是分组属性(groupby_attr)、哪个是度量属性(measure_attr)以及聚合函数 agg_func(如 mean、sum、max);
  2. 若 y 通道有聚合则按 x 分组,反之亦然;两个通道都无聚合则直接返回;
  3. 支持 color 通道:若 Vis 指定了 color 属性,则按 [groupby_attr, color_attr] 双键分组;
  4. 当度量属性是 "Record"(即"记录数")时,先 reset_index(),把索引列重命名为 "Record",再对分组结果 count();
  5. 缺值补零:当过滤导致某些分组没有数据点时(isFiltered or has_color 且聚合结果行数少于"分组取值数 × color 基数"),用 right merge 对齐全部取值组合,并把缺失度量值 fillna(0),保证过滤后的柱状图/折线图不丢轴刻度。测试 test_filter_aggregation_fillzero_aligned 验证了 Japan 过滤后 Cylinders==5/8 的均值补零为 0;
  6. 排序与类型兜底:按分组属性升序排序;若排序抛出 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 标记生成直方图数据:

  1. 先把 inf / -inf 替换为 NaN;
  2. 从 vis._inferred_intent 中找到 bin_size != 0 的 clause,取其 bin_size 作为分箱数;
  3. 若列含缺失值,会提示 "The column contains missing values, not shown in the displayed histogram." 并 dropna();
  4. 对象类型列尝试转 float;timedelta64 序列先经 timedelta64_to_float_seconds 转成秒数;
  5. 用 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 做视觉编码的依据。推断顺序如下:

  1. 若属性在 ldf._type_override 中,直接采用用户覆盖的类型(可用 df.set_data_type(...) 手动指定);
  2. timedelta64 序列 → quantitative(同时换算秒数极值);
  3. 真 datetime 类型(is_datetime64_any_dtype)→ temporal;
  4. 可通过 _is_datetime_string 解析的 object 字符串(先尝试 pd.to_numeric 失败再试 pd.to_datetime 成功)→ temporal;
  5. 列名本身是 Timestamp 对象 → temporal;
  6. 列名落入 ["month", "year", "day", "date", "time", "weekday"] → temporal;
  7. _is_datetime_number:整型且 pd.to_datetime(astype(str)) 可解析 → temporal;
  8. _is_geographical_attribute:列名匹配 {"state", "country"}(utils.py)→ geographical;
  9. 浮点列:基数 < 20 且不等于行数 → nominal,否则 quantitative;
  10. 整型列:若 基数/行数 < 0.4 且基数 < 20 → nominal,否则 quantitative;再经 check_if_id_like(高基数 + 名称含 id/ID + 字符串长度均匀)识别为 id;
  11. 字符串列:去掉 NaN 后能 astype("float") → quantitative(并补算 min/max),否则按 id/ nominal 处理;
  12. 其余一律 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 或分析流程中直接复用这些数据加工能力提供了依据。

登录后查看全文
lux