alterlab-arboreto

Arboreto

概述

Arboreto 是一个计算库，可利用并行化算法从基因表达数据中推断基因调控网络（GRN），并支持从单机扩展到多节点集群。

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

何时使用此技能

当用户希望执行以下操作时，使用此技能：

• 从 bulk 或单细胞表达矩阵推断 TF → 靶基因调控网络。
• 运行 SCENIC / pySCENIC 工作流中的 GRN 推断步骤（步骤 1）。
• 比较 GRNBoost2 与 GENIE3，或基于多个随机种子构建共识网络。
• 在多个核心或 Dask 集群上扩展 GRN 推断。

不适用的场景

场景	改用
比较不同条件之间的差异表达（counts → padj）	alterlab-pydeseq2
单细胞数据集的聚类、UMAP 或 QC	alterlab-scanpy
scRNA-seq 的深度学习潜在空间 / 批次整合	alterlab-scvi-tools
对现有网络进行通用图分析或中心性分析	alterlab-networkx
调整 Dask 集群本身，而非运行 GRN 推断	alterlab-dask

快速开始

安装 arboreto：

uv pip install arboreto

Arboreto 0.1.6 发布于 2021 年，其内部使用 dask.delayed 和 dask.dataframe.from_delayed。这些 API 在当前版本的 dask 中仍然存在，但如果运行在 dask 内部而非 arboreto 内部失败，请在独立环境中将 dask/distributed 固定为相互匹配的版本（pySCENIC 的版本固定配置是很好的参考），而不要修改 arboreto。

基本 GRN 推断：

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 会生成工作进程并重新导入模块，因此未受保护的顶层代码会在每个工作进程中再次运行。

核心能力

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

2. 算法选择

Arboreto 提供两种算法：

GRNBoost2（推荐）：

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

GENIE3：

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

快速比较：

from arboreto.algo import grnboost2, genie3

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

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

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

常见用例

单细胞 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)

    # importance is unbounded (not a 0-1 probability); keep the top links
    # per target rather than applying an absolute threshold.
    top_links = network.sort_values('importance', ascending=False).groupby('target').head(10)
    top_links.to_csv('grn_top_links.tsv', sep='\t', index=False)

使用 TF 筛选的 Bulk RNA-seq

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)

输出解读

Arboreto 返回一个包含调控链接的 DataFrame：

列	描述
TF	转录因子（调控因子）
target	靶基因
importance	调控重要性分数（越高表示调控越强）

筛选策略：importance 是无界的相对分数（基于树模型特征重要性得出），不是概率或相关性——不要使用 > 0.5 这类绝对阈值。建议使用：

• 每个靶基因的前 N 个链接
• 根据本次运行自身分布计算的分位数阈值
• 在 SCENIC 工作流中，保留所有链接，并交由下游 cisTarget 基序剪枝进行筛选

与 pySCENIC 集成

Arboreto 是 SCENIC 流程的核心组件，用于单细胞调控网络分析：

# Step 1: Use arboreto for GRN inference
from arboreto.algo import grnboost2
network = grnboost2(expression_data=sc_data, tf_names=tf_list)

# Step 2: Use pySCENIC for regulon identification and activity scoring
# (See pySCENIC documentation for downstream analysis)

可复现性

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

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

GRNBoost2 具有随机性，因此单个随机种子只能固定一次运行结果，无法证明结果具有稳健性。要构建共识网络，请使用多个随机种子运行，并保留重复出现的链接，同时对其重要性取平均值：

import pandas as pd
from distributed import LocalCluster, Client
from arboreto.algo import grnboost2

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

    seeds = [42, 123, 777]
    networks = [
        grnboost2(expression_data=matrix, client_or_address=client, seed=s)
        for s in seeds
    ]
    client.close()

    # Consensus: keep edges present in every run, average their importance
    combined = pd.concat(networks)
    consensus = (combined.groupby(['TF', 'target'])
                 .agg(importance=('importance', 'mean'), n_runs=('importance', 'size'))
                 .reset_index())
    consensus = consensus[consensus['n_runs'] == len(seeds)]

故障排除

内存错误：通过筛除低方差基因来缩小数据集，或使用分布式计算

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

Dask 错误：确保脚本中包含 if __name__ == '__main__': 保护

结果为空：检查数据格式（基因应为列），并确认 TF 名称与基因名称一致

资源

• references/basic_inference.md — 输入准备、运行推断、输出格式
• references/algorithms.md — GRNBoost2 与 GENIE3 的参数和选择指南
• references/distributed_computing.md — 集群设置和大规模工作流
• scripts/basic_grn_inference.py — 用于标准 GRNBoost2 运行的可执行 CLI 封装脚本

AlterLab Academic Skills 套件的一部分。