deepchem

DeepChem

概要

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

このスキルを使用するタイミング

このスキルは次の場合に使用してください:

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

主な機能

1. 分子データの読み込みと処理

DeepChem は、さまざまな化学データ形式に対応した専用のローダーを提供します:

import deepchem as dc

# Load CSV with SMILES
featurizer = dc.feat.CircularFingerprint(radius=2, size=2048)
loader = dc.data.CSVLoader(
    tasks=['solubility', 'toxicity'],
    feature_field='smiles',
    featurizer=featurizer
)
dataset = loader.create_dataset('molecules.csv')

# Load SDF files
loader = dc.data.SDFLoader(tasks=['activity'], featurizer=featurizer)
dataset = loader.create_dataset('compounds.sdf')

# Load protein sequences
loader = dc.data.FASTALoader()
dataset = loader.create_dataset('proteins.fasta')

主なローダー:

• CSVLoader: 分子識別子を含む表形式データ
• SDFLoader: 分子構造ファイル
• FASTALoader: タンパク質/DNA 配列
• ImageLoader: 分子画像
• JsonLoader: JSON 形式のデータセット

2. 分子特徴量化

分子を ML モデル向けの数値表現に変換します。

特徴量化手法の選択フローチャート

Is the model a graph neural network?
├─ YES → Use graph featurizers
│   ├─ Standard GNN → MolGraphConvFeaturizer
│   ├─ Message passing → DMPNNFeaturizer
│   └─ Pretrained → GroverFeaturizer
│
└─ NO → What type of model?
    ├─ Traditional ML (RF, XGBoost, SVM)
    │   ├─ Fast baseline → CircularFingerprint (ECFP)
    │   ├─ Interpretable → RDKitDescriptors
    │   └─ Maximum coverage → MordredDescriptors
    │
    ├─ Deep learning (non-graph)
    │   ├─ Dense networks → CircularFingerprint
    │   └─ CNN → SmilesToImage
    │
    ├─ Sequence models (LSTM, Transformer)
    │   └─ SmilesToSeq
    │
    └─ 3D structure analysis
        └─ CoulombMatrix

特徴量化の例

# Fingerprints (for traditional ML)
fp = dc.feat.CircularFingerprint(radius=2, size=2048)

# Descriptors (for interpretable models)
desc = dc.feat.RDKitDescriptors()

# Graph features (for GNNs)
graph_feat = dc.feat.MolGraphConvFeaturizer()

# Apply featurization
features = fp.featurize(['CCO', 'c1ccccc1'])

選択ガイド:

• 小規模データセット（1K 未満）: CircularFingerprint または RDKitDescriptors
• 中規模データセット（1K〜100K）: CircularFingerprint またはグラフ系特徴量化手法
• 大規模データセット（100K 超）: グラフ系特徴量化手法（MolGraphConvFeaturizer、DMPNNFeaturizer）
• 転移学習: 事前学習済みモデルの特徴量化手法（GroverFeaturizer）

すべての特徴量化手法の詳細については references/api_reference.md を参照してください。

3. データ分割

重要: 創薬タスクでは、類似した分子構造が学習データとテストデータの両方に現れてデータリークが起きるのを防ぐため、ScaffoldSplitter を使用してください。

# Scaffold splitting (recommended for molecules)
splitter = dc.splits.ScaffoldSplitter()
train, valid, test = splitter.train_valid_test_split(
    dataset,
    frac_train=0.8,
    frac_valid=0.1,
    frac_test=0.1
)

# Random splitting (for non-molecular data)
splitter = dc.splits.RandomSplitter()
train, test = splitter.train_test_split(dataset)

# Stratified splitting (for imbalanced classification)
splitter = dc.splits.RandomStratifiedSplitter()
train, test = splitter.train_test_split(dataset)

利用可能な分割手法:

• ScaffoldSplitter: 分子骨格による分割（データリークを防止）
• ButinaSplitter: クラスタリングに基づく分子分割
• MaxMinSplitter: データセット間の多様性を最大化
• RandomSplitter: ランダム分割
• RandomStratifiedSplitter: クラス分布を保持

4. モデルの選択と学習

モデル選択の簡易ガイド

データセットのサイズ	タスク	推奨モデル	特徴量化手法
1K 未満のサンプル	任意	SklearnModel（RandomForest）	CircularFingerprint
1K〜100K	分類/回帰	GBDTModel または MultitaskRegressor	CircularFingerprint
100K 超	分子特性	GCNModel、AttentiveFPModel、DMPNNModel	MolGraphConvFeaturizer
任意（小規模が望ましい）	転移学習	ChemBERTa、GROVER、MolFormer	モデル固有
結晶構造	材料特性	CGCNNModel、MEGNetModel	構造ベース
タンパク質配列	タンパク質特性	ProtBERT	配列ベース

例: 従来型の機械学習

from sklearn.ensemble import RandomForestRegressor

# Wrap scikit-learn model
sklearn_model = RandomForestRegressor(n_estimators=100)
model = dc.models.SklearnModel(model=sklearn_model)
model.fit(train)

例: ディープラーニング

# Multitask regressor (for fingerprints)
model = dc.models.MultitaskRegressor(
    n_tasks=2,
    n_features=2048,
    layer_sizes=[1000, 500],
    dropouts=0.25,
    learning_rate=0.001
)
model.fit(train, nb_epoch=50)

例: グラフニューラルネットワーク

# Graph Convolutional Network
model = dc.models.GCNModel(
    n_tasks=1,
    mode='regression',
    batch_size=128,
    learning_rate=0.001
)
model.fit(train, nb_epoch=50)

# Graph Attention Network
model = dc.models.GATModel(n_tasks=1, mode='classification')
model.fit(train, nb_epoch=50)

# Attentive Fingerprint
model = dc.models.AttentiveFPModel(n_tasks=1, mode='regression')
model.fit(train, nb_epoch=50)

5. MoleculeNet ベンチマーク

標準化された train/valid/test 分割を備えた 30 種類以上のキュレーション済みベンチマークデータセットに、簡単にアクセスできます:

# Load benchmark dataset
tasks, datasets, transformers = dc.molnet.load_tox21(
    featurizer='GraphConv',  # or 'ECFP', 'Weave', 'Raw'
    splitter='scaffold',     # or 'random', 'stratified'
    reload=False
)
train, valid, test = datasets

# Train and evaluate
model = dc.models.GCNModel(n_tasks=len(tasks), mode='classification')
model.fit(train, nb_epoch=50)

metric = dc.metrics.Metric(dc.metrics.roc_auc_score)
test_score = model.evaluate(test, [metric])

主なデータセット:

• 分類: load_tox21()、load_bbbp()、load_hiv()、load_clintox()
• 回帰: load_delaney()、load_freesolv()、load_lipo()
• 量子特性: load_qm7()、load_qm8()、load_qm9()
• 材料: load_perovskite()、load_bandgap()、load_mp_formation_energy()

データセットの完全な一覧については references/api_reference.md を参照してください。

6. Transfer Learning

事前学習済みモデルを活用して性能を向上させます。特に小規模データセットに有効です:

# ChemBERTa (BERT pretrained on 77M molecules)
model = dc.models.HuggingFaceModel(
    model='seyonec/ChemBERTa-zinc-base-v1',
    task='classification',
    n_tasks=1,
    learning_rate=2e-5  # Lower LR for fine-tuning
)
model.fit(train, nb_epoch=10)

# GROVER (graph transformer pretrained on 10M molecules)
model = dc.models.GroverModel(
    task='regression',
    n_tasks=1
)
model.fit(train, nb_epoch=20)

転移学習を使用する場面:

• 小規模データセット（< 1000 サンプル）
• 新規の分子骨格
• 計算リソースが限られている場合
• 迅速なプロトタイピングが必要な場合

ガイド付きの転移学習ワークフローには scripts/transfer_learning.py スクリプトを使用します。

7. Model Evaluation

# Define metrics
classification_metrics = [
    dc.metrics.Metric(dc.metrics.roc_auc_score, name='ROC-AUC'),
    dc.metrics.Metric(dc.metrics.accuracy_score, name='Accuracy'),
    dc.metrics.Metric(dc.metrics.f1_score, name='F1')
]

regression_metrics = [
    dc.metrics.Metric(dc.metrics.r2_score, name='R²'),
    dc.metrics.Metric(dc.metrics.mean_absolute_error, name='MAE'),
    dc.metrics.Metric(dc.metrics.root_mean_squared_error, name='RMSE')
]

# Evaluate
train_scores = model.evaluate(train, classification_metrics)
test_scores = model.evaluate(test, classification_metrics)

8. Making Predictions

# Predict on test set
predictions = model.predict(test)

# Predict on new molecules
new_smiles = ['CCO', 'c1ccccc1', 'CC(C)O']
new_features = featurizer.featurize(new_smiles)
new_dataset = dc.data.NumpyDataset(X=new_features)

# Apply same transformations as training
for transformer in transformers:
    new_dataset = transformer.transform(new_dataset)

predictions = model.predict(new_dataset)

Typical Workflows

Workflow A: Quick Benchmark Evaluation

標準ベンチマークでモデルを評価する場合:

import deepchem as dc

# 1. Load benchmark
tasks, datasets, _ = dc.molnet.load_bbbp(
    featurizer='GraphConv',
    splitter='scaffold'
)
train, valid, test = datasets

# 2. Train model
model = dc.models.GCNModel(n_tasks=len(tasks), mode='classification')
model.fit(train, nb_epoch=50)

# 3. Evaluate
metric = dc.metrics.Metric(dc.metrics.roc_auc_score)
test_score = model.evaluate(test, [metric])
print(f"Test ROC-AUC: {test_score}")

Workflow B: Custom Data Prediction

独自の分子データセットで学習する場合:

import deepchem as dc

# 1. Load and featurize data
featurizer = dc.feat.CircularFingerprint(radius=2, size=2048)
loader = dc.data.CSVLoader(
    tasks=['activity'],
    feature_field='smiles',
    featurizer=featurizer
)
dataset = loader.create_dataset('my_molecules.csv')

# 2. Split data (use ScaffoldSplitter for molecules!)
splitter = dc.splits.ScaffoldSplitter()
train, valid, test = splitter.train_valid_test_split(dataset)

# 3. Normalize (optional but recommended)
transformers = [dc.trans.NormalizationTransformer(
    transform_y=True, dataset=train
)]
for transformer in transformers:
    train = transformer.transform(train)
    valid = transformer.transform(valid)
    test = transformer.transform(test)

# 4. Train model
model = dc.models.MultitaskRegressor(
    n_tasks=1,
    n_features=2048,
    layer_sizes=[1000, 500],
    dropouts=0.25
)
model.fit(train, nb_epoch=50)

# 5. Evaluate
metric = dc.metrics.Metric(dc.metrics.r2_score)
test_score = model.evaluate(test, [metric])

Workflow C: Transfer Learning on Small Dataset

事前学習済みモデルを活用する場合:

import deepchem as dc

# 1. Load data (pretrained models often need raw SMILES)
loader = dc.data.CSVLoader(
    tasks=['activity'],
    feature_field='smiles',
    featurizer=dc.feat.DummyFeaturizer()  # Model handles featurization
)
dataset = loader.create_dataset('small_dataset.csv')

# 2. Split data
splitter = dc.splits.ScaffoldSplitter()
train, test = splitter.train_test_split(dataset)

# 3. Load pretrained model
model = dc.models.HuggingFaceModel(
    model='seyonec/ChemBERTa-zinc-base-v1',
    task='classification',
    n_tasks=1,
    learning_rate=2e-5
)

# 4. Fine-tune
model.fit(train, nb_epoch=10)

# 5. Evaluate
predictions = model.predict(test)

分子生成、材料科学、タンパク質解析などを扱う 8 つの詳細なワークフロー例については references/workflows.md を参照してください。

Example Scripts

このスキルには、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）をファインチューニングします。

# 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

Common Patterns and Best Practices

Pattern 1: Always Use Scaffold Splitting for Molecules

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

Pattern 2: Normalize Features and Targets

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)

Pattern 3: Start Simple, Then Scale

1. Random Forest + CircularFingerprint から始めます（高速なベースライン）
2. RF の結果が良好であれば XGBoost/LightGBM を試します
3. サンプル数が 5K を超える場合は深層学習（MultitaskRegressor）に進みます
4. サンプル数が 10K を超える場合は GNN を試します
5. 小規模データセットや新規の骨格には転移学習を使用します

Pattern 4: Handle Imbalanced Data

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

Pattern 5: Avoid Memory Issues

# 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

Common Pitfalls

Issue 1: Data Leakage in Drug Discovery

Problem: ランダム分割を使用すると、類似した分子が学習データとテストデータの両方に含まれてしまいます。 Solution: 分子データセットには必ず ScaffoldSplitter を使用してください。

Issue 2: GNN Underperforming vs Fingerprints

Problem: グラフニューラルネットワークが単純なフィンガープリントより性能が低くなります。 Solutions:

• データセットが十分な大きさであることを確認してください（通常 10K サンプル超）
• 学習エポック数を増やしてください（50〜100）
• 別のアーキテクチャを試してください（GCN の代わりに AttentiveFP や DMPNN）
• 事前学習済みモデル（GROVER）を使用してください

Issue 3: Overfitting on Small Datasets

Problem: モデルが学習データを丸暗記してしまいます。 Solutions:

• より強い正則化を行ってください（ドロップアウトを 0.5 に増やす）
• よりシンプルなモデルを使用してください（深層学習の代わりに Random Forest）
• 転移学習を適用してください（ChemBERTa、GROVER）
• データを追加収集してください

Issue 4: Import Errors

Problem: モジュールが見つからないエラーが発生します。 Solution: 必要な依存関係とともに DeepChem がインストールされていることを確認してください:

pip install deepchem
# For PyTorch models
pip install deepchem[torch]
# For all features
pip install deepchem[all]

Reference Documentation

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

references/api_reference.md

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

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

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

references/workflows.md

エンドツーエンドの詳細なワークフロー 8 種:

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

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

インストールに関する注意事項

基本的なインストール:

pip install deepchem

PyTorch モデル（GCN、GAT など）向け:

pip install deepchem[torch]

すべての機能を利用する場合:

pip install deepchem[all]

インポートエラーが発生した場合は、特定の依存関係が必要になることがあります。詳細なインストール手順については、DeepChem のドキュメントをご確認ください。

追加リソース

• 公式ドキュメント: 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"