Arboreto

Arboreto

概述

Arboreto 是来自 Aerts Lab 的 Python 库，用于从基因表达数据推断基因调控网络（GRN）。它使用 Dask 并行化树形集成回归算法（GRNBoost2、GENIE3），可在本地核心或远程集群上运行。

核心能力：根据跨观测（细胞、样本、条件）的表达模式，识别哪些转录因子（TF）调控哪些靶基因。

上游：PyPI 0.1.6 (2021-02-09, 最新)。文档：arboreto.readthedocs.io。主要下游使用者：pySCENIC。

快速开始

安装 arboreto：

uv pip install arboreto

基本 GRN 推断：

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)

    # 保存结果（TF、target、importance）
    network.to_csv('network.tsv', sep='\t', index=False, header=False)

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

核心能力

1. 基本 GRN 推断

用于标准 GRN 推断工作流程，包括：

• 输入数据准备（Pandas DataFrame 或 NumPy 数组）
• 使用 GRNBoost2 或 GENIE3 运行推断
• 按转录因子过滤
• 输出格式和解释

参见：references/basic_inference.md

使用现成脚本：scripts/basic_grn_inference.py 用于标准推断任务：

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

2. 算法选择

Arboreto 提供两种算法：

GRNBoost2（推荐）：

• 基于快速梯度提升的推断
• 针对大型数据集（10k+ 观测）优化
• 大多数分析的默认选择

GENIE3：

• 基于随机森林的推断
• 原始多元回归方法
• 用于比较或验证

快速比较：

from arboreto.algo import grnboost2, genie3

# 快速，推荐
network_grnboost = grnboost2(expression_data=matrix)

# 经典算法
network_genie3 = genie3(expression_data=matrix)

有关详细算法比较、参数和选择指导：references/algorithms.md

3. 分布式计算

将推断从本地多核扩展到集群环境：

本地（默认） - 自动使用所有可用核心：

network = grnboost2(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)

有关集群设置、性能优化和大规模工作流程：references/distributed_computing.md

安装

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。

常见用例

单细胞 RNA-seq 分析

import pandas as pd
from arboreto.algo import grnboost2

if __name__ == '__main__':
    # 加载单细胞表达矩阵（细胞 x 基因）
    sc_data = pd.read_csv('scrna_counts.tsv', sep='\t')

    # 推断细胞类型特异性调控网络
    network = grnboost2(expression_data=sc_data, seed=42)

    # 过滤高置信度链接
    high_confidence = network[network['importance'] > 0.5]
    high_confidence.to_csv('grn_high_confidence.tsv', sep='\t', index=False)

带 TF 过滤的 Bulk RNA-seq

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

if __name__ == '__main__':
    # 加载数据
    expression_data = pd.read_csv('rnaseq_tpm.tsv', sep='\t')
    tf_names = load_tf_names('human_tfs.txt')

    # 使用 TF 限制进行推断
    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__':
    # 为不同条件推断网络
    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)

输出解释

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。

# 独立版：在 pySCENIC cisTarget 修剪之前推断共表达模块
from arboreto.algo import grnboost2

network = grnboost2(expression_data=expression_df, tf_names=tf_list, limit=5000)

# 下游：pySCENIC ctx 修剪、调控子定义、AUCell（参见 pySCENIC 文档）

将 AnnData 直接转换为 arboreto 使用的 DataFrame：

expression_df = adata.to_df()  # cells x genes

可重现性

始终设置种子以获得可重现的结果：

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

运行多个种子进行稳健性分析：

from distributed import LocalCluster, Client

if __name__ == '__main__':
    client = Client(LocalCluster())

    seeds = [42, 123, 777]
    networks = []

    for seed in seeds:
        net = grnboost2(expression_data=matrix, client_or_address=client, seed=seed)
        networks.append(net)

    # 共识：跨运行重复的链接（示例：每个 TF-靶基因对的平均重要性）
    import pandas as pd
    combined = pd.concat(networks)
    consensus = (
        combined.groupby(['TF', 'target'], as_index=False)['importance']
        .mean()
        .query('importance > 0.5')
    )

故障排除

内存错误：通过过滤低方差基因减少数据集大小，或使用分布式计算

性能缓慢：使用 GRNBoost2 代替 GENIE3，启用分布式客户端，过滤 TF 列表

Dask 错误：确保脚本中存在 if __name__ == '__main__': 保护（在具有基于 spawn 的多处理的 Windows/macOS 上需要）

空结果：检查数据格式（基因作为列），验证 TF 名称与表达矩阵中的列名匹配

稀疏数据：使用 scipy.sparse.csc_matrix 并传递匹配的 gene_names；自 arboreto 0.1.6 / pySCENIC 0.11 起支持