plotly-resampler

<p align="center"> <a href="#readme"> <img alt="Plotly-Resampler标志" src="https://yellow-cdn.veclightyear.com/0a4dffa0/f40cb14e-fcc9-4d10-9aa9-08dd9897d05e.svg" width=65%> </a> </p>

plotly_resampler：通过为Plotly图表添加重采样功能来可视化大型序列数据

plotly-resampler通过改善Plotly可视化大型时间序列数据集的可扩展性。具体来说，我们的库会根据当前图表视图_动态_聚合时间序列数据，确保在用户进行平移或缩放等交互操作时，通过回调机制实现高效且响应迅速的更新。

这一核心聚合功能是通过使用_时间序列数据点选择算法_实现的，plotly-resampler利用了tsdownsample中提供的高度优化的实现。我们默认的数据聚合方法是MinMaxLTTB（选择1000个数据点进行绘图）。要深入了解这种方法，您可以参考算法专用的MinMaxLTTB仓库和相关的研究论文。

在这个Plotly-Resampler演示中，超过1.1亿个数据点被可视化展示！

🛠️ 安装

pip	pip install plotly-resampler

<br> <details><summary><b>👀 plotly-resampler 图表与普通 plotly 图表有什么区别?</b></summary>

plotly-resampler 可以被视为普通 plotly 图表的包装器，它通过根据前端视图动态聚合数据来为折线图添加可视化扩展性。因此，plotly-resampler 为普通 plotly 图表增加了动态聚合功能。

❗ 重要提示:

• show 始终生成图表的静态 HTML 视图，禁用动态聚合。
• 要实现动态聚合:
  • 使用 FigureResampler 的 show_dash 来启动 Dash 应用程序，通过回调实现动态聚合。<br>(或通过 IPython.display 在单元格中输出对象)，这也会启动一个 dash 网页应用
  • 对于 FigureWidgetResampler，你需要对对象使用 IPython.display，它通过运行的 IPython 内核使用小部件事件来实现动态聚合。

plotly-resampler 图表相对于原生 plotly 的其他变化:

• 在折线图区域内双击不会重置坐标轴，因为它会触发"自动缩放"事件。我们决定将自动缩放事件实现为更新 y 轴范围，以显示 x 轴范围内的所有数据。
  • 注意: 原生 Plotly 图表的自动缩放会导致重置坐标轴的行为，我们认为这不太合理。因此，我们在 plotly-resampler 中重写了这一行为。

</details><br>

📋 特性

• 使用方便:
  • 只需添加以下任一项
    • 在笔记本中使用 register_plotly_resampler 函数，并设置最适合的 mode 参数。
    • 用 FigureResampler 装饰器包装 plotly Figure，并调用 .show_dash()
    • 用 FigureWidgetResampler 装饰器包装 plotly Figure，并在单元格中输出实例
  • 允许使用所有其他 plotly 图表构建的灵活性!
• 环境无关
  • 可在 Jupyter、vscode-notebooks、Pycharm-notebooks、Google Colab、DataSpell 中使用，甚至可作为应用程序(在服务器上)使用
• 各种聚合算法的接口:
  • 能够开发或选择你偏好的序列聚合方法

🚀 使用方法

为你的 plotly Figure 添加动态聚合 (展开适合你的使用场景)

• 🤖 <b>自动</b> (最少代码开销):

  <details><summary>使用 <code>register_plotly_resampler</code> 函数</summary> <br>

  1. 导入并调用 register_plotly_resampler 方法

  2. 使用你常规的图表构建代码

  • 代码示例:

    import plotly.graph_objects as go; import numpy as np
    from plotly_resampler import register_plotly_resampler
    
    # 调用注册函数一次，所有 Figure/FigureWidget 都将根据 register_plotly_resampler 的 `mode` 参数进行包装
    register_plotly_resampler(mode='auto')
    
    x = np.arange(1_000_000)
    noisy_sin = (3 + np.sin(x / 200) + np.random.randn(len(x)) / 10) * x / 1_000
    
    
    # 自动模式: 在 IPython 环境中工作时，这将自动成为 FigureWidgetResampler
    # 否则，这将是一个 FigureResampler
    f = go.Figure()
    f.add_trace({"y": noisy_sin + 2, "name": "yp2"})
    f

  注意: 这会用 FigureResampler | FigureWidgetResampler 包装所有 plotly 图形对象。 因此，这也可以用于 plotly.express 接口。 🎉

  </details>

• 👷 <b>手动方式</b>（更高的数据聚合可配置性，更多加速可能性）：

  • 在<b><i>Jupyter</i></b>环境中，无需创建<i>网络应用</i>
    1. 用FigureWidgetResampler包装plotly Figure
    2. 在一个单元格中输出FigureWidgetResampler实例

    import plotly.graph_objects as go; import numpy as np
    from plotly_resampler import FigureResampler, FigureWidgetResampler
    
    x = np.arange(1_000_000)
    noisy_sin = (3 + np.sin(x / 200) + np.random.randn(len(x)) / 10) * x / 1_000
    
    # 选项1 - FigureWidgetResampler：通过`FigureWidget.layout.on_change`实现动态聚合
    fig = FigureWidgetResampler(go.Figure())
    fig.add_trace(go.Scattergl(name='noisy sine', showlegend=True), hf_x=x, hf_y=noisy_sin)
    
    fig

  • 使用<b><i>网络应用</i></b>和<b><a href="https://github.com/plotly/dash">dash</a></b>回调
    1. 用FigureResampler包装plotly Figure
    2. 在Figure上调用.show_dash()

    import plotly.graph_objects as go; import numpy as np
    from plotly_resampler import FigureResampler, FigureWidgetResampler
    
    x = np.arange(1_000_000)
    noisy_sin = (3 + np.sin(x / 200) + np.random.randn(len(x)) / 10) * x / 1_000
    
    # 选项2 - FigureResampler：通过Dash网络应用实现动态聚合
    fig = FigureResampler(go.Figure())
    fig.add_trace(go.Scattergl(name='noisy sine', showlegend=True), hf_x=x, hf_y=noisy_sin)
    
    fig.show_dash(mode='inline')

  提示 💡： 为了显著加快Figure的初始加载速度，我们建议包装plotly Figure的构造函数，并将trace数据作为hf_x和hf_y添加

<br>

注意： 任何plotly Figure都可以用FigureResampler和FigureWidgetResampler包装！🎉 但只有go.Scatter/go.Scattergl 轨迹会被重采样。

💭 重要考虑事项和提示

• 在服务器上运行代码时，你应该将FigureResampler.show_dash()方法的端口转发到本地机器。<br> 注意，你可以使用FigureWidgetResampler包装器为plotly figures添加动态聚合功能，而无需转发端口！
• FigureWidgetResampler使用IPython主线程进行数据聚合功能，所以当主线程被占用时，无法执行重采样逻辑。例如，如果你在笔记本中执行长时间计算，内核将在这些计算期间被占用，只有在完成计算后才会执行这些计算期间发生的重采样操作。
• 一般来说，使用下采样时应该注意可能的混叠效应。 图例中的<b style="color:orange">[R]</b>表示相应的轨迹是否正在被重采样（因此可能被扭曲）。此外，~<范围>后缀表示平均聚合bin大小（以序列索引为单位）。
• plotly的自动缩放事件（由自动缩放按钮或图表内双击触发）不会重置坐标轴，而是自动缩放plotly-resampler图表的当前视图。这个设计选择是因为开发者认为用双击支持这种行为比默认的坐标轴重置行为更直观。当然，可以使用reset_axis按钮重置图表坐标轴。如果你想就此提供反馈并与开发者进一步讨论，请查看issue #49。

📜 引用和论文

关于plotly-resampler工具包本身的论文（预印本）：https://arxiv.org/abs/2206.08703

@inproceedings{van2022plotly,
  title={Plotly-resampler: 大型时间序列的有效可视化分析},
  author={Van Der Donckt, Jonas 和 Van Der Donckt, Jeroen 和 Deprost, Emiel 和 Van Hoecke, Sofie},
  booktitle={2022年IEEE可视化和可视分析会议（VIS）},
  pages={21--25},
  year={2022},
  organization={IEEE}
}

相关论文:

• 时间序列数据点选择算法的视觉代表性（预印本）：https://arxiv.org/abs/2304.00900 <br> 代码：https://github.com/predict-idlab/ts-datapoint-selection-vis
• MinMaxLTTB - 一种高效的数据点选择算法（预印本）：https://arxiv.org/abs/2305.00332 <br> 代码：https://github.com/predict-idlab/MinMaxLTTB

<br>

---

<p align="center"> 👤 <i>Jonas Van Der Donckt, Jeroen Van Der Donckt, Emiel Deprost</i> </p>