名称: arboreto 描述: “使用GRNBoost2/GENIE3算法进行基因调控网络推断。从表达数据推断TF-靶标关系，通过Dask可扩展，适用于scRNA-seq和GRN分析。”

Arboreto - 基因调控网络推断

概述

Arboreto 是一个用于从基因表达数据推断基因调控网络（GRNs）的Python库，使用机器学习算法。它通过Dask实现分布式计算，可从单机扩展到多节点集群。该技能全面支持GRNBoost2（快速梯度提升）和GENIE3（随机森林）算法。

何时使用此技能

此技能应在以下情况下使用：

从表达数据推断基因之间的调控关系
分析单细胞或批量RNA-seq数据以识别转录因子靶标
构建pySCENIC流水线的GRN推断组件
比较GRNBoost2和GENIE3算法性能
设置大规模基因组分析的分布式计算
故障排除arboreto安装或运行时问题

核心能力

1. 基本GRN推断

对于标准基因调控网络推断任务：

关键注意事项：

表达数据格式：行 = 观测值（细胞/样本），列 = 基因
如果数据以基因为行，请先转置：expression_df.T
始终包含seed参数以确保可重复结果
转录因子列表是可选的，但建议用于聚焦分析

典型工作流：

import pandas as pd
from arboreto.algo import grnboost2
from arboreto.utils import load_tf_names

# 加载表达数据（确保正确方向）
expression_data = pd.read_csv('expression_data.tsv', sep='\t', index_col=0)

# 可选：加载TF名称
tf_names = load_tf_names('transcription_factors.txt')

# 运行推断
network = grnboost2(
    expression_data=expression_data,
    tf_names=tf_names,
    seed=42  # 为确保可重复性
)

# 保存结果
network.to_csv('network_output.tsv', sep='\t', index=False)

输出格式：

DataFrame，列包括：['TF', 'target', 'importance']
更高的重要性分数表示更强的预测调控关系
通常按重要性降序排序

多进程要求： 所有arboreto代码必须包含if __name__ == '__main__':保护，因为Dask的多进程要求：

if __name__ == '__main__':
    # Arboreto代码在此
    network = grnboost2(expression_data=expr_data, seed=42)

2. 算法选择

GRNBoost2（大多数情况推荐）：

比GENIE3快约10-100倍
使用带早停的随机梯度提升
最佳用于：大型数据集（>10k观测值）、时间敏感分析
函数：arboreto.algo.grnboost2()

GENIE3：

使用随机森林回归
更成熟、经典的方法
最佳用于：小型数据集、方法学比较、复制已发表结果
函数：arboreto.algo.genie3()

何时比较两种算法： 使用提供的compare_algorithms.py脚本时：

验证关键分析结果
在新数据集上进行性能基准测试
发表需要方法学比较的研究

3. 分布式计算

本地执行（默认）： Arboreto自动创建本地Dask客户端。无需配置：

network = grnboost2(expression_data=expr_data)

自定义本地集群（推荐以更好控制）：

from dask.distributed import Client, LocalCluster

# 配置集群
cluster = LocalCluster(
    n_workers=4,
    threads_per_worker=2,
    memory_limit='4GB',
    diagnostics_port=8787  # 仪表板位于 http://localhost:8787
)
client = Client(cluster)

# 运行推断
network = grnboost2(
    expression_data=expr_data,
    client_or_address=client
)

# 清理
client.close()
cluster.close()

分布式集群（多节点）： 在调度器节点：

dask-scheduler --no-bokeh

在工作节点：

dask-worker scheduler-address:8786 --local-dir /tmp

在Python中：

from dask.distributed import Client

client = Client('scheduler-address:8786')
network = grnboost2(expression_data=expr_data, client_or_address=client)

4. 数据准备

常见数据格式问题：

转置数据（基因为行而非列）：

# 如果基因为行，转置
expression_data = pd.read_csv('data.tsv', sep='\t', index_col=0).T

缺少基因名称：

# 如果使用numpy数组，提供基因名称
network = grnboost2(
    expression_data=expr_array,
    gene_names=['Gene1', 'Gene2', 'Gene3', ...],
    seed=42
)

转录因子指定：

# 选项1：Python列表
tf_names = ['Sox2', 'Oct4', 'Nanog', 'Klf4']

# 选项2：从文件加载（每行一个TF）
from arboreto.utils import load_tf_names
tf_names = load_tf_names('tf_names.txt')

5. 可重复性

始终指定种子以确保一致结果：

network = grnboost2(expression_data=expr_data, seed=42)

无种子时，由于算法随机性，结果会在运行间变化。

6. 结果解释

理解输出：

TF：转录因子（调控器）基因
target：被调控的靶标基因
importance：预测调控关系的强度

典型后处理：

# 按重要性阈值过滤
high_confidence = network[network['importance'] > 10]

# 获取前N个预测
top_predictions = network.head(1000)

# 查找特定TF的所有靶标
sox2_targets = network[network['TF'] == 'Sox2']

# 统计每个TF的调控数量
tf_counts = network['TF'].value_counts()

安装

推荐（通过conda）：

conda install -c bioconda arboreto

通过pip：

pip install arboreto

从源代码：

git clone https://github.com/tmoerman/arboreto.git
cd arboreto
pip install .

依赖：

pandas
numpy
scikit-learn
scipy
dask
distributed

故障排除

问题：启动Dask调度器时出现Bokeh错误

错误： TypeError: got an unexpected keyword argument 'host'

解决方案：

使用dask-scheduler --no-bokeh禁用Bokeh
升级到Dask distributed >= 0.20.0

问题：工作节点未连接到调度器

症状： 工作进程启动但无法建立连接

解决方案：

重启工作节点前删除dask-worker-space目录
创建集群时指定足够的local_dir：

cluster = LocalCluster(
    worker_kwargs={'local_dir': '/tmp'}
)

问题：大型数据集内存错误

解决方案：

增加工作节点内存限制：memory_limit='8GB'
分发到更多节点
通过预处理（例如特征选择）减少数据集大小
确保表达矩阵适合可用RAM

问题：运行间结果不一致

解决方案： 始终指定seed参数：

network = grnboost2(expression_data=expr_data, seed=42)

问题：导入错误或缺少依赖

解决方案： 使用conda安装以处理数值库依赖：

conda create --name arboreto-env
conda activate arboreto-env
conda install -c bioconda arboreto

提供的脚本

此技能包括常见工作流的即用型脚本：

scripts/basic_grn_inference.py

标准GRN推断工作流的命令行工具。

用法：

python scripts/basic_grn_inference.py expression_data.tsv \
    -t tf_names.txt \
    -o network.tsv \
    -s 42 \
    --transpose  # 如果基因为行

特点：

自动数据加载和验证
可选的TF列表指定
可配置的输出格式
数据转置支持
汇总统计

scripts/distributed_inference.py

带自定义Dask集群配置的GRN推断。

用法：

python scripts/distributed_inference.py expression_data.tsv \
    -t tf_names.txt \
    -w 8 \
    -m 4GB \
    --threads 2 \
    --dashboard-port 8787

特点：

可配置的工作节点数和内存限制
Dask仪表板集成
线程配置
资源监控

scripts/compare_algorithms.py

并排比较GRNBoost2和GENIE3。

用法：

python scripts/compare_algorithms.py expression_data.tsv \
    -t tf_names.txt \
    --top-n 100

特点：

运行时间比较
网络统计
预测重叠分析
前预测比较

参考文档

详细API文档位于references/api_reference.md，包括：

所有函数的完整参数描述
数据格式规范
分布式计算配置
性能优化提示
与pySCENIC的集成
全面示例

加载此参考当：

使用高级Dask配置
故障排除复杂部署场景
理解算法内部机制
针对特定用例优化性能

与pySCENIC集成

Arboreto是pySCENIC单细胞分析流水线的第一步：

GRN推断（arboreto） ← 此技能
- 输入：表达矩阵
- 输出：调控网络
Regulon预测（pySCENIC）
- 输入：来自arboreto的网络
- 输出：精炼的regulons
细胞类型识别（pySCENIC）
- 输入：Regulons
- 输出：细胞类型分数

当使用pySCENIC时，使用arboreto生成初始网络，然后将结果传递到pySCENIC流水线。

最佳实践

始终使用seed参数以确保可重复研究
验证数据方向（行 = 观测值，列 = 基因）
指定TF列表以聚焦推断并提高速度
使用Dask仪表板监控分布式计算
保存中间结果以避免重新运行长时间计算
按重要性阈值过滤结果用于下游分析
默认使用GRNBoost2除非特别需要GENIE3
在所有脚本中包含多进程保护（if __name__ == '__main__':）

快速参考

基本推断：

from arboreto.algo import grnboost2
network = grnboost2(expression_data=expr_df, seed=42)

带TF指定：

network = grnboost2(expression_data=expr_df, tf_names=tf_list, seed=42)

带自定义Dask客户端：

from dask.distributed import Client, LocalCluster
cluster = LocalCluster(n_workers=4)
client = Client(cluster)
network = grnboost2(expression_data=expr_df, client_or_address=client, seed=42)
client.close()
cluster.close()

加载TF名称：

from arboreto.utils import load_tf_names
tf_names = load_tf_names('transcription_factors.txt')

转置数据：

expression_df = pd.read_csv('data.tsv', sep='\t', index_col=0).T