molfeat-molecular-featurization

Molfeat — 分子特徴量化ハブ

概要

Molfeat は、100 種類以上の事前学習済み埋め込みと手作業で設計された特徴量化器を、scikit-learn 互換の API の下で統合する、分子特徴量化のための包括的な Python ライブラリです。SMILES 文字列を数値表現（フィンガープリント、記述子、深層学習による埋め込み）に変換し、QSAR モデリング、バーチャルスクリーニング、類似性検索、化学空間解析に利用できます。

使用する場面

• 分子特徴量を入力とする QSAR/QSPR モデルの構築
• バーチャルスクリーニング — 予測活性に基づく化合物ライブラリのランキング
• 分子データベースを対象とした類似性検索
• 化学空間解析 — クラスタリング、可視化、次元削減
• 事前学習済み埋め込み（ChemBERTa、GIN）を用いた分子の深層学習
• scikit-learn または PyTorch と統合する特徴量化パイプライン
• ベンチマークのための複数の分子表現の比較
• 分子の操作やフィルタリングには代わりに datamol を、部分構造に基づく分子操作には rdkit-cheminformatics を使用してください

前提条件

uv pip install molfeat

# Optional extras for specific featurizer types
uv pip install "molfeat[transformer]"   # ChemBERTa, ChemGPT, MolT5
uv pip install "molfeat[dgl]"           # GIN graph neural networks
uv pip install "molfeat[graphormer]"    # Graphormer models
uv pip install "molfeat[fcd]"           # FCD descriptors
uv pip install "molfeat[map4]"          # MAP4 fingerprints
uv pip install "molfeat[all]"           # All dependencies

クイックスタート

from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer

smiles = ["CCO", "CC(=O)O", "c1ccccc1", "CC(C)O"]

# Create fingerprint calculator + transformer
calc = FPCalculator("ecfp", radius=3, fpSize=2048)
transformer = MoleculeTransformer(calc, n_jobs=-1)

# Featurize batch in parallel
features = transformer(smiles)
print(f"Shape: {features.shape}")  # (4, 2048)

# Save configuration for reproducibility
transformer.to_state_yaml_file("featurizer_config.yml")

主な概念

アーキテクチャ：Calculator → Transformer → Store

Molfeat は特徴量化を 3 つのレイヤーに分けて構成します。

レイヤー	クラス	用途	使用する場面
Calculator	molfeat.calc.*	単一分子 → 特徴量ベクトル	カスタムループ、単一分子
Transformer	molfeat.trans.MoleculeTransformer	並列化によるバッチ処理	データセット、scikit-learn パイプライン
Store	molfeat.store.ModelStore	事前学習済みモデルの検索と読み込み	利用可能な特徴量化器の検索

Calculator は呼び出し可能です。calc("CCO") は numpy 配列を返します。Transformer はバッチ処理用に Calculator をラップします。transformer(smiles_list) は 2 次元配列を返します。事前学習済み Transformer（PretrainedMolTransformer）は、バッチ処理による GPU 推論とキャッシュに対応します。

特徴量化器の選択ガイド

タスク	推奨	次元数	速度
一般的な QSAR	ecfp（radius=3）	2048	高速
骨格類似性	maccs	167	非常に高速
大規模スクリーニング	map4	1024	高速
解釈可能なモデル	desc2D（RDKitDescriptors2D）	200+	高速
包括的な記述子	mordred	1800+	中速
転移学習	ChemBERTa-77M-MLM	768	低速*
グラフベースの DL	gin-supervised-masking	可変	低速*
ファーマコフォア	fcfp または cats2D	2048 / 21	高速
3D 形状	usr / usrcat	12 / 60	高速

*初回の実行は低速ですが、以降の実行ではキャッシュが使用されます。

状態の永続化

再現性を確保するため、特徴量化器の設定をそのまま保存して再読み込みできます。

# Save
transformer.to_state_yaml_file("config.yml")
transformer.to_state_json_file("config.json")

# Reload
loaded = MoleculeTransformer.from_state_yaml_file("config.yml")

コア API

1. フィンガープリント計算器

from molfeat.calc import FPCalculator

# ECFP — most popular, general-purpose
ecfp = FPCalculator("ecfp", radius=3, fpSize=2048)
fp = ecfp("CCO")
print(f"ECFP shape: {fp.shape}")  # (2048,)

# MACCS keys — 167-bit structural keys, fast scaffold similarity
maccs = FPCalculator("maccs")
fp = maccs("c1ccccc1")
print(f"MACCS shape: {fp.shape}")  # (167,)

# Count-based fingerprints (non-binary)
ecfp_count = FPCalculator("ecfp-count", radius=3, fpSize=2048)

# MAP4 — MinHashed atom-pair, efficient for large databases
map4 = FPCalculator("map4")
print(f"MAP4 shape: {map4('CCO').shape}")  # (1024,)

利用可能なフィンガープリントの種類：ecfp、fcfp、maccs、rdkit、avalon、pattern、layered、atompair、topological、map4、secfp、erg、estate（および -count サフィックス付きのカウント版）。

2. 記述子計算器

from molfeat.calc import RDKitDescriptors2D, MordredDescriptors

# RDKit 2D — 200+ named properties (MW, logP, TPSA, etc.)
desc2d = RDKitDescriptors2D()
descriptors = desc2d("CCO")
print(f"2D descriptors: {len(descriptors)}")  # 200+
print(f"Feature names: {desc2d.columns[:5]}")

# Mordred — 1800+ comprehensive descriptors
mordred = MordredDescriptors()
descriptors = mordred("c1ccccc1O")
print(f"Mordred descriptors: {len(descriptors)}")  # 1800+

3. ファーマコフォアおよび形状計算器

from molfeat.calc import CATSCalculator, USRDescriptors

# CATS — pharmacophore point pair distributions
cats = CATSCalculator(mode="2D", scale="raw")
descriptors = cats("CC(C)Cc1ccc(C)cc1C")
print(f"CATS shape: {descriptors.shape}")  # (21,)

# USR — ultrafast shape recognition
usr = USRDescriptors()
shape = usr("CC(=O)Oc1ccccc1C(=O)O")
print(f"USR shape: {shape.shape}")  # (12,)

4. Transformer によるバッチ処理

from molfeat.trans import MoleculeTransformer, FeatConcat
from molfeat.calc import FPCalculator

smiles = ["CCO", "CC(=O)O", "c1ccccc1", "CC(C)O", "CCCC"]

# Parallel batch processing
transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
features = transformer(smiles)
print(f"Batch shape: {features.shape}")  # (5, 2048)

# Concatenate multiple featurizers
concat = FeatConcat([
    FPCalculator("maccs"),      # 167 dims
    FPCalculator("ecfp")        # 2048 dims
])
combo_transformer = MoleculeTransformer(concat, n_jobs=-1)
combo_features = combo_transformer(smiles)
print(f"Combined shape: {combo_features.shape}")  # (5, 2215)

# Error-tolerant processing
safe_transformer = MoleculeTransformer(
    FPCalculator("ecfp"), n_jobs=-1,
    ignore_errors=True, verbose=True
)
features = safe_transformer(["CCO", "invalid", "c1ccccc1"])
# Returns None for failed molecules

5. 事前学習済みモデルの埋め込み

from molfeat.trans.pretrained import PretrainedMolTransformer

# ChemBERTa — RoBERTa trained on 77M PubChem compounds
chemberta = PretrainedMolTransformer("ChemBERTa-77M-MLM", n_jobs=-1)
embeddings = chemberta(["CCO", "CC(=O)O", "c1ccccc1"])
print(f"ChemBERTa shape: {embeddings.shape}")  # (3, 768)

# GIN — graph neural network pretrained on ChEMBL
gin = PretrainedMolTransformer("gin-supervised-masking", n_jobs=-1)
graph_emb = gin(["CCO", "CC(=O)O"])
print(f"GIN shape: {graph_emb.shape}")

6. ModelStore — 特徴量化器の検索

from molfeat.store.modelstore import ModelStore

store = ModelStore()
print(f"Total available: {len(store.available_models)}")

# Search for specific model
results = store.search(name="ChemBERTa")
for model in results:
    print(f"  {model.name}: {model.description}")

# View usage and load
card = store.search(name="ChemBERTa-77M-MLM")[0]
card.usage()
transformer = store.load("ChemBERTa-77M-MLM")

一般的なワークフロー

ワークフロー 1：QSAR モデルの構築

from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer
from sklearn.ensemble import RandomForestRegressor
from sklearn.model_selection import cross_val_score

# Featurize molecules
transformer = MoleculeTransformer(FPCalculator("ecfp", radius=3), n_jobs=-1)
X = transformer(smiles_train)
print(f"Features shape: {X.shape}")

# Train and evaluate
model = RandomForestRegressor(n_estimators=100)
scores = cross_val_score(model, X, y_train, cv=5, scoring='r2')
print(f"R² = {scores.mean():.3f} ± {scores.std():.3f}")

# Save for deployment
transformer.to_state_yaml_file("production_featurizer.yml")

ワークフロー 2：バーチャルスクリーニングのパイプライン

from sklearn.ensemble import RandomForestClassifier

# Step 1: Featurize known actives/inactives
transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
X_train = transformer(train_smiles)

# Step 2: Train classifier
clf = RandomForestClassifier(n_estimators=500, n_jobs=-1)
clf.fit(X_train, train_labels)

# Step 3: Screen library (e.g., 1M compounds)
X_screen = transformer(screening_smiles)
predictions = clf.predict_proba(X_screen)[:, 1]

# Step 4: Rank and select top hits
top_indices = predictions.argsort()[::-1][:1000]
top_hits = [screening_smiles[i] for i in top_indices]
print(f"Top 1000 hits selected from {len(screening_smiles)} compounds")

ワークフロー 3：特徴量化器のベンチマーク

from molfeat.calc import FPCalculator, RDKitDescriptors2D
from sklearn.metrics import roc_auc_score

featurizers = {
    'ECFP': FPCalculator("ecfp"),
    'MACCS': FPCalculator("maccs"),
    'Descriptors': RDKitDescriptors2D(),
}

for name, calc in featurizers.items():
    transformer = MoleculeTransformer(calc, n_jobs=-1)
    X_train = transformer(smiles_train)
    X_test = transformer(smiles_test)
    clf = RandomForestClassifier(n_estimators=100)
    clf.fit(X_train, y_train)
    auc = roc_auc_score(y_test, clf.predict_proba(X_test)[:, 1])
    print(f"{name}: AUC = {auc:.3f}")

よく使うレシピ

レシピ：Scikit-learn パイプラインとの統合

from sklearn.pipeline import Pipeline
from sklearn.ensemble import RandomForestClassifier

pipeline = Pipeline([
    ('featurizer', MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)),
    ('classifier', RandomForestClassifier(n_estimators=100))
])
pipeline.fit(smiles_train, y_train)
predictions = pipeline.predict(smiles_test)

レシピ：類似性検索

from sklearn.metrics.pairwise import cosine_similarity

calc = FPCalculator("ecfp")
query_fp = calc("CC(=O)Oc1ccccc1C(=O)O").reshape(1, -1)  # Aspirin

transformer = MoleculeTransformer(calc, n_jobs=-1)
db_fps = transformer(database_smiles)

similarities = cosine_similarity(query_fp, db_fps)[0]
top_k = similarities.argsort()[-10:][::-1]
for i in top_k:
    print(f"  {database_smiles[i]}: {similarities[i]:.3f}")

レシピ：大規模データセットのチャンク処理

import numpy as np

def featurize_chunks(smiles_list, transformer, chunk_size=10000):
    all_features = []
    for i in range(0, len(smiles_list), chunk_size):
        chunk = smiles_list[i:i+chunk_size]
        features = transformer(chunk)
        all_features.append(features)
        print(f"Processed {min(i+chunk_size, len(smiles_list))}/{len(smiles_list)}")
    return np.vstack(all_features)

主要なパラメーター

パラメーター	モジュール	デフォルト	説明
method	FPCalculator	—	フィンガープリントの種類：ecfp、maccs、map4 など
radius	FPCalculator	3	円形フィンガープリントの半径
fpSize	FPCalculator	2048	フィンガープリントのビット長
counting	FPCalculator	False	バイナリではなくカウントベクトルを使用します
n_jobs	MoleculeTransformer	1	並列ワーカー数（-1 = すべてのコア）
ignore_errors	MoleculeTransformer	False	無効な分子をスキップします（None を返します）
verbose	MoleculeTransformer	False	処理の詳細をログに記録します
dtype	MoleculeTransformer	float64	出力の型（メモリ節約には float32）
mode	CATSCalculator	"2D"	距離の計算モード
scale	CATSCalculator	"raw"	スケーリング：raw、num、count

ベストプラクティス

• すべての CPU コアを使って並列処理するには n_jobs=-1 を使用します — バッチ特徴量化を大幅に高速化できます
• 最初のベースラインには ECFP を使用します — ディープラーニングを試す前に使う、汎用性に優れたフィンガープリントです
• 大規模なデータセットには ignore_errors=True を使用します — 無効な SMILES がパイプラインを停止させません
• 再現性を確保するため、to_state_yaml_file() で設定を保存します — 後から同一の特徴量化器を再作成できます
• メモリが重要な場合は float32 を使用します：MoleculeTransformer(calc, dtype=np.float32)
• 事前学習済みの埋め込みをキャッシュします — ChemBERTa/GIN の初回推論は遅いですが、以降の実行ではキャッシュが使われます
• 10 万件を超えるデータセットはチャンクに分けて処理します — メモリ不足を防ぎます（レシピを参照）
• フィンガープリントを FeatConcat で結合します — 相補的な分子情報を捉えられます

トラブルシューティング

問題	原因	解決策
ValueError: unsupported featurizer	不明なメソッド名	FPCalculator でサポートされている種類を確認するか、ModelStore.search() を使用します
事前学習済みモデルの ImportError	オプションの依存関係が不足しています	エクストラをインストールします：pip install "molfeat[transformer]" または "molfeat[dgl]"
出力配列に None が含まれています	ignore_errors=True のときの無効な SMILES	結果をフィルタリングします：[f for f in features if f is not None]
大規模なデータセットでメモリエラーが発生します	一度に処理する分子が多すぎます	1 万～5 万件のチャンクに分けて処理します（レシピを参照）
事前学習済みモデルの推論が遅いです	初回実行時にモデルの重みをダウンロードします	正常な動作です。以降の実行ではキャッシュが使われます
パイプラインで形状が一致しません	有効な分子と無効な分子が混在しています	ignore_errors=True を設定し、ML モデルの前に None をフィルタリングします
再現性に問題があります	molfeat のバージョンが異なります	バージョンを固定し、設定を保存します：transformer.to_state_yaml_file()

関連スキル

• datamol-cheminformatics — 高水準の分子操作（標準化、I/O、コンフォーマー）
• rdkit-cheminformatics — 低水準のケモインフォマティクス（部分構造、反応、3D）
• scikit-learn — molfeat の特徴量を利用する ML モデル

参考資料

• 公式ドキュメント：https://molfeat-docs.datamol.io/
• GitHub リポジトリ：https://github.com/datamol-io/molfeat
• PyPI パッケージ：https://pypi.org/project/molfeat/
• チュートリアル：https://portal.valencelabs.com/datamol/post/types-of-featurizers-b1e8HHrbFMkbun6

同梱リソース

メインの SKILL.md ＋ 2 つのリファレンスファイル。元の合計：1,273 行（SKILL.md 510 行 ＋ api_reference.md 429 行 ＋ available_featurizers.md 334 行）。スクリプト：なし。例：724 行（examples.md）。

references/available_featurizers.md：カテゴリ別に整理した、100 種類以上のすべてのフィージャライザーの完全なカタログです。トランスフォーマーモデル、GNN、記述子、フィンガープリント、ファーマコフォア、形状、スキャフォールド、グラフフィージャライザーを含みます。各カテゴリの次元、依存関係、選択ガイドを掲載しています。検索用途に特化したコンテンツはリファレンスとして保持されています。

references/api_reference.md：molfeat.calc、molfeat.trans、molfeat.store モジュールの詳細な API リファレンスです。SerializableCalculator 基底クラス、パラメーターを含むすべての計算クラス、MoleculeTransformer のメソッド、PretrainedMolTransformer、FeatConcat、ModelStore／ModelCard API、データ型の制御、PyTorch との連携パターンを扱います。

元ファイルの扱い：

• SKILL.md（510 行）→ コア API モジュール 1～6、主要な概念（アーキテクチャ、選択ガイド）、クイックスタート、ワークフロー 1～3。「適切なフィージャライザーの選び方」→「主要な概念」の選択ガイド表。「高度な機能」（カスタム前処理、バッチ処理、キャッシュ）→レシピ ＋ ベストプラクティス。「一般的なフィージャライザーのリファレンス」表 →「主要な概念」の選択ガイド。用途別の扱い：QSAR モデリング → ワークフロー 1、バーチャルスクリーニング → ワークフロー 2、類似性検索 → レシピ、化学空間 →「使用する場面」の箇条書き、scikit-learn パイプライン → レシピ、フィージャライザーの比較 → ワークフロー 3
• references/api_reference.md（429 行）→ 新しい references/api_reference.md に移行。コアパターン（FPCalculator、MoleculeTransformer、基本的な ModelStore）を SKILL.md のコア API モジュール 1～6 に移動。詳細なクラスメソッド、SerializableCalculator 基底クラス、PrecomputedMolTransformer、PyTorch との連携はリファレンスに保持
• references/available_featurizers.md（334 行）→ 新しい references/available_featurizers.md に移行。概要 →「主要な概念」の選択ガイド表。カテゴリ別の完全なカタログはリファレンスに保持
• references/examples.md（724 行）→ 内容をすべて本文に統合：インストール → 前提条件、計算クラスの例 → コア API 1～3、トランスフォーマーの例 → コア API 4、事前学習済みモデルの例 → コア API 5、ML との連携 → ワークフロー 1～3 ＋ レシピ、高度なパターン（カスタム前処理、キャッシュ、チャンク処理）→ レシピ ＋ ベストプラクティス、トラブルシューティング → トラブルシューティング表。内容はすべて SKILL.md の各セクションに取り込まれているため、独立したリファレンスファイルは不要

保持率：約 490 行（SKILL.md）＋ 約 170 行（available_featurizers）＋ 約 190 行（api_reference）＝ 約 850／元の 1,273 行（examples.md は統合済みとして除外）＝ 約 67％。examples.md を分母に含める場合：約 850／1,997 ＝ 約 43％。