alterlab-arboreto

Arboreto

概要

Arboreto は、単一マシンから複数ノードのクラスターまでスケールする並列化アルゴリズムを使用して、遺伝子発現データから遺伝子制御ネットワーク（GRN）を推定する計算ライブラリです。

主な機能：観測データ（細胞、サンプル、条件）全体の発現パターンに基づいて、どの転写因子（TF）がどの標的遺伝子を制御しているかを特定します。

このスキルを使用する場面

次のような場合にこのスキルを使用します。

• バルクまたは単一細胞の発現マトリックスから、TF → 標的遺伝子の制御ネットワークを推定する。
• SCENIC / pySCENIC パイプラインの GRN 推定ステップ（ステップ 1）を実行する。
• GRNBoost2 と GENIE3 を比較する、またはランダムシードを変えてコンセンサスネットワークを構築する。
• コアまたは Dask クラスター全体で GRN 推定をスケールする。

該当しないケース

シナリオ	代わりに使用するもの
条件間の差次的発現（counts → padj）	alterlab-pydeseq2
単一細胞データセットのクラスタリング、UMAP、または QC	alterlab-scanpy
scRNA-seq の深層学習による潜在空間 / バッチ統合	alterlab-scvi-tools
既存ネットワークの一般的なグラフ解析または中心性解析	alterlab-networkx
GRN 推定の実行ではなく、Dask クラスター自体の調整	alterlab-dask

クイックスタート

arboreto をインストールします。

uv pip install arboreto

Arboreto 0.1.6 は 2021 年のもので、内部では dask.delayed と dask.dataframe.from_delayed を使用しています。これらの API は現在の dask にも存在しますが、実行が arboreto 内部ではなく dask 内部で失敗する場合は、arboreto を編集するのではなく、隔離された環境で dask／distributed のバージョンを互換性のある組み合わせに固定してください（pySCENIC のバージョン固定が参考になります）。

基本的な 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 には 2 つのアルゴリズムがあります。

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 フィルタリングを使用したバルク 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 は確率的であるため、単一のシードで固定できるのは1回の実行結果に限られ、頑健性は確認できません。コンセンサスネットワークを作成するには、複数のシードで実行し、繰り返し現れるリンクを保持して、その重要度を平均してください。

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

トラブルシューティング

メモリエラー：低分散遺伝子をフィルタリングしてデータセットのサイズを縮小するか、分散コンピューティングを使用してください。

パフォーマンスが遅い：GENIE3 の代わりに GRNBoost2 を使用し、分散クライアントを有効にして、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 スイートの一部です。