ipecharts

Apache Echarts Jupyter Widget

ipecharts 将基于 Apache ECharts 图表库的交互式小部件引入到Jupyter生态系统。通过使用Jupyter Widget协议，ipecharts 与Jupyter生态系统中的其他小部件库和工具完全兼容。

https://github.com/trungleduc/ipecharts/assets/4451292/c6e73b4d-61ef-4098-a274-92233d0801b0

[!注意]
pyecharts 也支持在笔记本中使用Echarts，但它们没有使用像 ipecharts 这样的Jupyter Widget。在这个库中，HTML代码被注入到笔记本中以渲染图表。

在线尝试！

您可以通过点击此徽章在线尝试： 点击这里

文档

您可以通过以下链接阅读文档： https://ipecharts.readthedocs.io/

安装

要安装扩展，执行

pip install ipecharts

或者使用conda

conda install -c conda-forge  ipecharts

使用方法

ipecharts 小部件会自动从 ECharts 5.5.0 生成。它提供两个高级小部件以在笔记本中创建图表： EChartsRawWidget 和 EChartsWidget。

使用 EChartsRawWidget 创建图表

EChartsRawWidget 是一个用于渲染 ECharts 选项字典的简单小部件。它与 ECharts 的 JavaScript 版本完全兼容。以下是将以下示例转换为使用 EChartsRawWidget 的示例

import * as echarts from 'echarts';

var chartDom = document.getElementById('main');
var myChart = echarts.init(chartDom);
var option;

option = {
  xAxis: {
    type: 'category',
    boundaryGap: false,
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {
    type: 'value'
  },
  series: [
    {
      data: [820, 932, 901, 934, 1290, 1330, 1320],
      type: 'line',
      areaStyle: {}
    }
  ]
};

option && myChart.setOption(option);

的示例

from ipecharts import EChartsRawWidget

option = {
  'xAxis': {
    'type': 'category',
    'boundaryGap': False,
    'data': ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  'yAxis': {
    'type': 'value'
  },
  'series': [
    {
      'data': [820, 932, 901, 934, 1290, 1330, 1320],
      'type': 'line',
      'areaStyle': {}
    }
  ]
}

EChartsRawWidget(option=option)

使用 EChartsWidget 创建图表

虽然原始小部件可以正确渲染图表，但它缺少 Jupyter 小部件的交互性。 ipecharts 提供了 EChartsWidget 和配置类，以几乎涵盖 ECharts 所有可用选项，以解决这个问题。

以下是使用 EChartsWidget 的上述图表的等效示例

from ipecharts import EChartsWidget
from ipecharts.option import Option, XAxis, YAxis
from ipecharts.option.series import Line

line = Line(data=[820, 932, 901, 934, 1290, 1330, 1320], areaStyle={})
option = Option(
    xAxis=XAxis(
        type="category",
        boundaryGap=False,
        data=["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
    ),
    yAxis=YAxis(type="value"),
    series=[line],
)
EChartsWidget(option=option)

虽然看起来更冗长，但优点是反应性。我们可以更新线数据，并自动更新图表。

使用 traitlets 配置 EChartsWidget

每个 ECharts 选项字典中的键都有一个同名的配置类。这些类包含与相应 ECharts 选项同名的属性。对这些属性的任何更改都将传播到顶级小部件，并自动更新图表。

例如，您可以比较 ECharts 的散点选项 https://echarts.org.cn/en/option.html#series-scatter.type 以及 ipecharts 文档中的等效 Scatter 类 https://ipecharts.readthedocs.io/en/latest/api/ipecharts.option.seriesitems.scatter。Python 类自动从 ECharts 选项生成。

通过使用 Traitlets 配置您的部件，您可以使用 EChartsWidget 与 Jupyter 生态系统中的其他部件一起使用。以下是一个使用 ipywidgets Button 控制图表的示例

from ipecharts.option import Option, XAxis, YAxis
from ipecharts.option.series import Line
from ipywidgets.widgets import Button

line = Line(smooth=True, areaStyle={}, data=numpy.random.rand(10).tolist())
option = Option(
    xAxis=XAxis(type="category"),
    yAxis=YAxis(type="value"),
    series=[line],
)
chart = EChartsWidget(option=option)

button = Button(description="Generate data")
def on_button_clicked(b):
    data = numpy.random.rand(10).tolist()
    line.data = data

button.on_click(on_button_clicked)

display(button, chart)

自定义图表容器样式

Both EChartsWidget 和 EChartsRawWidget 类都允许您通过设置样式属性来自定义图表容器的样式。样式属性接受一个字典，其中键是 CSS 属性名称（以驼峰式或破折号分隔），值是相应的 CSS 值。

示例：'backgroundColor': '#f0f0f0' 或 'background-color': '#f0f0f0'

from ipecharts import EChartsWidget
from ipecharts.option import Option, XAxis, YAxis
from ipecharts.option.series import Line

# Define the data for the line series
line = Line(
    data=[820, 932, 901, 934, 1290, 1330, 1320],
    areaStyle={}
)

# Create the option object with xAxis, yAxis, and series
option = Option(
    xAxis=XAxis(
        type="category",
        boundaryGap=False,
        data=["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
    ),
    yAxis=YAxis(type="value"),
    series=[line]
)

# Define the style for the widget
style = {
    'width': '450px',
    'height': '300px',
    'border': '5px solid #ccc'
}

# Create the EChartsWidget with the option and style
chart = EChartsWidget(option=option, style=style)

# Display the chart
chart

创建和显示小部件后，您可以通过修改样式属性来更新其样式。

# Update the style of the chart
chart.style = {
    'width': '800px',
    'height': '600px',
    'border': '2px solid #000'
}

# The widget will automatically update to reflect the new styles.

https://github.com/user-attachments/assets/e4245101-8dff-40a9-a4d4-1f75a06b88c4

贡献

开发安装

注意：您将需要 markdownify、autodoc-traits、sphinx 来生成代码

jlpm 命令是 JupyterLab 的 yarn 固定版本，它与 JupyterLab 一起安装。您可以使用 yarn 或 npm 替代下面的 jlpm。

# Clone the repo to your local environment
# Change directory to the ipecharts directory
# Install package in development mode
pip install -e "."
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Rebuild extension Typescript source after making changes
jlpm build

您可以在不同的终端中同时监视源目录并运行 JupyterLab，以监视扩展源的变化，并自动重新构建扩展。

# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm watch
# Run JupyterLab in another terminal
jupyter lab

当监视命令运行时，每次保存的更改都将立即在本地构建并可用于您的运行 JupyterLab。刷新 JupyterLab 以在浏览器中加载更改（您可能需要等待几秒钟以重新构建扩展）。

默认情况下，jlpm build 命令为此扩展生成源映射，以便更容易使用浏览器开发工具进行调试。要为 JupyterLab 核心扩展也生成源映射，您可以运行以下命令

jupyter lab build --minimize=False

开发卸载

pip uninstall ipecharts

在开发模式下，您还需要删除由 jupyter labextension develop 命令创建的符号链接。要找到其位置，您可以运行 jupyter labextension list 以确定 labextensions 文件夹的位置。然后您可以从该文件夹中删除名为 ipecharts 的符号链接。

打包扩展

见 RELEASE