简介这份压缩包面向数据挖掘与机器学习初学者、教学者以及希望研究可视化分析工具的开发者提供开源软件 Orange 的完整源码与配套资料可用于搭建交互式数据分析流程、开展课程实验、学习组件化建模并进行二次开发也可用于教学演示与原型验证。包内共 2000 个文件以 png 界面截图与示例图、py 脚本、txt 与 rst 说明文档、svg 图标、cpp 与 hpp 源码以及 tab、csv、arff 数据表为主另含 Makefile、CMake、vcproj、sln 等构建配置压缩包约 19.26MB便于从源码、文档和示例数据三个层面理解软件结构。已有 2102 人学习下载。Orange 的图形界面基于跨平台 Qt 框架将数据预处理、数据账目、过渡、可视化、建模、模式评估与勘探整合其中并保留 Python 脚本扩展能力读者可据此梳理组件设计、查看算法实现、复现示例工作流并积累跨 C 与 Python 项目的阅读和调试经验。1. 从“一个压缩包”说起解压一个数据挖掘和机器学习的压缩包你期待看到什么是几个写死路径的 demo 脚本还是一份需要自己拼装的环境清单Orange 这个开源项目给出的答案是一整套可以在画布上拖拽连线的工作台。读数据、清洗缺失值、特征变换、训练模型、交叉验证、混淆矩阵、散点图与箱线图每一步都是画布上一颗可以双击配置的方块方块之间用线连起来一条完整的数据挖掘流水线就跑起来了。它适合两类人一类是不想写几十行样板代码就为了跑一次聚类和 ROC 曲线的分析人员另一类是想搞清楚“可视化编程工具内部到底怎么组织数据流”的开发者。这个项目把 Python 生态里的 numpy、pandas、scikit-learn 包了一层同时又保留了一条完整的 Python 逃生通道这意味着你可以全程不写代码也可以在任意一个环节插进自己的脚本。2. 架构拆解控件、画布与数据管道Orange 不是一个单体脚本而是一个分层的桌面临界应用。把它拆开看最外层是画布canvas中间层是控件widget最里层是数据结构与算法data / preprocess / classification / regression / ensemble / evaluation。理解这三层的关系比记住任何一个 API 都重要因为后面所有的改造动作本质上都是在某一层上加东西。2.1 控件是主体画布只是容器很多可视化编程工具会把“节点类型”做成配置项Orange 不是。在 Orange 里一个控件就是一个 Python 类继承自OWWidget类体里用声明式的方式描述自己的输入、输出和持久化设置。画布不关心控件内部干什么它只做三件事把控件实例化、把上游输出连到下游输入、在需要的时候调用对应的方法。这套机制的关键在于两点。第一控件的输入输出是通过类属性声明的不是通过构造函数传参。第二控件之间的数据传递走的是“推送”而不是“拉取”上游数据变了下游的 setter 会被调用。这带来的一个直接后果是写控件时你必须自己决定“什么时候把结果推下去”推早了性能崩推晚了界面卡。常见的写法是把重计算放进一个延迟提交的通道里用户拖动滑块的过程中只更新界面松手或者停顿几百毫秒后才真正计算from Orange.widgets import gui from Orange.widgets.widget import OWWidget, Input, Output from Orange.widgets.settings import Setting class OWZScoreFilter(OWWidget): name Z-Score Filter description 按 Z 分数剔除离群样本 icon icons/zscore.svg priority 1300 # 类体里声明的输入/输出画布靠它建立连线规则 class Inputs: data Input(Data, Table) class Outputs: data Output(Data, Table) # 类属性即持久化字段保存 .ows 时自动写入 threshold Setting(3.0) def __init__(self): super().__init__() self.data None box gui.vBox(self.controlArea, 过滤参数) # callback 里只做“请求重算”不直接算 gui.doubleSpin(box, self, threshold, 0.5, 10.0, 0.5, labelZ 阈值, callbackself._invalidate) gui.rubber(self.controlArea) def _invalidate(self): # 老版本里是 self.commit()新版本拆成了 deferred / now self.commit.deferred()Setting在这里不只是个装饰器它是控件状态持久化的入口用户在界面上把阈值调成 2.5保存工作流后下次打开.ows文件这个值会原样恢复。这也是为什么参数不要在__init__里硬写死而要交给Setting声明——一旦你写成self.threshold 3.0覆盖掉类属性持久化就失效了这种坑在后面还会再说一次。priority决定控件在左侧目录里的排序icon指向图标资源description会出现在鼠标悬停提示里。这些字段看着琐碎但一个控件想在菜单里“像个原生控件”这几项一个都不能少。2.2 目录结构算法层和界面层是分开的源码树的划分很能说明设计意图。核心算法层不依赖任何 Qt 组件你在服务器上 import 它跑批处理完全没问题界面层才引入 PyQt/PySide 那一套东西。目录/包职责是否依赖 GUIOrange/data/Table、Domain、Variable整个项目的数据契约否Orange/preprocess/缺失值填补、离散化、连续化、特征选择否Orange/classification/、Orange/regression/各类学习器的封装否Orange/ensemble/随机森林、梯度提升等集成方法否Orange/evaluation/交叉验证、测试集评估、评分指标否Orange/projection/、Orange/distance/降维与距离度量否Orange/widgets/按业务域分包的控件实现是Orange/canvas/画布主程序、方案存取、控件注册表是Orange/widgets/下面通常按data、visualize、model、evaluate、unsupervised、utils这样的业务域再分包每个包里一个文件一个控件外加同名的icons/目录。这种“一个控件一个文件”的约定值得学控件之间几乎不互相 import公共逻辑抽到同级的小工具模块里避免改一个控件连带把整个包拖崩。算法层与界面层分离还有一个实际好处你要给某个模型加个自定义损失函数只需要动classification/下的封装不用碰任何界面代码反过来你要改交互也基本不会影响模型行为。二次开发时先判断自己改的是哪一层能省掉大量无谓的调试。2.3 数据管道Table 是唯一的流通货币控件之间传递的东西绝大多数时候是一个Table对象。它不是一个裸的 DataFrame而是带“域”的结构化数据from Orange.data import Table, Domain, ContinuousVariable, DiscreteVariable # 手工构造一个最小的 Table age ContinuousVariable(age) churn DiscreteVariable(churn, values(no, yes)) domain Domain([age], churn) # 特征列 / 目标列 data Table.from_numpy(domain, X[[31], [45], [52]], Y[0, 1, 0])Domain里区分了几个位置attributes是特征存在X里class_vars是目标存在Y里metas是元数据存在metas里比如样本 ID、时间戳。这个划分贯穿整个项目——“读数据”控件负责把 CSV 的列映射到这三类上后面的模型控件只认X和Y画图控件则可能把metas里的字段拿来当标签。变量类型同样重要。DiscreteVariable带values元组索引到名字的映射就固定下来了ContinuousVariable则是浮点。一旦某列的变量类型判断错了下游的模型可能直接报“不支持离散输入”或者悄悄把类别当成数值算均值这种错误不会抛异常只会让你的准确率莫名其妙地低一截。Table同时支持稀疏矩阵文本挖掘那类高维稀疏场景下不会炸内存。代价是你写控件时不能假设data.X一定是稠密的 ndarray涉及全量数值运算前先确认一下或者用np.asarray转一次。3. 跑起来从环境到第一个可复现的流水线装不上或者装上了打不开是这类桌面工具最常见的劝退点。Orange 的依赖里既有科学计算栈又有 Qt混装环境翻车的概率不低。这一节按“先隔离、再图形、后脚本”的顺序走一遍。3.1 环境隔离与安装不要往系统 Python 或者某个已有的大环境里装。Qt 的版本冲突是玄学问题一旦和别的桌面库撞上报错信息往往指向完全无关的模块。# 新建一个干净环境Python 版本建议 3.10 ~ 3.12 conda create -n orange3 python3.11 -y conda activate orange3 # 装主程序pip 走清华源会快很多 pip install orange3 # 启动画布 python -m Orange.canvaspython -m Orange.canvas和命令行里的orange-canvas是等价的前者在排查启动问题时更好用因为你能直接看到完整的 Python traceback。第一次启动会加载所有已注册控件耗时十几秒属于正常之后有缓存会快很多。如果需要从源码跑想改核心代码就得这么干把源码目录拉下来在同一个环境里执行pip install -e .做开发模式安装之后改代码重启画布即可生效不用反复重装。提示Linux 上如果启动时报 Qt 平台插件加载失败绝大多数情况是缺系统级的 xcb 相关库而不是 Python 包装错了。先确认这一点再去折腾 pip能少走很多弯路。安装完成后左侧会出现控件目录树中间是空白画布。把“File”拖进来、双击选一个自带数据集比如 iris再从“Model”里拖一个逻辑回归连上去最后接一个“Test Score”整条链路就通了。这一步能跑通说明环境和核心依赖都没问题。3.2 用脚本复现画布上的工作流画布上的每一次连线背后都是一次函数调用。把这些调用手写出来你就能在不能开图形界面的机器上比如跑实验的服务器复现同一套流程。import Orange from Orange.data import Table from Orange.preprocess import Impute from Orange.classification import LogisticRegressionLearner from Orange.evaluation import CrossValidation, scoring # 1. 读数据Orange 自带 iris也可以换成 Table(your.csv) data Table(iris) # 2. 预处理对缺失值做均值/众数填补 data Impute()(data) # 3. 定义学习器 learner LogisticRegressionLearner(penaltyl2, C1.0) # 4. 5 折交叉验证 result CrossValidation(k5, random_state42)(learner, data) # 5. 取指标 print(CA :, scoring.CA(result)) print(AUC:, scoring.AUC(result, multi_classweighted))这段代码和画布上的File → Impute → Logistic Regression → Test Score完全等价。关键点在于Impute()这类预处理器本身是可调用对象传进去一个Table吐出一个新TableCrossValidation(k5)返回的是一个评估器它接收“学习器 数据”返回带预测结果的结果对象指标从结果对象里取。random_state一定要固定。交叉验证的折分是随机的不固定种子你每次跑出来的数字都不一样调参时根本分不清是参数起作用还是折分运气好。这个习惯我在做对比实验时踩过不止一次同一个模型前后两次跑出 3 个点的差距白折腾一下午。多分类场景下scoring.AUC需要指定multi_class策略weighted会按每类样本数加权macro则每类等权。二分类可以省略这个参数但一旦数据里目标变量有三个以上取值不传会直接报错。3.3 无界面批量跑把工作流当配置文件真正的落地场景很少只跑一个数据集。更常见的是一批 CSV 放在目录里同一套流程刷一遍最后把指标汇总成一张表。这时候.ows工作流文件的另一个价值就体现出来了——它本质上是 JSON里面的每个节点都记录了控件名和参数设置。import glob import pandas as pd import Orange from Orange.data import Table from Orange.classification import TreeLearner from Orange.evaluation import CrossValidation, scoring rows [] for path in sorted(glob.glob(data/*.tab)): data Table(path) # 只保留有目标变量的表否则评估无从谈起 if data.domain.class_var is None: continue learner TreeLearner(max_depth6, min_leaf5) res CrossValidation(k5, random_state0)(learner, data) rows.append({ dataset: path.split(/)[-1], n_samples: len(data), CA: float(scoring.CA(res)), AUC: float(scoring.AUC(res)), }) print(pd.DataFrame(rows).to_string(indexFalse))这里用TreeLearner(max_depth6, min_leaf5)而不是默认参数是因为不加限制的决策树在样本量不大的表上几乎必然过拟合交叉验证的分数会异常漂亮换一批数据就原形毕露。min_leaf控制叶子最少样本数是抑制过拟合最直接的一个旋钮。整个循环里没有出现任何 GUI 相关代码这正是第 2 章说的层间分离带来的好处。如果你想把这套流程固化成团队共用的规范可以把参数抽成一个 dict 放在配置里脚本只负责读取和执行改参数不用改代码。4. 核心代码从零写一个能用的控件会跑现成的流程只是第一步。Orange 真正的扩展点在于你可以往里塞自己的控件做完之后它和原生控件在画布上没有任何区别可以连线、可以被别人复用。这一节把上一节的OWZScoreFilter补全。4.1 骨架类声明决定了一切控件的类体不是随便写的OWWidget在实例化时会扫描类上的这些描述符把它们注册到控件注册表和画布的信号系统里。所以顺序通常是先写元信息name / icon / priority再声明Inputs/Outputs最后写Setting字段。from AnyQt.QtWidgets import QLabel from Orange.data import Table from Orange.widgets import gui from Orange.widgets.widget import OWWidget, Input, Output, Msg from Orange.widgets.settings import Setting import numpy as np class OWZScoreFilter(OWWidget): name Z-Score Filter description 按 Z 分数剔除离群样本 icon icons/zscore.svg priority 1300 keywords [outlier, filter, 离群] class Inputs: data Input(Data, Table) class Outputs: data Output(Data, Table) threshold Setting(3.0) # 自定义警告画布顶部会出现黄色三角提示 class Warning(OWWidget.Warning): all_removed Msg(阈值过小所有样本都被过滤掉了) def __init__(self): super().__init__() self.data None box gui.vBox(self.controlArea, 过滤参数) gui.doubleSpin(box, self, threshold, 0.5, 10.0, 0.5, labelZ 阈值, callbackself._invalidate) gui.rubber(self.controlArea) self.info_label QLabel(尚未接收数据) self.controlArea.layout().addWidget(self.info_label)Input(Data, Table)里第一个参数是通道名会显示在画布上的连接点旁边第二个是类型画布靠它判断能不能连。如果下游控件要求Table而上游吐的是np.ndarray线就连不上——这不是 bug是类型契约在起作用。class Warning这种嵌套声明是 Orange 提供的一套轻量反馈机制。用self.Warning.all_removed()触发用self.Warning.all_removed.clear()清除。它比弹对话框温和得多不会打断用户的操作流。4.2 输入处理与输出推送真正干活的逻辑放在被Inputs.data装饰的方法里。这个方法由画布在连线建立或上游数据变化时调用参数就是上游传来的对象。Inputs.data def set_data(self, data): self.data data self._invalidate() def _invalidate(self): self.commit.deferred() def commit_now(self): 真正计算并向下游推送由 commit 机制调度 data self.data if data is None: self.info_label.setText(尚未接收数据) self.Outputs.data.send(None) return X np.asarray(data.X, dtypefloat) if X.size 0 or X.shape[1] 0: # 只有目标变量、没有特征的表原样往下传 self.Outputs.data.send(data) return mu np.nanmean(X, axis0) sd np.nanstd(X, axis0) # 常量列标准差为 0直接除会产生 inf这里兜底成 1 sd[sd 0] 1.0 z np.abs((X - mu) / sd) mask np.all(z self.threshold, axis1) filtered data[mask] if len(filtered) 0: self.Warning.all_removed() else: self.Warning.all_removed.clear() self.info_label.setText(f{len(filtered)} / {len(data)} 条保留) self.Outputs.data.send(filtered)几个必须注意的点。np.nanmean而不是mean因为 Orange 的Table里缺失值以nan存储用普通均值会得到nan整个筛选逻辑直接崩。常量列的标准差是 0除法会产生infnp.abs之后和阈值比较永远为假那些列上的样本会被全部误杀——这是很隐蔽的一类错误表现出来就是“一开过滤样本全没了”。最后data[mask]是Table支持的布尔索引返回的是原表的一个子集视图Domain会一并带过去下游不需要重新映射列。self.Outputs.data.send(filtered)才是数据真正流出去的瞬间。如果忘了这一句界面上看起来一切正常信息标签也在变但下游控件永远是空的——新手最常见的“我明明算出来了为什么下游没反应”十有八九是漏了 send。注意commit.deferred()会合并短时间内的多次请求适合滑块这种高频交互。如果是按钮触发的重计算用commit.now()更直观。老版本 Orange 里对应的是self.commit()和gui.deferred装饰器迁移代码时留意一下。4.3 注册到画布entry point 那一行不能省控件写完了放在源码目录里画布是看不到的。它需要在包的安装元数据里注册画布启动时扫描所有已安装包的 entry point把控件收集进注册表。# setup.py 节选 from setuptools import setup, find_packages setup( nameorange3-zscore, version0.1.0, packagesfind_packages(include[orangecontrib, orangecontrib.*]), install_requires[Orange33.32, numpy], entry_points{ # 左边是分组名右边是控件所在的模块路径 orange.widgets: [ ZScore orangecontrib.zscore.widgets, ], }, )目录组织上按惯例把控件放进orangecontrib/你的包名/widgets/模块里导出一个控件类列表画布加载这个模块时读取它。开发阶段用pip install -e .装一次之后改控件代码只需重启画布只有改entry_points这类元数据时才需要重新安装。注册成功后控件会出现在左侧目录的对应分组里。如果分组名不是你想要的位置可以在模块里额外声明分类信息。不同版本的注册细节略有差异最稳的做法是照着官方 add-on 模板改别自己从零猜格式。5. 避坑与排查五个真实会卡住的地方这一节记的都是实际调试中反复出现的问题按“现象 → 原因 → 解决”写遇到同类症状可以直接对号入座。5.1 启动闪退报 Qt 平台插件加载失败现象命令行敲下去窗口闪一下就没了或者直接抛出一段关于platform plugin/xcb的错误。原因环境里同时存在多个 Qt 后端PyQt5 与 PySide 混装、或某个系统级 Qt 库抢先被加载也可能是 Linux 上缺少 xcb 相关系统库。这类问题和 Orange 本身关系不大纯粹是二进制依赖打架。解决新建一个全新环境只装orange3及其依赖不装任何其他 GUI 库确认环境里只有一个 Qt 后端。Linux 下把缺失的系统库补齐再试。如果是通过 conda 装的优先用 conda 的包而不是 pip 重装能减少二进制不匹配的概率。5.2 自己写的控件在菜单里找不到现象代码写好了pip install -e .也执行了重启画布后左侧目录里翻遍了都没有。原因三种可能——忘了配entry_points模块路径写错画布 import 失败但没有明显报错控件类没被模块导出注册表扫不到。解决先用python -c import orangecontrib.yourpkg.widgets单独 import 一次把语法错误和依赖缺失暴露出来再确认entry_points里的模块路径和实际目录完全一致大小写敏感最后确认模块里确实导出了控件类。启动画布时如果加了-v之类的详细日志import 失败的信息会打出来比盲猜快得多。5.3 两个控件连不上线现象把线从输出点拖到输入点松手后线消失或者能连上但下游立刻报类型错误。原因输入声明的类型和上游输出的类型不匹配。画布是按类型做兼容判断的Table只接TableTable和np.ndarray之间不会自动转换。解决检查两边Input/Output的第二个参数是否一致。如果确实需要传别的类型比如自定义的Model包装对象两边都要用同一个类。注意继承关系也会被考虑子类通常能连到父类通道上反过来不行。5.4 参数改了下游不动现象在控件里拖动滑块自己的信息标签在变但下游的表格、图表纹丝不动。原因计算做了但没调self.Outputs.xxx.send(...)或者调了commit.deferred()却没实现对应的提交方法延迟请求被静默丢弃。解决在commit_now结尾加一行日志确认真的执行到了再看 send 是否被调用。延迟提交的机制依赖框架回调如果你用的是自定义方法名记得和框架约定的一致否则永远不会被触发。5.5 大数据集下界面卡死现象加载一个几十万行的表画布直接假死风扇狂转。原因控件的输入方法里做了全量计算而set_data是在主线程里被调用的。上游一变主线程就开始算界面自然没法响应。解决把重计算挪到提交阶段输入方法里只存引用、发提交请求确实需要耗时的计算考虑放到后台线程并把结果回传。另外在线计算时尽量用向量化避免在 Python 层写逐行循环——np.nanmean和逐行for在十万行量级上的差距是几十倍。6. 二次开发的改造思路改造这个项目我一般按“数据层 → 控件层 → 分发层”倒着推先想清楚要产出什么形态的数据再决定控件长什么样最后才考虑怎么打包。顺序反过来做往往写到一半发现数据结构对不上控件得推倒重来。最省力的切入点是“包装现成算法”。比如你手里有一个自己实现的聚类方法只要它能接收X矩阵、返回标签数组包成控件的成本很低输入声明为Table在提交阶段取出data.X喂给你的算法把标签写回成DiscreteVariable拼进结果表再send出去。这个过程中不需要碰任何画布代码也不需要理解 Qt 的事件循环。再往上一层是“改造已有控件”。这时候建议先把原控件的源码复制一份到自己的包里改而不是直接改源码树——直接改会让后续升级变成噩梦你改过的地方和上游的变更一定会打架。复制出来之后在新类里换掉name画布会把它当成两个不同的控件可以并排放在画布上对比效果这在调试时特别有用。验证改造是否真的生效我习惯用两条腿走路一条是画布上手工连一条最短链路数据 → 你的控件 → 结果查看肉眼看输出另一条是写个脚本直接调用核心逻辑固定随机种子跑固定数据集把结果和预期值对比。第一条保证交互没问题第二条保证数值没问题。缺了第一条界面上的坑发现不了缺了第二条改个参数导致精度掉点你也察觉不到。回到开头那个压缩包。拿到之后别急着往画布上拖控件先按第 3.2 节的脚本把一条最小流水线跑通确认环境和指标都对得上再去碰界面和控件开发。从那以后我每次拆这类可视化编程项目都强制先跑一遍纯脚本路径再开图形界面——因为脚本报错会告诉你哪一行错了而画布只会告诉你“出错了”。这份资源需要的依赖、控件组织和扩展方式都在里面按上面的顺序走一遍基本上就能从“能打开”走到“能改”。希望帮到你。本文还有配套的精品资源点击获取