arboreto

Arboreto

概述

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

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

快速开始

安装 arboreto：

uv pip install 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)

    # Filter high-confidence links
    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__':
    # 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	调控重要性评分（越高表示调控越强）

筛选策略：

• 每个目标基因取排名靠前的 N 个连接
• 重要性阈值（例如 > 0.5）
• 统计显著性检验（置换检验）

与 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)

使用多个随机种子进行稳健性分析：

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)

    # Combine networks and filter consensus links
    consensus = analyze_consensus(networks)

故障排除

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

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

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

结果为空：检查数据格式（基因作为列），确认 TF 名称与基因名称匹配