Lux 意图规范(Intent Specification)完全指南:用一行代码向 Lux 传达你的分析意图
Lux 意图规范(Intent Specification)完全指南:用一行代码向 Lux 传达你的分析意图
Lux 是一个"一个 print 自动可视化 pandas DataFrame"的开源库。它的核心交互机制是 intent(意图):通过在 DataFrame 上设置 df.intent,把你想关注的属性、值甚至可视化编码约束告诉 Lux,Lux 就能据此生成精准且相关的推荐图表。本文基于 doc/source/guide/intent.rst 展开,先介绍以字符串简写表达意图的基础用法,再深入 lux.Clause 对象的高级规格,并结合 lux/vis/Clause.py、lux/processor/Parser.py、lux/processor/Compiler.py 等源码,讲透意图从解析、校验到编译成可视化的完整链路。读完本文,你将掌握用字符串与 lux.Clause 两种模式表达属性、值、通配符与编码约束的完整能力。
示例数据为
lux/data/college.csv(美国大学数据),字段包括AverageCost、FundingModel、Expenditure、MedianDebt、MedianEarnings、Region等,与官方教程保持一致。本文所有示例均假设已经import lux。
意图是什么:intent 属性与三种输入形式
Lux 为 DataFrame 提供了一条自定义的 intent 属性(见 lux/core/frame.py 中的 getter/setter)。给 df.intent 赋值时,Lux 会依次执行 Parser(解析)→ Validator(校验)→ Compiler(编译) 三段流水线(_parse_validate_compile_intent 方法):
self._intent = Parser.parse(self._intent) # 字符串简写 → lux.Clause 对象
Validator.validate_intent(self._intent, self) # 校验属性/值是否存在于 DataFrame
self.current_vis = Compiler.compile_intent(self, self._intent) # 生成可渲染的 Vis 集合
intent 接受三种输入(源码中的类型注解为 Union[List[Union[str, Clause]], Vis]):
- 字符串列表:如
['AverageCost'],最常用、最便捷的简写; lux.Clause对象列表:更精细的规格,可携带约束;lux.Vis对象:直接以某个已生成的可视化作为新意图(set_intent_as_vis),实现"点选图表即更新分析方向"。
若传入非列表、非 Vis 的值(如裸字符串 "bad string input"),会抛出 TypeError: Input intent must be either a list ...,该行为由 tests/test_error_warning.py 的 test_intent_str_error 用例锁定。需要清除意图时,调用 df.clear_intent() 即可(df.intent = [] 等价)。
基础描述:用字符串简写表达兴趣
指定关注的属性
最简单的情形是只关注一个属性,例如 AverageCost:
df.intent = ['AverageCost']
你可以在意图中放入多个属性。当指定多个 clause 时,Lux 会应用所有 clause,搜索与 AverageCost 和 FundingModel 都相关的可视化(属性之间是 AND 关系):
df.intent = ['AverageCost','FundingModel']
df
用 | 表达 OR:一组候选属性
如果除了 AverageCost,你还想轮换查看 Expenditure、MedianDebt、MedianEarnings 等财务指标,并观察它们如何随 FundingModel 拆分,可以用 | 分隔多个属性,表示 OR 关系。多个 clause 存在时,Lux 会自动为指定属性做组合枚举:
possible_attributes = "AverageCost|Expenditure|MedianDebt|MedianEarnings"
df.intent = [possible_attributes,"FundingModel"]
df
同样的需求也可以直接给一个 Python 列表,语义一致:
possible_attributes = ['AverageCost','Expenditure','MedianDebt','MedianEarnings']
df.intent = [possible_attributes,"FundingModel"]
df
从源码看,| 拆分与列表拆分最终殊途同归:Parser.parse 会把两种形式都解析成 Clause(attribute=<a href="https://link.gitcode.com/i/ea58afeff0379277df3b5301986f96ef" target="_blank">...])(见 [lux/processor/Parser.py 与 lux/processor/Parser.py),即"属性列表"这种 OR 规格。
指定关注的值:过滤意图
除了属性,还可以指定具体的值,表示你只关心数据的某个子集。例如只关心新英格兰地区的大学:
df.intent = ["Region=New England"]
df
值同样支持 | 多值语法。比如对比新英格兰、东南与远西三个地区大学的 MedianDebt:
df.intent = ["MedianDebt","Region=New England|Southeast|Far West"]
这里生成的是一组基于同一意图的多张可视化(而非常规推荐列表),因此界面会直接展示这些可视化结果。解析逻辑见 lux/processor/Parser.py:字符串含 = 时按过滤规格解析,| 会把等号右侧拆成值列表,最终生成 Clause(attribute="Region", filter_op="=", value=["New England","Southeast","Far West"])。
意图过滤 vs Pandas 直接过滤:关键区别
你可能疑惑:既然能指定值,为什么不直接用 Pandas 过滤 df[df["Region"]=="New England"]?两者有一个微妙但重要的区别——Lux 感知不到 Pandas 的过滤操作:
df[df["Region"]=="New England"]
用 Pandas 过滤后,Lux 只是"看到"一份被过滤后的数据,不会把过滤意图纳入推荐逻辑,因而无法围绕 Region 的过滤做进一步推荐;而通过 df.intent = <a href="https://link.gitcode.com/i/d49fbb1d3541e29c40f0132e396b8a89" target="_blank">"Region=New England"] 显式声明意图后,Lux 的 Filter 动作([lux/action/filter.py 的 add_filter)会建议替换 Region 为其他可能取值、或改用互补的不等号运算(!=)等变体,帮助你围绕过滤条件继续探索:
df.intent = ["Region=New England"]
df
原文的建议是:如果过滤是确定性的数据清理操作(如删除某个数据子集),用 Pandas;如果还想在分析中反复实验、调整过滤条件,则通过 Lux 意图来声明。
高级规格:lux.Clause 对象
字符串简写方便,但表达能力有限。更复杂的规格要用 lux.Clause 对象表达。两种模式本质等价——字符串描述最终由 lux.processor.Parser 解析为 Clause 的各字段(attribute、value、filter_op),因此字符串简写可以看作 Clause 的语法糖。
Clause 的完整构造签名(见 lux/vis/Clause.py):
| 参数 | 类型 | 默认值 | 含义 |
|---|---|---|---|
description |
str / list | "" |
便捷简写描述,由 Parser 解析为其他字段 |
attribute |
str / list | "" |
关注的属性;传列表表示 OR(多个属性任一即可) |
value |
str / list | "" |
关注的值;传列表表示多个值任一 |
filter_op |
str | "=" |
过滤运算:=、<、>、<=、>=、!= |
channel |
str | "" |
编码通道:x、y、color |
data_type |
str | "" |
数据类型:nominal、quantitative、temporal |
data_model |
str | "" |
数据模型:dimension、measure |
aggregation |
str / callable | "" |
聚合函数,默认取 mean;支持 Pandas agg 字符串简写及 numpy 函数 |
bin_size |
int | 0 |
直方图分箱数(默认 10) |
weight |
float | 1 |
0~1 之间的权重,表示该 Clause 的重要性 |
sort |
str | "" |
条形图排序:ascending、descending |
timescale |
str | "" |
时间类型属性是否与时间尺度绑定 |
exclude |
str / list | "" |
通配符枚举时要排除的属性或值 |
其中聚合函数若传 numpy 函数(如 np.ptp),set_aggregation 会通过 __name__ 提取函数名作为 _aggregation_name 供图表标注使用(见 lux/vis/Clause.py)。
用 Clause 指定属性与值
把最开始的 AverageCost 示例改写为 Clause 形式:
df.intent = [lux.Clause(attribute='AverageCost')]
值过滤也可用 Clause 表达,且支持将 value 传为列表:
df.intent = ['MedianDebt',
lux.Clause(attribute='Region',filter_op='=', value=['New England','Southeast','Far West'])]
attribute 与 value 字段都可以是单个字符串或属性/值列表。上面的例子也展示了 lux.Clause 与字符串简写可以混用在同一个意图列表中。
添加约束,覆盖自动推断的细节
前面所有例子中,Lux 都在接收一个"松散的"意图后自动补齐生成图表所需的细节(轴通道、聚合方式、分箱数等)。当你希望覆盖这些自动推断值时,可以在 Clause 上追加约束属性。
把属性固定到指定坐标轴
默认把 AverageCost 作为意图时,Lux 生成的是以 AverageCost 为 x 轴的直方图。若想把它放到 y 轴,只需指定 channel:
df.intent = [lux.Clause(attribute='AverageCost', channel='y')]
df
channel 可取值 x、y、color。该约束在编译阶段由 Compiler.enforce_specified_channel(见 lux/processor/Compiler.py)强制生效:它先收集用户显式指定的通道,替换 ShowMe 自动推荐的通道分配,剩余通道再按自动方案补齐;若同一通道被指定了两个属性,会抛出 ValueError。
修改聚合函数
定量属性默认以 mean 聚合。先看默认效果:
df.intent = ["HighestDegree","AverageCost"]
df
用 aggregation 覆盖为 sum:
df.intent = ["HighestDegree",lux.Clause("AverageCost",aggregation="sum")]
df
聚合取值与 Pandas DataFrame.agg 支持的完全一致:既可以是字符串简写("sum"、"count"、"min"、"max"、"median" 等),也可以是 numpy 聚合函数。例如改成极差(point-to-point,np.ptp):
df.intent = ["HighestDegree",lux.Clause("AverageCost",aggregation=np.ptp)]
df
在 Compiler.determine_encoding 的 ShowMe 逻辑中,若 measure 的 aggregation 为空会自动置为 "mean";散点图场景则会把 aggregation 置为 None(数据不预聚合)。相关行为可参见测试 tests/test_vis.py:aggregation="max" 与 aggregation=np.ptp 都能正确解析并记录 _aggregation_name。另外,将 aggregation 显式设为 None 表示数据已预聚合、不再做聚合运算。
指定通配符(Wildcards)
当你关心 AverageCost 与任意属性的关系时,Lux 支持基于 CompassQL 思想的通配符(wildcard):Clause('?') 表示枚举所有满足给定约束的属性或值。
df.intent = ['AverageCost',lux.Clause('?')]
df
通配符的枚举空间可以用约束缩小。例如只关心 AverageCost 与定量属性的散点图关系,加 data_type='quantitative' 后,可视化数量会从 15 张缩减到仅涉及定量属性的 9 张:
df.intent = ['AverageCost',lux.Clause('?',data_type='quantitative')]
df
通配符也可以放在值上。例如想看 AverageCost 的分布在 Geography 所有可能取值下的变化,两种写法等价:
df.intent = ['AverageCost','Geography=?']
或
df.intent = ['AverageCost',lux.Clause(attribute='Geography',filter_op='=',value='?')]
df
通配符的底层实现在 Compiler.populate_wildcard_options:属性为 ? 时取全部列,再依次与 data_type(利用 invert_data_type)和 data_model 约束做集合交集;值为 ? 时从 ldf.unique_values<a href="https://link.gitcode.com/i/be2336c993e5573bd71b2b031c699114" target="_blank">attr] 展开为该属性的全部唯一值。随后 enumerate_collection 会对这些候选做递归组合,生成 VisList(见 [lux/processor/Compiler.py)。测试 tests/test_vis.py 验证了 VisList(["Height", "SportType=Ball", "?"], df) 这类通配符组合的数量与去重行为(同一属性重复、过滤属性与可视化属性重叠的图会被 remove_all_invalid 剔除)。
意图的校验与常见错误
Validator.validate_intent(见 lux/processor/Validator.py)会在解析后检查意图与 DataFrame 内容的一致性,典型场景包括:
- 属性不存在:给出
The input attribute 'xxx' does not exist in the DataFrame警告,并提示检查拼写; - 值错写成属性:若输入串其实对应某属性的取值,会提示
Please specify the value fully, as something like Region=New England; - 值不存在:当
filter_op == "="且该值不在属性取值集合内时警告(NaN 过滤值与日期时间类型除外)。
此外,Clause 的 exclude 字段可在通配符枚举时排除特定属性/值(Compiler 中通过 str(optStr) not in clause.exclude 判断)。若一个意图会展开为多张可视化(如 Vis 构造函数收到多值规格),还会触发多图合并校验(见 tests/test_error_warning.py 的 test_multi_vis)。
意图与推荐动作的联动
设置意图后,df._ipython_display_()(即直接 df)会展示当前意图直接对应的可视化(Current Vis),并触发各推荐动作(Action)。理解意图格式有助于读懂这些动作的输入输出约定,源码中用两个工具函数区分属性规格与过滤规格(见 lux/utils/utils.py):
get_attrs_specs(intent):筛选value == ""的 Clause,即属性意图;get_filter_specs(intent):筛选value != ""的 Clause,即过滤意图。
基于此,Generalize(lux/action/generalize.py)会移除当前意图中的一个属性或过滤器来生成更宏观的可视化;Filter(lux/action/filter.py)则围绕过滤意图生成替换值、互补运算的候选;Enhance、Column Groups(lux/action/column_group.py)等动作同样以 lux.Clause 为基本单元构造新规格——理解意图的字符串与 Clause 两种表达,就等于掌握了阅读和自定义 Lux 推荐逻辑的钥匙。
小结
- 字符串简写:
['AverageCost']表达属性;'A|B|C'或属性列表表达 OR;'Region=New England'、'Region=New England|Southeast'表达值过滤;两者可与lux.Clause混用。 lux.Clause高级规格:通过attribute、value、filter_op精确指定兴趣点,通过channel、aggregation、bin_size、data_type、data_model、sort、timescale、exclude、weight覆盖自动推断并约束枚举空间。- 通配符
?:Clause('?')枚举任意属性,'Geography=?'枚举任意值,可用data_type/data_model收缩范围。 - 三段流水线:
Parser.parse把字符串解析成 Clause →Validator.validate_intent校验合法性 →Compiler.compile_intent展开通配符、自动填充数据模型、确定编码通道,最终产出可直接渲染的VisList。
掌握意图规范,你就能用极简的表达驱动 Lux 生成高度贴合分析目标的推荐,把"我想看什么"清晰地传达给系统。更完整的架构说明可继续阅读 doc/source/advanced/architecture.rst 与 doc/source/guide/vis.rst。













