Scanpy项目中regress_out函数与完美分离问题的兼容性更新

背景介绍

Scanpy是一个广泛使用的单细胞RNA测序数据分析工具包，其中的regress_out函数用于对表达数据进行回归校正。该函数底层依赖于statsmodels库的广义线性模型(GLM)实现。近期statsmodels 0.14版本的更新引入了一个重要的行为变更，影响了Scanpy中回归校正的处理方式。

问题本质

在统计学建模中，"完美分离"(Perfect Separation)是指预测变量能够完美区分响应变量的情况。例如，当某个协变量完全决定了基因表达是否为零时，就会出现这种情况。在statsmodels 0.14版本之前，遇到完美分离时会直接抛出错误；而新版本中改为发出警告(Warning)。

Scanpy现有的错误捕获机制仅处理了旧版本中的错误类型，未能适配新版本的警告机制。这导致用户在运行regress_out时可能会看到大量关于完美分离的警告信息，即使实际上并不存在真正的完美分离问题。

技术影响

这种版本不兼容性带来的主要影响包括：

1. 用户体验下降：用户控制台被大量警告信息淹没
2. 潜在问题掩盖：真正的完美分离问题可能被忽视
3. 分析流程干扰：在自动化流程中，警告信息可能干扰日志解析

解决方案

针对这一问题，Scanpy需要更新其错误/警告处理机制，主要修改包括：

1. 同时捕获PerfectSeparationError和PerfectSeparationWarning
2. 保持原有处理逻辑的一致性
3. 确保向后兼容性，不影响使用旧版statsmodels的用户

代码示例

以下代码展示了典型的问题场景：

import anndata as ad
import scanpy as sc
import numpy as np
import pandas as pd

# 创建测试数据
adata = ad.AnnData(
    np.array([[0,0,1,1]]).T, 
    obs=pd.DataFrame({"a":[0,0,1,1]})
)

# 触发完美分离警告
sc.pp.regress_out(adata, "a")

版本兼容性

该问题主要影响以下版本组合：

• Scanpy 1.9.6
• statsmodels ≥ 0.14.0

最佳实践建议

对于单细胞数据分析人员，建议：

1. 检查当前环境中的statsmodels版本
2. 关注回归校正后的结果合理性
3. 对于确实存在的完美分离问题，考虑：
   • 检查协变量选择是否合理
   • 评估是否需要合并某些类别
   • 考虑使用其他校正方法

总结

Scanpy与依赖库的版本兼容性是生物信息学工具链中需要持续关注的问题。本次更新确保了regress_out函数在不同statsmodels版本下的稳定行为，维护了分析流程的可靠性。用户应及时更新Scanpy以获取这些改进。