alterlab-deepchem

DeepChem

概要

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

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

次のような場合にこのスキルを使用します。

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

該当しない場面

場面	代わりに使用
PyTorch でカスタム GNN アーキテクチャ（独自のレイヤー／メッセージパッシング）を設計する	alterlab-torch-geometric（TorchDrug のタスク抽象化を使う場合は alterlab-torchdrug）
モデル構築は行わず、標準化済みの ADMET／DTI ベンチマークデータセットと公式分割のみを取得する	alterlab-pytdc
独自モデル用に分子を特徴量行列または事前学習済み埋め込みに変換するだけの場合	alterlab-molfeat
既存の数値特徴量テーブルに対して従来型の ML（パイプライン、CV、チューニング）を行う	alterlab-scikit-learn

主な機能

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、GroverModel（MoLFormer：nightly のみ）	モデル固有
結晶構造	材料特性	CGCNNModel、MEGNetModel	構造ベース
タンパク質配列	タンパク質特性	ProtBERT（nightly ビルドのみ）	配列ベース

例：従来型 ML

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 ベンチマーク

標準化された訓練／検証／テスト分割を備えた、厳選された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. 転移学習

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

# ChemBERTa (RoBERTa pretrained on SMILES) — use DeepChem's Chemberta wrapper
model = dc.models.Chemberta(
    task='classification',
    tokenizer_path='seyonec/PubChem10M_SMILES_BPE_60k',
    n_tasks=1,
    learning_rate=2e-5  # passed via **kwargs to TorchModel
)
model.fit(train, nb_epoch=10)

# GROVER: DeepChem's GroverModel is NOT a one-line pretrained loader. task is
# 'pretraining' | 'finetuning', mode is 'classification' | 'regression', and it needs
# node/edge feature dims, atom/bond vocabularies built from your data, and inputs
# featurized with dc.feat.GroverFeaturizer(features_generator=dc.feat.CircularFingerprint()).
# No pretrained GROVER weights are downloaded — pretrain (task='pretraining') or restore
# your own checkpoint. Full recipe: the GroverModel class docstring.
from deepchem.feat.vocabulary_builders import (GroverAtomVocabularyBuilder,
                                               GroverBondVocabularyBuilder)
av, bv = GroverAtomVocabularyBuilder(), GroverBondVocabularyBuilder()
av.build(smiles_dataset); bv.build(smiles_dataset)   # dataset built with DummyFeaturizer
model = dc.models.GroverModel(node_fdim=151, edge_fdim=165, hidden_size=128,
                              atom_vocab=av, bond_vocab=bv, features_dim=2048,
                              functional_group_size=85, task='finetuning',
                              mode='regression', n_tasks=1, model_dir='grover_ft')
model.fit(grover_train, nb_epoch=20)   # grover_train featurized with GroverFeaturizer

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

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

ガイド付きの転移学習ワークフローには、scripts/transfer_learning.pyスクリプトを使用してください。

7. モデル評価

# 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.rms_score, name='RMSE')   # there is no root_mean_squared_error
]

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

8. 予測の実行

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

# Pass the training transformers to predict() to undo y-normalization
# so predictions come back in the original units. (Don't .transform()
# the X-only dataset — those transformers act on y, not the features.)
predictions = model.predict(new_dataset, transformers=transformers)

典型的なワークフロー

すぐに実行できるエンドツーエンドのレシピを3つ用意しています。

• ワークフロー A — ベンチマーク評価のクイック実行：MoleculeNetベンチマークを読み込み、GNNを訓練してスコアを算出します。
• ワークフロー B — カスタムデータの予測：CSVを特徴量化し、骨格に基づいて分割して正規化した後、訓練して評価します。
• ワークフロー C — 小規模データセットでの転移学習：生のSMILESを使って事前学習済みモデルをファインチューニングします。

A／B／Cの実行可能なコード全体については、references/end_to_end_recipes.mdを参照してください。さらに詳しい8つのワークフロー（分子生成、材料科学、タンパク質解析、カスタムモデルの統合、ハイパーパラメーター探索）については、references/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をファインチューニングします。（--model groverを指定すると、設定方法のガイダンスが表示されます。GROVERには、上記の手順に示す手動での語彙／特徴量化器のレシピが必要です。）

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

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

一般的なパターン、ベストプラクティス、落とし穴

基本的な習慣として、データリークを防ぐために分子データは必ず骨格に基づいて分割し、特徴量と目的変数を正規化してください。また、深層ネットワークやGNNに進む前に、Random ForestとCircularFingerprintのようなシンプルな手法から始めてください。不均衡データにはBalancingTransformerまたは均衡化された指標を使用し、メモリの問題を避けるために小さめのバッチサイズでDiskDatasetを使用してください。データリーク、フィンガープリントより性能が低いGNN、小規模データセットでの過学習、インポートエラーといった繰り返し発生する問題には、それぞれ具体的な解決策があります。

コード付きの完全なパターンレシピと、落とし穴と解決策の一覧については、references/best_practices.mdを参照してください。

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

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

references/api_reference.md

以下を含む完全なAPIドキュメントです。

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

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

references/workflows.md

エンドツーエンドの詳しいワークフローを8つ紹介しています。

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

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

references/end_to_end_recipes.md

ベンチマーク評価、カスタムデータの予測、転移学習の、すぐに使えるエンドツーエンドのレシピを3つ紹介します。いずれも実行可能なコードがすべて含まれています。

参照するタイミング：完全なパイプラインの出発点として、レシピのいずれかを利用してください。

references/best_practices.md

ベストプラクティスのパターン（データ分割、正規化、モデルの段階的な改善、クラスのバランス調整、メモリ）と、問題点から対処法を探せるトラブルシューティング集を紹介します。

参照するタイミング：性能が低いときのデバッグや、モデリング戦略の選択に役立ててください。

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

DeepChem 専用の仮想環境を用意してください。DeepChem のバージョン固定は、現在の科学技術系パッケージスタックと競合します。

# Stable release 2.8.0 (Apr 2024; latest stable as of 2026-09) supports Python 3.7-3.11
uv venv --python 3.11 && uv pip install deepchem

# PyTorch-backed models (GCN, GAT, AttentiveFP, Chemberta, GroverModel, ...)
uv pip install "deepchem[torch]"       # also: "deepchem[tensorflow]", "deepchem[jax]" — there is no [all] extra

# Python 3.12 or newer model classes (MoLFormer, ProtBERT): nightly pre-releases
uv pip install --pre "deepchem[torch]" # 2.8.1.devYYYYMMDD builds; Python <= 3.12

ナイトリービルドでは numpy<2 が固定されており、[torch] を指定すると torch==2.2.1 と dgl<2.2.1 も固定されるため、numpy 2.x や現行の PyTorch と同じ環境では使用できません。Hugging Face のラッパー（Chemberta、MoLFormer、ProtBERT）には transformers も必要ですが、追加インストールには含まれていません。

その他のリソース

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

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