alterlab-torch-geometric

PyTorch Geometric（PyG）

概要

PyTorch Geometric は、グラフニューラルネットワーク（GNN）の開発と学習のために PyTorch 上に構築されたライブラリです。ミニバッチ処理、マルチ GPU 学習、幾何学的深層学習のアプリケーションなど、グラフや不規則な構造を対象とする深層学習にこのスキルを使用します。

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

次の用途で作業する際にこのスキルを使用してください。

• グラフベースの機械学習：ノード分類、グラフ分類、リンク予測
• 分子特性予測：創薬、化学特性の予測
• ソーシャルネットワーク分析：コミュニティ検出、影響力の予測
• 引用ネットワーク：論文分類、推薦システム
• 3D 幾何データ：点群、メッシュ、分子構造
• 異種グラフ：複数タイプのノードとエッジ（例：ナレッジグラフ）
• 大規模グラフ学習：近傍サンプリング、分散学習

対象外

シナリオ	代わりに使用
学習を伴わない古典的なグラフアルゴリズム、中心性、最短経路、ネットワークの可視化	alterlab-networkx
実質的な社会科学上の主張を目的とする、ソーシャルネットワーク分析の設計（中心性、コミュニティ検出、ERGM）	alterlab-sna
MoleculeNet の特徴量生成器と事前学習済み化学モデルを使用する、エンドツーエンドの分子特性予測	alterlab-deepchem
TorchDrug のデータセットとタスク（GearNet、逆合成、分子生成）を基盤とするプロジェクト	alterlab-torchdrug

クイックスタート

uv pip install torch_geometric
# Optional compiled ops (neighbor sampling, knn/radius graphs, fps): pick TORCH/CUDA to match your install
uv pip install pyg-lib -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html

PyG 2.8 では torch-cluster と torch-spline-conv が pyg-lib（>= 0.7）に統合されたため、これら 2 つの パッケージは不要になりました。pyg-lib（または torch-sparse）がインストールされていないと、NeighborLoader は ImportError を発生させます。現行の PyTorch（2.13/2.14）では、data.pyg.org が公開しているのは pyg-lib のホイールのみで、torch-scatter／torch-sparse のホイールはありません。

グラフは torch_geometric.data.Data オブジェクトです。x（ノード特徴量 [N, F]）、edge_index （COO 形式の接続情報 [2, E]）、任意の edge_attr、y、pos、および任意のカスタム属性 （train_mask など）を持ちます。DataLoader は複数のグラフを 1 つのブロック対角グラフに まとめてバッチ処理します（パディングなし）。batch ベクトルでノードの元のグラフを特定できます。

インストールとスパース依存関係、基本的なグラフの作成、ベンチマークの読み込み、エッジインデックスの形式、ミニバッチ処理の詳細については、references/getting_started.md を参照してください。

基本的なワークフロー

1. データの読み込みまたは構築 — ベンチマークデータセット、カスタム InMemoryDataset、または CSV からの読み込み（references/datasets_and_loading.md。カタログ全体は references/datasets_reference.md）。
2. GNN の定義 — 既製の畳み込みレイヤー（GCNConv、GATConv、SAGEConv）を積み重ねるか、MessagePassing をサブクラス化してカスタムレイヤーを作成します（references/building_gnns.md。レイヤー一覧全体は references/layers_reference.md）。
3. 学習 — ノード分類（単一グラフ、学習／テスト用マスク）、グラフ分類（DataLoader + グローバルプーリング）、または NeighborLoader による近傍サンプリングを用いた大規模学習（references/training_workflows.md）。
4. 必要に応じて高度な機能を活用 — 異種グラフ向けの HeteroData／to_hetero、変換、GNNExplainer による説明可能性、階層プーリング、GPU、保存／読み込み（references/advanced_features.md。変換のカタログは references/transforms_reference.md）。

GNN の構築（概要）

GNN は近傍集約に従います。ノード特徴量を変換 → エッジに沿ってメッセージを伝播 → 近傍から集約 → 表現を更新します。PyG には 40 種類以上の畳み込みレイヤーが用意されています。レイヤーを選ぶ際は、SparseTensor のサポート、edge_weight、edge_attr、二部グラフへの対応、遅延（-1 チャンネル）初期化などの機能を確認してください。GCN／GAT／GraphSAGE と、カスタム MessagePassing レイヤー（_i／_j によるターゲット／ソースの命名規則を含む）のコードは references/building_gnns.md にあります。

リソース

同梱のリファレンス

このスキルには、詳細なリファレンスドキュメントが含まれています。

• references/getting_started.md：インストール、基本的なグラフの作成、Data の構造、エッジインデックスの形式、ミニバッチ処理
• references/building_gnns.md：メッセージパッシング、GCN／GAT／GraphSAGE のコード、カスタム MessagePassing レイヤー、レイヤーの機能
• references/datasets_and_loading.md：組み込みデータセット、カスタム InMemoryDataset、CSV からのグラフの読み込み
• references/training_workflows.md：ノード分類、グラフ分類、大規模な近傍サンプリング
• references/advanced_features.md：異種グラフ、変換、説明可能性、プーリング、GPU、保存／読み込み
• references/layers_reference.md：説明と機能を含む、40 種類以上の GNN レイヤーの完全な一覧
• references/datasets_reference.md：カテゴリ別に整理された包括的なデータセットカタログ
• references/transforms_reference.md：利用可能なすべての変換とその用途

スクリプト

ユーティリティスクリプトは scripts/ に用意されています。

• scripts/visualize_graph.py：networkx と matplotlib を使用してグラフ構造を可視化します
• scripts/create_gnn_template.py：一般的な GNN アーキテクチャのボイラープレートコードを生成します
• scripts/benchmark_model.py：標準データセットでモデルのパフォーマンスをベンチマークします

スクリプトを直接実行するか、実装パターンを確認するために読み込んでください。

公式リソース

• ドキュメント：https://pytorch-geometric.readthedocs.io/
• GitHub：https://github.com/pyg-team/pytorch_geometric
• チュートリアル：https://pytorch-geometric.readthedocs.io/en/latest/get_started/introduction.html
• サンプル：https://github.com/pyg-team/pytorch_geometric/tree/master/examples

AlterLab Academic Skills スイートの一部です。