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__':
    # 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 --limit 5000

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

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__':
    # 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	调控重要性评分（越高 = 越强）

筛选策略：

• 在推断时使用 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。

# Standalone: infer co-expression modules before pySCENIC cisTarget pruning
from arboreto.algo import grnboost2

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

# Downstream: pySCENIC ctx pruning, regulon definition, AUCell (see pySCENIC docs)

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

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)

    # Consensus: links recurring across runs (example: mean importance per TF-target pair)
    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 起支持

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组/注释版本以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 确认输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会改变结果的值，都应询问而不是猜测。
3. 先运行小规模版本。 先在小型子集上运行流水线（一个样本、一条染色体、几千个细胞）。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 在解读结果之前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并协调统一（liftover、ID 映射）后再继续。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

完整性规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 不要对超出统计数据支持范围的生物学意义作出解读；报告多重检验校正。
• 此处与版本相关的细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须事先征求同意。

相关技能

• cellxgene-census：以编程方式查询 CZ CELLxGENE Census，获取带版本信息的公共单细胞和空间转录组数据。
• pydeseq2：使用 PyDESeq2（DESeq2 的 Python 移植版）对 bulk RNA-seq 计数数据进行差异表达分析。
• bulk-rnaseq：端到端 bulk RNA-seq 编排器——将原始 FASTQ 读取数据依次处理为 QC 和修剪（FastQC、fastp/Trim Galore）、比对和定量…