arboreto

用途

Arboreto 是一个用于从基因表达数据推断基因调控网络（GRN）的计算库，使用可并行化算法，可从单机扩展到多节点集群。其核心能力是根据观测样本（细胞、样本、条件）间的表达模式，识别哪些转录因子（TF）调控哪些靶基因。

适用场景为转录组数据分析，包括 bulk RNA-seq 与单细胞 RNA-seq。

主要能力

基本 GRN 推断：输入数据准备（Pandas DataFrame 或 NumPy 数组），使用 GRNBoost2 或 GENIE3 执行推断，可按转录因子过滤，并输出可解释的结果格式。
算法选择：提供 GRNBoost2 和 GENIE3 两种算法。GRNBoost2 为基于梯度提升的快速推断，针对大型数据集（1 万以上观测）优化，是大多数分析的默认选择；GENIE3 为基于随机森林的推断，采用原始多元回归方法，用于对比或验证。
分布式计算：可从本地多核扩展到集群环境。本地模式默认自动使用全部可用核心；也可自定义本地客户端控制资源；集群模式可连接远程 Dask 调度器。
与 pySCENIC 集成：Arboreto 是 SCENIC 流程中用于单细胞调控网络分析的核心组件，可用于 GRN 推断，后续调控子识别与活性评分参见 pySCENIC 文档。
可复现性：可设置随机种子以获得可复现结果，也可使用多个种子进行稳健性分析并合并网络、筛选共识连接。

使用方式

安装：

uv pip install arboreto

依赖项：scipy、scikit-learn、numpy、pandas、dask、distributed。

基本推断示例：

import pandas as pd
from arboreto.algo import grnboost2

if __name__ == '__main__':
    # Load expression data (genes as columns)
    expression_matrix = pd.read_csv('expression_data.tsv', sep='\t')

    # Infer regulatory network
    network = grnboost2(expression_data=expression_matrix)

    # Save results (TF, target, importance)
    network.to_csv('network.tsv', sep='\t', index=False, header=False)

关键点：始终使用 if __name__ == '__main__': 保护，因为 Dask 会生成新进程。

也可使用现成脚本执行标准推断任务：

python scripts/basic_grn_inference.py expression_data.tsv output_network.tsv --tf-file tfs.txt --seed 777

算法对比：

from arboreto.algo import grnboost2, genie3

# Fast, recommended
network_grnboost = grnboost2(expression_data=matrix)

# Classic algorithm
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()

连接远程 Dask 调度器：

from distributed import Client

client = Client('tcp://scheduler:8786')
network = grnboost2(expression_data=matrix, client_or_address=client)

输出解读

Arboreto 返回包含调控连接的 DataFrame，列为：

列	说明
TF	转录因子（调控者）
target	靶基因
importance	调控重要性得分（越高表示越强）

过滤策略包括：每个靶基因取前 N 个连接、按重要性阈值过滤（例如 > 0.5）、统计显著性检验（置换检验）。

常见用例

单细胞 RNA-seq 分析：加载单细胞表达矩阵（细胞 × 基因），推断细胞类型特异性调控网络，并过滤高置信连接。

import pandas as pd
from arboreto.algo import grnboost2

if __name__ == '__main__':
    # Load single-cell expression matrix (cells x genes)
    sc_data = pd.read_csv('scrna_counts.tsv', sep='\t')

    # Infer cell-type-specific regulatory network
    network = grnboost2(expression_data=sc_data, seed=42)

    # Filter high-confidence links
    high_confidence = network[network['importance'] > 0.5]
    high_confidence.to_csv('grn_high_confidence.tsv', sep='\t', index=False)

Bulk RNA-seq 配合 TF 过滤：

from arboreto.utils import load_tf_names
from arboreto.algo import grnboost2

if __name__ == '__main__':
    # Load data
    expression_data = pd.read_csv('rnaseq_tpm.tsv', sep='\t')
    tf_names = load_tf_names('human_tfs.txt')

    # Infer with TF restriction
    network = grnboost2(
        expression_data=expression_data,
        tf_names=tf_names,
        seed=123
    )

    network.to_csv('tf_target_network.tsv', sep='\t', index=False)

多条件比较分析：

from arboreto.algo import grnboost2

if __name__ == '__main__':
    # Infer networks for different conditions
    conditions = ['control', 'treatment_24h', 'treatment_48h']

    for condition in conditions:
        data = pd.read_csv(f'{condition}_expression.tsv', sep='\t')
        network = grnboost2(expression_data=data, seed=42)
        network.to_csv(f'{condition}_network.tsv', sep='\t', index=False)

可复现性

始终设置随机种子以获得可复现结果：

network = grnboost2(expression_data=matrix, seed=777)

可使用多个种子进行稳健性分析，合并网络并筛选共识连接。

故障排查

内存错误：通过过滤低方差基因减小数据集，或使用分布式计算。
性能缓慢：使用 GRNBoost2 而非 GENIE3，启用分布式客户端，过滤 TF 列表。
Dask 错误：确保脚本中存在 if __name__ == '__main__': 保护。
结果为空：检查数据格式（基因为列），核实 TF 名称与基因名称匹配。

限制

关于算法细节、参数说明与选择指导、集群设置、性能优化及大规模工作流等更多内容，资料中指向相应参考文档；具体收费、价格与平台信息暂未提供。