plotly-resampler

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

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

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

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

🛠️ 安装

📋 特性

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

🚀 使用方法

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

• 🤖 自动 (最少代码开销):

  使用 register_plotly_resampler 函数

  
  

  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 接口。 🎉

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

  • 在Jupyter环境中，无需创建网络应用
    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
    

  • 使用网络应用和dash回调
    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添加

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

💭 重要考虑事项和提示

• 在服务器上运行代码时，你应该将FigureResampler.show_dash()方法的端口转发到本地机器。
  注意，你可以使用FigureWidgetResampler包装器为plotly figures添加动态聚合功能，而无需转发端口！
• FigureWidgetResampler使用IPython主线程进行数据聚合功能，所以当主线程被占用时，无法执行重采样逻辑。例如，如果你在笔记本中执行长时间计算，内核将在这些计算期间被占用，只有在完成计算后才会执行这些计算期间发生的重采样操作。
• 一般来说，使用下采样时应该注意可能的混叠效应。 图例中的[R]表示相应的轨迹是否正在被重采样（因此可能被扭曲）。此外，~<范围>后缀表示平均聚合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
  代码：https://github.com/predict-idlab/ts-datapoint-selection-vis
• MinMaxLTTB - 一种高效的数据点选择算法（预印本）：https://arxiv.org/abs/2305.00332
  代码：https://github.com/predict-idlab/MinMaxLTTB

👤 Jonas Van Der Donckt, Jeroen Van Der Donckt, Emiel Deprost