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)

重要: Dask は新しいプロセスを生成するため、必ず if __name__ == '__main__': ガードを使用してください。

主な機能

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)

    # Filter high-confidence links
    high_confidence = network[network['importance'] > 0.5]
    high_confidence.to_csv('grn_high_confidence.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	制御の重要度スコア（高いほど強い）

フィルタリング戦略:

• 標的遺伝子ごとの上位 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)

トラブルシューティング

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

処理が遅い: GENIE3 ではなく GRNBoost2 を使用し、分散クライアントを有効にし、TF リストをフィルタリングしてください

Dask のエラー: スクリプトに if __name__ == '__main__': ガードが含まれていることを確認してください

結果が空: データ形式（遺伝子が列になっているか）を確認し、TF 名が遺伝子名と一致しているか確認してください