arboreto

Arboreto

概要

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

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

クイックスタート

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

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

インストール

推奨（Conda）：

conda install -c bioconda arboreto

別の方法（pip）：

pip install arboreto

分離された環境を使用する場合：

conda create --name arboreto-env
conda activate arboreto-env
conda install -c bioconda 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名が遺伝子名と一致していることを確認してください