NeuroKit项目中ts2vg依赖与NumPy 2.0兼容性问题解析

在NeuroKit项目的开发过程中，我们遇到了一个与第三方库ts2vg相关的依赖兼容性问题。这个问题主要影响到了ECG信号处理中基于visibility graph方法的峰值检测功能（ecg_findpeaks）。

问题背景

ts2vg是一个用于构建时间序列可见性图（Visibility Graph）的Python库，在NeuroKit中被用于实现_ecg_findpeaks_visibilitygraph方法。该库在1.2.4版本之前发布的二进制wheel文件存在一个关键限制：它要求NumPy版本必须低于2.0。

问题表现

当用户环境中的NumPy自动升级到2.0或更高版本时，尝试使用visibility graph方法进行ECG峰值检测会导致兼容性错误。这个问题在持续集成（CI）环境中尤为明显，因为CI环境通常会安装最新的依赖版本。

技术分析

问题的根源在于ts2vg的二进制分发包（wheel）是在NumPy 1.x环境下构建的。当NumPy 2.0引入了一些不兼容的API变更后，这些预编译的二进制文件就无法正常工作。这种现象在Python生态系统中并不罕见，特别是在涉及科学计算和数值处理的库中。

解决方案

针对这个问题，开发团队考虑了多种解决方案：

1. 版本锁定：将NumPy版本锁定在1.x范围内
2. 源码安装：在CI环境中强制从源码安装ts2vg
3. 上游修复：推动ts2vg维护者发布兼容NumPy 2.0的新版本

最终，最优雅的解决方案是第三种。ts2vg的维护者迅速响应，于近期发布了1.2.4版本，该版本完全兼容NumPy 2.0，从根本上解决了兼容性问题。

经验总结

这个案例给我们几个重要启示：

1. 依赖管理的重要性：对于科学计算项目，需要特别注意数值计算库的版本兼容性
2. 二进制分发的局限性：预编译的wheel文件虽然提高了安装效率，但也可能带来兼容性问题
3. 社区协作的价值：积极与上游维护者沟通往往能获得最根本的解决方案

对于NeuroKit用户来说，现在只需确保使用ts2vg 1.2.4或更高版本，就可以无障碍地在NumPy 2.0环境下使用所有功能。