DGNN-BCMMM 再現実験プロジェクト

• タスク種別 : リンク予測
• GNNフレームワーク : torch-geometric
• CUDA 有無 : CPU

参照論文「DGNN-BCMMM: Dynamic Graph Neural Networks for Bayesian Causal Marketing Mix Modeling」に基づき、data/MMM_data.csv のみから動的グラフを構築し、チャネルリンクの将来活性化を予測する実装を収録しています。コード・ノートブック・構成ファイルはすべてローカル再現（uv）と Google Colab 実行の両立を前提に整備されています。

ディレクトリ概要

.
├── data/MMM_data.csv        # 唯一使用する入力データ
├── figures/                 # 可視化の保存先（任意）
├── outputs/                 # Notebook/スクリプトが生成する成果物
├── paper/                   # 既存の論文テンプレート
├── src/                     # Python モジュール（再現実装テンプレ）
├── DGNN_BCMMM_reproduction.ipynb  # Colab 互換 Notebook
├── pyproject.toml           # uv 管理用メタ情報
├── requirements.txt         # Colab 用依存関係（CPU Torch 指定）
├── .pre-commit-config.yaml  # コード整形と静的解析フック
└── README.md

uv を用いたローカル開発手順

uv を利用すると Python バージョン固定・依存関係ロック・スクリプト実行が一貫して行えます。

1. uv 導入（未導入の場合）

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Python バージョン固定

   uv python pin 3.11

3. 依存パッケージ追加（プロジェクトにはすでに追加済み）

   uv add torch==2.2.1 torch-geometric==2.5.3 torch-scatter==2.1.2 \\
          torch-sparse==0.6.18 torch-cluster==1.6.3 torch-spline-conv==1.2.2 \\
          numpy==1.26.4 pandas==2.2.1 matplotlib==3.8.3 \\
          scikit-learn==1.4.2 tqdm==4.66.2 pyyaml==6.0.1 networkx==3.2.1 \\
          rich==13.7.1 japanize-matplotlib notebook

   PyTorch/torch-geometric のホイールは pyproject.toml の [[tool.uv.find-links]] で CPU 向けインデックスを指定しています。
4. ロックファイル作成

   uv lock

5. Colab 共有用 requirements.txt の生成

   uv export --no-hashes -o requirements.txt

6. スクリプト・Notebook の実行例

   uv run python -m src.train          # 学習スクリプト
   uv run jupyter notebook             # Jupyter Notebook を起動

   ※ src/train.py には CLI 用エントリーポイントが用意されており、outputs/ 以下に config.yaml・metrics.json・best_model.pt・test_predictions.npy を保存します。

コード品質チェック

uv run pre-commit install
uv run pre-commit run --all-files

Google Colab での再現手順

1. ノートブック DGNN_BCMMM_reproduction.ipynb を Colab にアップロードします。
2. 先頭セルで DATA_ROOT や乱数シードを設定し、フォールバックが機能することを確認します。
3. 次のセルで依存関係をインストールします。

   !pip install -r requirements.txt

4. 各章（0〜11）を順番に実行します。学習完了後、./outputs/ に
   • config.yaml
   • metrics.json
   • best_model.pt
   • test_predictions.npy が保存され、学習曲線・指標表・代表的サブグラフ可視化が表示されます。

実装概要

• src/utils.py : 乱数固定・入出力ユーティリティ・デバイス管理。
• src/data.py : スキーマ検証、チャネル別イベント生成、時間順データセット作成。
• src/model.py : 時間埋め込み付メモリ更新を備えた DGNN-BCMMM コアモデル。
• src/losses.py : クラス不均衡を考慮した二値クロスエントロピー損失。
• src/metrics.py : AUC / AP / Precision@K / Recall@K を計算する指標関数。
• src/train.py : ExperimentConfig を基に学習ループ・検証・成果物保存を実装（tqdm による進捗表示）。

Notebook と Python モジュールは同じ処理フローを共有し、ローカルでも Colab でも data/MMM_data.csv 以外の外部データは参照しません。乱数シード・バージョン固定・例外時の明示的ログにより再現性を担保しています。

参考

• DGNN-BCMMM: Dynamic Graph Neural Networks for Bayesian Causal Marketing Mix Modeling.
• torch-geometric / PyTorch ドキュメント（CPU 版ホイール利用）。
• uv 公式ドキュメント: https://docs.astral.sh/uv/