arboreto

Arboreto

概要

Arboretoは、遺伝子発現データから遺伝子制御ネットワーク（GRN）を推定するためのAerts LabのPythonライブラリです。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)

重要：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 --limit 5000

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

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フィルタリングを使用したバルク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)

arboretoで直接使用するため、AnnDataをDataFrameに変換します：

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

トラブルシューティング

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

パフォーマンスが遅い場合：GENIE3 の代わりに GRNBoost2 を使用し、分散クライアントを有効にして、TF リストをフィルタリングしてください。

Dask のエラー：スクリプトに if __name__ == '__main__': ガードが含まれていることを確認してください（spawn ベースのマルチプロセッシングを使用する Windows/macOS では必須です）。

結果が空の場合：データ形式（列が遺伝子になっているか）を確認し、TF 名が発現行列の列名と一致していることを確認してください。

スパースデータ：scipy.sparse.csc_matrix を使用し、一致する gene_names を渡してください。arboreto 0.1.6 / pySCENIC 0.11 以降でサポートされています。

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を特定します。 データまたはユーザーから形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 最初に、少数のサブセット（1 サンプル、1 染色体、数千個の細胞）でパイプラインを実行します。
4. 上記の手順と参照情報を使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの識別情報、ゲノムビルドの一貫性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を記載します。

次のような場合	対応
入力間でゲノムビルドまたは識別子が一致しない	続行する前に処理を中止し、整合させてください（liftover、ID マッピング）。
これらの手順に記載されている関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適宜対応し、ユーザーに伝えてください。API を決してでっち上げないでください。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに質問するか、実行前に前提を明示してください。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えてください。
• 統計で裏付けられる範囲を超えて生物学的な意義を解釈しないでください。多重検定補正について報告してください。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントと照合してください。
• 費用が発生する、共有 GPU やクラウドのクォータを消費する、個人データまたは患者データを扱う、あるいは取り消せない操作を行う前に、必ず確認してください。

関連スキル

• cellxgene-census：バージョン管理された公開単一細胞・空間トランスクリプトミクスデータをプログラムから検索するための、CZ CELLxGENE Census クエリ。
• pydeseq2：PyDESeq2（DESeq2 の Python 移植版）を使用して、バルク RNA-seq カウントデータの差次的発現解析を実行します。
• bulk-rnaseq：バルク RNA-seq のエンドツーエンドオーケストレーターです。生の FASTQ リードを QC とトリミング（FastQC、fastp/Trim Galore）、アライメント、定量まで処理します…