deepchem

DeepChem

概要

DeepChemは、化学、材料科学、生物学に機械学習を適用するための包括的なPythonライブラリです。専用のニューラルネットワーク、分子の特徴量化手法、事前学習済みモデルを通じて、分子特性の予測、創薬、材料設計、生体分子解析を実現します。

バージョンに関する注意： 例は deepchem 2.8.0（PyPI安定版、2024年4月）を対象としています。Python 3.7–3.11 が必要です（PyPIでは <3.12）。コアユーティリティ（ローダー、特徴量化器、MoleculeNet）はDLバックエンドなしで動作します。GNNモデルとトランスフォーマーモデルには、対応する追加パッケージ（torch、tensorflow、または jax）が必要です。GPUビルドを使用する場合は、先にバックエンドのフレームワークをインストールしてください。

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

以下の場合にこのスキルを使用してください：

• 分子データ（SMILES文字列、SDFファイル、タンパク質配列）の読み込みと処理
• 分子特性（溶解度、毒性、結合親和性、ADMET特性）の予測
• 化学・生物学データセットでのモデルの学習
• MoleculeNetベンチマークデータセット（Tox21、BBBP、Delaneyなど）の使用
• 分子のML向け特徴量への変換（フィンガープリント、グラフ表現、記述子）
• 分子向けグラフニューラルネットワーク（GCN、GAT、MPNN、AttentiveFP）の実装
• 事前学習済みモデル（ChemBERTa、GROVER、MolFormer）による転移学習の適用
• 結晶・材料特性（バンドギャップ、生成エネルギー）の予測
• タンパク質またはDNA配列の解析

コア機能

実際に動作するコードを含む8つの機能領域については、 references/core_capabilities.md を参照してください。

1. 分子データの読み込みと処理 — ローダー、NumpyDataset / DiskDataset。
2. 分子の特徴量化 — 円形フィンガープリント、グラフ畳み込み、記述子。
3. データ分割 — ランダム、スキャフォールド、層化、Butina分割、および分子ではスキャフォールド分割が誠実なデフォルトである理由。
4. モデルの選択と学習 — モデルファミリーとその学習方法。
5. MoleculeNetベンチマーク — 標準データセットと公開済みの分割方法の読み込み。
6. 転移学習 — 事前学習とファインチューニング。
7. モデル評価 — 回帰タスクと分類タスクに適した指標。
8. 予測の実行 — 学習済みモデルの新しい分子への適用。

エンドツーエンドのワークフロー3つについては、 references/typical_workflows.md を参照してください。

サンプルスクリプト

このスキルには、scripts/ ディレクトリに本番環境向けのスクリプトが3つ含まれています。

1. predict_solubility.py

溶解度予測モデルを学習して評価します。DelaneyベンチマークまたはカスタムCSVデータに対応しています。

# Use Delaney benchmark
python scripts/predict_solubility.py

# Use custom data
python scripts/predict_solubility.py \
    --data my_data.csv \
    --smiles-col smiles \
    --target-col solubility \
    --predict "CCO" "c1ccccc1"

2. graph_neural_network.py

分子データを用いて、さまざまなグラフニューラルネットワークアーキテクチャを学習します。

# Train GCN on Tox21
python scripts/graph_neural_network.py --model gcn --dataset tox21

# Train AttentiveFP on custom data
python scripts/graph_neural_network.py \
    --model attentivefp \
    --data molecules.csv \
    --task-type regression \
    --targets activity \
    --epochs 100

3. transfer_learning.py

分子特性予測タスク向けに、事前学習済みモデル（ChemBERTa、GROVER、MolFormer）をファインチューニングします。

# Fine-tune ChemBERTa on BBBP
python scripts/transfer_learning.py --model chemberta --dataset bbbp

# Fine-tune GROVER on custom data
python scripts/transfer_learning.py \
    --model grover \
    --data small_dataset.csv \
    --target activity \
    --task-type classification \
    --epochs 20

よくあるパターンとベストプラクティス

パターン1：分子には必ずスキャフォールド分割を使用する

# GOOD: Prevents data leakage
splitter = dc.splits.ScaffoldSplitter()
train, test = splitter.train_test_split(dataset)

# BAD: Similar molecules in train and test
splitter = dc.splits.RandomSplitter()
train, test = splitter.train_test_split(dataset)

パターン2：特徴量とターゲットを正規化する

transformers = [
    dc.trans.NormalizationTransformer(
        transform_y=True,  # Also normalize target values
        dataset=train
    )
]
for transformer in transformers:
    train = transformer.transform(train)
    test = transformer.transform(test)

パターン3：シンプルな方法から始めて、段階的に拡張する

1. Random Forest + CircularFingerprintから始める（高速なベースライン）
2. RFの性能がよければ、XGBoost/LightGBMを試す
3. 5Kを超えるサンプルがある場合は、ディープラーニング（MultitaskRegressor）に進む
4. 10Kを超えるサンプルがある場合は、GNNを試す
5. データセットが小さい場合や新しいスキャフォールドの場合は、転移学習を使用する

パターン4：不均衡データに対処する

# Option 1: Balancing transformer
transformer = dc.trans.BalancingTransformer(dataset=train)
train = transformer.transform(train)

# Option 2: Use balanced metrics
metric = dc.metrics.Metric(dc.metrics.balanced_accuracy_score)

パターン5：メモリの問題を回避する

# Use DiskDataset for large datasets
dataset = dc.data.DiskDataset.from_numpy(X, y, w, ids)

# Use smaller batch sizes
model = dc.models.GCNModel(batch_size=32)  # Instead of 128

よくある落とし穴

問題1：創薬におけるデータリーク

問題： ランダム分割を使うと、類似した分子が学習セットとテストセットの両方に含まれます。 解決策： 分子データセットでは、必ず ScaffoldSplitter を使用してください。

問題2：GNNの性能がフィンガープリントを下回る

問題： グラフニューラルネットワークの性能が、単純なフィンガープリントを下回ります。 解決策：

• データセットの規模が十分であることを確認する（通常は10Kを超えるサンプルが必要）
• 学習エポック数を増やす（50～100）
• 別のアーキテクチャを試す（GCNの代わりにAttentiveFP、DMPNN）
• 事前学習済みモデル（GROVER）を使用する

問題 3：小規模データセットでの過学習

問題：モデルが学習データを記憶してしまいます。 解決策：

• 正則化を強化します（ドロップアウトを 0.5 に増やします）
• よりシンプルなモデルを使用します（ディープラーニングの代わりに Random Forest を使用します）
• 転移学習を適用します（ChemBERTa、GROVER）
• データをさらに収集します

問題 4：インポートエラー

問題：No module named 'torch' / No module named 'tensorflow' という警告が表示される、またはモデルクラスのインポートに失敗します。 解決策：DeepChem は遅延読み込みを行います。モデルに適合するバックエンドをインストールしてから、対応する追加パッケージを指定します。

uv pip install deepchem              # loaders, featurizers, MoleculeNet only
uv pip install 'deepchem[torch]'       # GCN, GAT, AttentiveFP, HuggingFaceModel, GroverModel
uv pip install 'deepchem[tensorflow]'  # legacy Keras models
uv pip install 'deepchem[jax]'         # Haiku/JAX models

GPU を使用する場合は、追加パッケージより先に、正しい CUDA ビルドの PyTorch または TensorFlow をインストールしてください。zsh では追加パッケージを引用符で囲みます：'deepchem[torch]'。

Conda + PyTorch ユーザー向け： import deepchem が undefined symbol: iJIT_NotifyEvent で失敗する場合は、MKL のバージョンを 2025 未満に固定してください（conda install "mkl<2025"）。PyTorch のホイールは MKL 2025.0.0 と互換性がない場合があります。

リファレンスドキュメント

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

references/api_reference.md

以下を含む完全な API ドキュメント：

• すべてのデータローダーとその使用例
• データセットクラスと、それぞれを使用するタイミング
• 選択ガイド付きの完全な特徴量化器カタログ
• カテゴリ別に整理されたモデルカタログ（50 以上のモデル）
• MoleculeNet データセットの説明
• メトリクスと評価関数
• 一般的なコードパターン

参照するタイミング：特定の API の詳細やパラメーター名が必要な場合、または利用可能なオプションを確認する場合に、このファイルを検索してください。

references/workflows.md

詳細なエンドツーエンドのワークフロー 8 例：

1. SMILES からの分子特性予測
2. MoleculeNet ベンチマークの使用
3. ハイパーパラメーター最適化
4. 事前学習済みモデルを使用した転移学習
5. GAN による分子生成
6. 材料特性の予測
7. タンパク質配列の解析
8. カスタムモデルの統合

参照するタイミング：完全なソリューションを実装する際のテンプレートとして、これらのワークフローを使用してください。

インストール

コアパッケージ（データローダー、特徴量化器、MoleculeNet、scikit-learn ラッパー）：

uv pip install deepchem

モデルのバックエンドに対応する追加パッケージを指定してください（GPU ビルドの場合は、先に PyTorch/TensorFlow/JAX をインストールします）。

uv pip install 'deepchem[torch]'       # GNNs, TorchModel, HuggingFaceModel, GroverModel
uv pip install 'deepchem[tensorflow]'  # Keras/TensorFlow models
uv pip install 'deepchem[jax]'         # JAX/Haiku models
uv pip install 'deepchem[dqc]'         # Differentiable quantum chemistry (torch + xitorch)

ナイトリービルド：uv pip install --pre deepchem（同じ追加パッケージを --pre と併用できます）。

モデルクラスごとのオプション依存関係については、インストールガイドとソフトウェア要件を参照してください。

追加リソース

• 公式ドキュメント：https://deepchem.readthedocs.io/
• GitHub リポジトリ：https://github.com/deepchem/deepchem
• チュートリアル：https://deepchem.readthedocs.io/en/latest/get_started/tutorials.html
• 論文：「MoleculeNet: A Benchmark for Molecular Machine Learning」

エージェントの作業手順

1. 環境を確認します。 ツールキットのバージョンと入力形式（SMILES、SDF、PDB、CIF）を確認し、計算の前に分子をサニタイズします。
2. 入力を明確にします。 データまたはユーザーに確認し、形式、識別子、パラメーターを確定します。結果に影響する値は推測せず、確認してください。
3. まず小規模に実行します。 いくつかの分子、または1つのターゲットを処理し、出力を確認します。
4. 上記の指示と参考資料に従って、タスク全体を実行します。
5. 結果を検証します。 無効な構造、単位の整合性、予測モデルの適用領域を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実性を明記します。

発生した事象	対応
分子の解析またはサニタイズに失敗する	理由を添えて報告し、対象をスキップします。構造を黙って削除したり変更したりしてはいけません。
これらの指示にある関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応してユーザーに伝えます。APIを捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧である	ユーザーに確認するか、実行前に前提を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計値を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• 計算による予測は仮説であり、実験結果ではありません。そのように明記してください。
• ここに記載されているバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認してください。
• 金銭が発生する操作、共有GPUやクラウドの利用枠を消費する操作、個人データや患者データに触れる操作、または取り消せない操作を行う前に、ユーザーに確認してください。

関連スキル

• torchdrug：分子グラフ、物性予測、自己教師あり事前学習、分子生成のためのTorchDrug 0.2.1のワークフローを構築し、トラブルシューティングします…
• pytdc：PyTDCパッケージ（tdcをインポート、Therapeutics Data Commons）を使用して、tdc.metadataから治療に関するMLタスクを見つけ、承認済みのd…を計画して読み込みます
• molfeat：molfeat（0.11.0）を使用して、SMILES文字列またはRDKit/datamol分子を数値特徴量に変換します。molfeatは計算器、scikit-learn…を提供します