用途
Arboreto 是一个 Python 库，用于从基因表达数据推断基因调控网络（GRN）。其核心目标是：根据观测样本（细胞、样本、条件）的表达模式，识别哪些转录因子（TF）调控哪些靶基因。它通过 Dask 并行化基于树的集成回归算法（GRNBoost2、GENIE3），可在本地多核或远程集群上运行。
上游信息：PyPI 0.1.6（2021-02-09，最新版）。文档：arboreto.readthedocs.io。主要下游消费者：pySCENIC。
主要能力
基础 GRN 推断
支持标准 GRN 推断流程，包括输入数据准备（Pandas DataFrame 或 NumPy 数组）、使用 GRNBoost2 或 GENIE3 运行推断、按转录因子过滤、输出格式与解读。
算法选择
Arboreto 提供两种算法：
- GRNBoost2（推荐）：基于快速梯度提升的推断，针对大型数据集（1 万+ 观测）优化，是大多数分析的默认选择。
- GENIE3：基于随机森林的推断，原始多元回归方法，用于对比或验证。
分布式计算
可将推断从本地多核扩展到集群环境：
- 本地（默认）：自动使用所有可用核心。
- 自定义本地客户端：通过 distributed 的 LocalCluster 和 Client 控制资源。
- 集群计算：连接到远程 Dask 调度器。
使用方式
安装
uv pip install arboreto
Conda（Bioconda）：
conda install -c bioconda arboreto
依赖（来自上游 requirements.txt）：dask[complete]、distributed、numpy、pandas、scikit-learn、scipy。
输入格式：pandas DataFrame、稠密 numpy.ndarray 或稀疏 scipy.sparse.csc_matrix（行=观测，列=基因）。对于数组/矩阵输入，需显式传入 gene_names。
基础推断示例
import pandas as pd from arboreto.algo import grnboost2
if name == 'main': expression_matrix = pd.read_csv('expression_data.tsv', sep='\t') network = grnboost2(expression_data=expression_matrix) network.to_csv('network.tsv', sep='\t', index=False, header=False)
关键：始终使用 if name == 'main': 保护，因为 Dask 会生成新进程。
算法对比示例
from arboreto.algo import grnboost2, genie3
network_grnboost = grnboost2(expression_data=matrix) network_genie3 = genie3(expression_data=matrix)
分布式计算示例
自定义本地客户端：
from distributed import LocalCluster, Client
local_cluster = LocalCluster(n_workers=10, memory_limit='8GB') client = Client(local_cluster) network = grnboost2(expression_data=matrix, client_or_address=client) client.close() local_cluster.close()
集群计算：
from distributed import Client
client = Client('tcp://scheduler:8786') network = grnboost2(expression_data=matrix, client_or_address=client)
输出解读
Arboreto 返回包含调控关系的 DataFrame：
- TF：转录因子（调控者）
- target：靶基因
- importance：调控重要性分数（越高越强）
过滤策略：推断时使用 limit=N（全局返回前 N 条关系）；事后重要性阈值（如 > 0.5）；通过 groupby('target') 取每个靶基因的前几条关系；统计显著性检验（置换检验、外部工具）。
与 pySCENIC 集成
Arboreto 为 pySCENIC 的 GRN 推断步骤提供支持。pySCENIC 0.11+ 将稀疏表达矩阵传给 grnboost2 / genie3；pySCENIC 0.12+ 默认使用 arboreto_with_multiprocessing.py（无 Dask）以保持兼容——当需要 Dask 扩展时使用独立 arboreto。
将 AnnData 直接转换为 DataFrame：
expression_df = adata.to_df() # cells x genes
可复现性
始终设置种子以获得可复现结果：
network = grnboost2(expression_data=matrix, seed=777)
可运行多个种子进行稳健性分析，并对多次运行的 TF-target 对取平均重要性作为共识。
适用场景
- 单细胞 RNA-seq 分析：从细胞 x 基因矩阵推断细胞类型特异性调控网络，并过滤高置信度关系。
- Bulk RNA-seq 结合 TF 过滤：使用 load_tf_names 加载转录因子列表，限制推断范围。
- 多条件比较分析：对不同条件分别推断网络。
限制与注意事项
- 内存错误：通过过滤低方差基因缩小数据集，或使用分布式计算。
- 性能缓慢：使用 GRNBoost2 而非 GENIE3，启用分布式客户端，过滤 TF 列表。
- Dask 错误：确保脚本中存在 if name == 'main': 保护（在 Windows/macOS 的 spawn 多进程下必需）。
- 结果为空：检查数据格式（基因作为列），验证 TF 名称与表达矩阵列名匹配。
- 稀疏数据：使用 scipy.sparse.csc_matrix 并传入匹配的 gene_names；自 arboreto 0.1.6 / pySCENIC 0.11 起支持。
- 版本特定细节可能已过时，请对照已安装版本的官方文档确认。
- 不得编造结果、参数、标识符、引用或统计量；不得超出统计支持范围解读生物学意义，需报告多重检验校正。
- 涉及费用、共享 GPU/云配额、个人或患者数据、不可撤销操作时，须先询问。