PyGWalker 快速上手指南在 Jupyter Notebook 中用拖拽式交互 UI 完成探索性数据分析【免费下载链接】pygwalkerPyGWalker: Turn your dataframe into an interactive UI for visual analysis项目地址: https://gitcode.com/GitHub_Trending/py/pygwalkerPyGWalker 是一个将 pandas / polars DataFrame 转换为 Tableau 风格交互式可视化界面的 Python 库让你在 Jupyter Notebook 中通过简单的拖拽操作完成数据探索、清洗与可视化。本文基于仓库中的官方文档 docs/README.fr.md法语版与 README.md并结合仓库源码完整讲解安装配置、pyg.walk()核心参数、计算引擎选型、隐私策略命令与图表导出 API读完即可在本地或云端 Notebook 中直接上手。PyGWalker 是什么Py 与 Graphic Walker 的结合PyGWalker 读作 “Pig Walker”其名称是 Python binding ofGraphicWalker 的缩写。它将 Jupyter Notebook以及其它基于 Jupyter 的笔记本环境与 Graphic Walker——一款开源的 Tableau 替代方案——集成在一起让数据科学家通过简单的拖拽操作即可分析数据、观察数据模式无需编写绘图代码。从当前仓库源码看其顶层 API 均定义在 pygwalker/api/adapter.py 中walk、render、table三个入口会根据运行环境自动分流到 Jupyter 通道pygwalker/api/jupyter.py或 Web 服务器通道pygwalker/api/webserver.py而 pygwalker/init.py 对外导出walk、render、table、to_html、FieldSpec、GlobalVarManager、component、Walker与spec模块。仓库当前版本为0.6.0rc0见 pygwalker/init.py。安装 PyGWalker在命令行中使用 pip 或 conda 安装pip 安装pip install pygwalker若想尝鲜体验最新功能可以升级到最新发布版甚至获取包含最新特性与 bug 修复的预发布版本pip install pygwalker --upgrade pip install pygwalker --upgrade --preConda-forge 安装conda install -c conda-forge pygwalker或使用 mambamamba install -c conda-forge pygwalker说明PyGWalker 0.6 系列经过验证支持的 Python 版本为 3.10、3.11、3.12 与 3.13前端与发布工作流使用 Node.js 22.x 构建见 docs/RELEASE_0_6.md。在 Jupyter Notebook 中使用 PyGWalker快速开始在 Jupyter Notebook 中导入 pygwalker 与 pandasimport pandas as pd import pygwalker as pygPyGWalker 不会打断你现有的工作流。例如用如下方式加载 DataFrame 后即可唤起 Graphic Walker 界面df pd.read_csv(./bike_sharing_dc.csv) walker pyg.walk(df)这就完成了。现在你拥有一个 Tableau 风格的交互式 UI可以通过拖拽变量完成数据分析和可视化。最佳实践状态持久化与大数据集计算df pd.read_csv(./bike_sharing_dc.csv) walker pyg.walk( df, spec./chart_meta_0.json, # 该 JSON 文件用于保存图表状态完成一个图表后需点击界面中的保存按钮未来会支持 autosave kernel_computationTrue, # 设为 True 时pygwalker 使用 DuckDB 作为计算引擎可探索更大的数据集100GB )在 0.6 版本线上官方更推荐用spec_path与新的computation参数表达同样的意图见 docs/RELEASE_0_6.mddf pd.read_csv(./bike_sharing_dc.csv) walker pyg.walk( df, spec_path./chart_meta_0.json, # 本地文件用于加载与保存图表状态 computationkernel, # 在 Python 内核中使用 DuckDB以支撑更大的数据集 )离线与在线示例离线 Notebook 代码示例可参考 pygwalker-offline-example 仓库以及 HTML 版 Notebook 预览在线示例包括 Kaggle 上的 Airbnb EDA 演示与 Google Colab 在线运行环境。核心参数详解spec 与 computation图表配置参数spec与spec_path根据 README.md 中的说明图表配置相关参数包括spec_path本地文件路径用于保存/加载图表配置spec图表配置对象可以是 JSON 字符串、配置 ID 或远程 URL。在 pygwalker/utils/spec.py 的resolve_spec_input()中可以看到二者的解析规则当spec_path为None时保留spec的旧行为若spec是路径类对象则取其文件路径当同时传入非空的spec与spec_path时会抛出ValueError要求只传其一并建议本地配置文件统一走spec_path。spec参数的输入类型判定在 pygwalker/spec.py 的migrate()中也有体现既可以是 dict / list 对象也可以是合法 JSON 字符串或已存在的本地文件路径。计算引擎参数computation与遗留参数PyGWalker 0.6 引入了新的统一计算模型computation可选值auto默认自动选择计算后端browser仅前端计算kernel本地基于 DuckDB 的 Python 内核计算cloudKanaries 云端计算。同时保留的遗留布尔参数及废弃时间线如下均计划在 PyGWalker 0.7.0 中移除kernel_computation遗留布尔值表示使用 DuckDB 作为计算引擎建议改用computationkernel或computationbrowsercloud_computation遗留布尔值表示使用 Kanaries 云端计算建议改用computationclouduse_kernel_calc内核计算的废弃别名建议改用computationkernel或computationbrowser。源码层面的解析逻辑位于 pygwalker/utils/computation.py 的resolve_computation_mode()若显式传入非auto的computation值同时又启用了上述遗留参数会直接抛出ValueError要求二选一browser映射为(False, False)kernel映射为(True, False)cloud映射为(False, True)。值得注意的推断逻辑是当数据集是数据库连接器Connector或str且未显式指定计算模式时会强制启用内核计算force_kernel_for_connectorsTrue保证连接器场景下的查询可执行。pyg.walk()完整参数参考根据 README.md 的 API 参考表与 pygwalker/api/adapter.py 中的函数签名pyg.walk()主要参数如下参数类型默认值说明datasetUnion[DataFrame, pyarrow.Table, Connector, str, Walker]-要探索的 DataFrame、pyarrow 表、数据库连接器、SQL/数据源字符串或可复用的 Walker 对象gidUnion[int, str]NoneGraphicWalker 容器 div 的 ID格式为gwalker-{gid}envLiteral[JupyterAnywidget, Jupyter, JupyterWidget]JupyterAnywidgetNotebook 渲染环境推荐使用JupyterAnywidget或省略Jupyter与JupyterWidget是废弃别名计划在 0.7.0 移除field_specsOptional[List[FieldSpec]]None字段规格未指定时从dataset自动推断theme_keyLiteral[vega, g2, streamlit]g2Graphic Walker 主题类型appearanceLiteral[media, light, dark]media主题外观media跟随操作系统偏好specstr图表配置数据可为配置 ID、JSON 字符串、本地文件路径或远程文件 URLspec_pathOptional[str]None本地图表配置文件路径优先于通过spec传入本地路径computationOptional[Literal[auto, browser, kernel, cloud]]None计算后端省略时为自动行为也可显式指定use_kernel_calcOptional[bool]None已废弃计划 0.7.0 移除改用computationkernel_computationOptional[bool]None遗留布尔值本地 DuckDB 内核计算计划 0.7.0 移除cloud_computationboolFalse遗留布尔值Kanaries 云端计算计划 0.7.0 移除show_cloud_toolboolTrue是否在可用时显示 Kanaries 云工具kanaries_api_keystr云功能使用的 Kanaries API Keydefault_tabLiteral[data, vis]visUI 打开时默认显示的标签页可复用 Walker 对象与静态导出对于需要在多个环境中渲染同一份数据的场景0.6 版本推荐优先使用可复用的Walker对象并自行选择渲染方式见 pygwalker/api/walker.pywalker pyg.Walker(df, spec_path./chart_meta_0.json, computationbrowser) walker.show() # 自动检测 Notebook 或脚本模式 html walker.to_html() html pyg.to_html(walker)从源码看Walker.show()会解析env参数并路由到jupyter-anywidget默认、首选渲染通道、jupyter-convert、jupyter-preview或webserver模式Walker.to_html()与to_html_without_iframe()会先检查kernel_computation与cloud_computation若处于实时计算模式则抛出ValueError因为静态 HTML 只支持浏览器计算。Walker.to_streamlit()则会把构造参数透传给StreamlitRenderer实现同一 Walker 的多端复用。在 UI 中完成探索后还可以把当前图表状态导出为可复现的 Python 代码实现于 pygwalker/api/pygwalker.py 的PygWalker.to_code()它会序列化当前 spec 并生成pyg.walk(df, spec...)代码code walker.to_code(dataset_namedf) print(code)如果你持有旧版本保存的 spec可以在提交前将其迁移到当前 schemamigrated_spec pyg.spec.migrate(open(./old_chart_meta.json).read())pyg.spec.migrate()的实现位于 pygwalker/spec.py它支持 dict / list / JSON 字符串 / 本地文件路径四种输入迁移后会自动补充version、chart_map与workflow_list字段。图表的程序化导出在 UI 中保存图表后可以直接从 Python 中获取图表图片walker pyg.walk(df, spec_path./chart_meta_0.json) # 在 UI 中编辑图表并点击保存按钮 walker.save_chart_to_file(Chart 1, chart1.svg, save_typesvg) png_bytes walker.export_chart_png(Chart 1) svg_bytes walker.export_chart_svg(Chart 1)对应的 API 定义在 pygwalker/api/pygwalker.pysave_chart_to_file(chart_name, path, save_type)支持html、png、svg三种格式export_chart_html/export_chart_png/export_chart_svg分别返回 HTML 字符串或 PNG/SVG 字节流chart_list属性可获取已保存图表的名称列表。这些方法最终通过ChartExportManagerpygwalker/services/chart_export.py实现。已测试的运行环境根据 docs/README.fr.md 与 README.md 的环境矩阵Jupyter NotebookGoogle ColabKaggle CodeJupyter Lab法语版标注为“进行中仍有少量 CSS 小问题”Jupyter LiteDatabricks Notebook自0.1.4a0起Visual Studio Code 的 Jupyter 扩展自0.1.4a0起大多数兼容 IPython 内核的 Web 应用自0.1.4a0起Streamlit自0.1.4.9起通过pygwalker.api.streamlit.StreamlitRenderer启用DataCamp Workspace自0.1.4a0起法语版文档还列出 Hex Projects自0.1.4a0起为已验证环境英文版 README 则将其标记为待验证并额外列出 Panel通过 panel-graphic-walker与 marimo自0.4.9.11起。其余环境欢迎通过提交 issue 补充。在 Streamlit 中使用Streamlit 让你无需关心 Web 应用实现细节即可托管 pygwalker 的 Web 版本。参考 examples/streamlit_demo.py 与如下模式from pygwalker.api.streamlit import StreamlitRenderer import pandas as pd import streamlit as st # 调整 Streamlit 页面宽度 st.set_page_config( page_titleUse Pygwalker In Streamlit, layoutwide ) # 添加标题 st.title(Use Pygwalker In Streamlit) # 建议缓存 renderer避免内存爆炸 st.cache_resource def get_pyg_renderer() - StreamlitRenderer: df pd.read_csv(./bike_sharing_dc.csv) # 若想使用保存图表配置的功能设置 spec_io_moderw return StreamlitRenderer(df, spec_path./gw_config.json, spec_io_moderw) renderer get_pyg_renderer() renderer.explorer()若已创建可复用的WalkerStreamlit 可以直接渲染它import pygwalker as pyg from pygwalker.api.streamlit import StreamlitRenderer walker pyg.Walker(df, spec_path./gw_config.json, computationkernel) renderer StreamlitRenderer(walker) renderer.explorer()隐私配置与数据安全pygwalker 0.3.10PyGWalker 提供pygwalker config命令行工具来设置隐私策略$ pygwalker config --help usage: pygwalker config [-h] [--set [keyvalue ...]] [--reset [key ...]] [--reset-all] [--list] Modify configuration file. (default: ~/Library/Application Support/pygwalker/config.json) Available configurations: - privacy [offline, update-only, events] (default: update-only). offline: 完全离线不发送任何数据不请求任何 API update-only: 仅检查 pygwalker 是否有新版本可更新 events: 共享 pygwalker 中使用了哪些功能的事件数据仅包含你到达了哪些功能的事件数据用于产品优化。不会发送你分析的数据。 - kanaries_token [your kanaries token] (default: empty string). 你的 kanaries token可以从 kanaries.net 获取。 通过 kanaries token你可以在 pygwalker 中使用 kanaries 服务例如分享图表、分享配置。 options: -h, --help show this help message and exit --set [keyvalue ...] Set configuration. e.g. pygwalker config --set privacyupdate-only --reset [key ...] Reset user configuration and use default values instead. e.g. pygwalker config --reset privacy --reset-all Reset all user configuration and use default values instead. e.g. pygwalker config --reset-all --list List current used configuration.源码层面pygwalker/services/config.py 定义了默认配置{privacy: update-only, kanaries_token: }配置文件存放于用户配置目录appdirs.user_config_dir(pygwalker)下的config.json并提供set_config、reset_config、reset_all_config、get_config等读写函数。要点privacy三种模式offline完全离线不发送任何数据也不请求 APIupdate-only默认仅做版本更新检查events上报功能使用事件绑定安装时生成、基于时间戳的唯一 ID但绝不上报你分析的数据本身。事件上报的边界根据 docs/RELEASE_0_6.md仅在privacy设为events时才会发送事件遥测前端 Segment 追踪器也只在该设置下开启默认update-only模式不发送事件。offline 模式的联动在 pygwalker/api/pygwalker.py 的PygWalker.__init__中当GlobalVarManager.privacy offline时会强制关闭 Kanaries 云工具self.show_cloud_tool False从 UI 层保证完全离线。kanaries_token用于启用分享图表、分享配置等 Kanaries 云服务PygWalker构造时若未显式传入kanaries_api_key会回退到全局配置中的 token。许可与资源本项目采用 Apache License 2.0 许可。相关学术论文PyGWalker: On-the-fly Assistant for Exploratory Visual Data AnalysisarXiv:2406.11637。可参考仓库内的 docs/ARCHITECTURE.mdPython 与前端两半如何构建与通信、docs/DEVELOPMENT.md热重载开发工作流、docs/CONTRIBUTING.md验证命令、CI 与打包进行本地开发与贡献R 语言用户可关注 GWalkR偏好免代码离线桌面应用的用户可关注 PyGWalker Desktop。完整的行为变化、废弃时间线与兼容策略详见 docs/RELEASE_0_6.md。总结从pip install pygwalker到pyg.walk(df)再到spec_path状态持久化与computationkernel大计算引擎切换PyGWalker 将 Jupyter 中的探索性数据分析体验提升为类 Tableau 的拖拽交互。0.6 版本进一步引入了可复用的Walker对象、统一的computation计算模型、静态 HTML 导出与图表程序化导出 API同时通过pygwalker config将隐私控制权完整交还用户。无论是本地 Notebook、Kaggle/Colab 云端环境还是 Streamlit Web 应用都可以基于上述模式快速搭建可视化分析工作流。【免费下载链接】pygwalkerPyGWalker: Turn your dataframe into an interactive UI for visual analysis项目地址: https://gitcode.com/GitHub_Trending/py/pygwalker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考