molfeat

Molfeat - 分子特徴量化ハブ

概要

Molfeat は、100 を超える事前学習済みエンベディングと手作業で設計された特徴量化器を統合する、分子特徴量化のための包括的な Python ライブラリです。化学構造（SMILES 文字列または RDKit 分子）を、QSAR モデリング、バーチャルスクリーニング、類似性検索、ディープラーニングなどの機械学習タスク向けの数値表現に変換します。高速な並列処理、scikit-learn 互換のトランスフォーマー、組み込みのキャッシュ機能を備えています。

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

このスキルは、以下のような作業で使用します。

• 分子機械学習: QSAR/QSPR モデルの構築、物性予測
• バーチャルスクリーニング: 化合物ライブラリを生物活性に基づいてランク付けする
• 類似性検索: 構造的に類似した分子を見つける
• 化学空間解析: クラスタリング、可視化、次元削減
• ディープラーニング: 分子データを用いたニューラルネットワークの学習
• 特徴量化パイプライン: SMILES を ML に適した表現へ変換する
• ケモインフォマティクス: 分子特徴量の抽出を必要とするあらゆるタスク

インストール

uv pip install molfeat

# With all optional dependencies
uv pip install "molfeat[all]"

特定の特徴量化器向けのオプション依存関係:

• molfeat[dgl] - GNN モデル（GIN 系列）
• molfeat[graphormer] - Graphormer モデル
• molfeat[transformer] - ChemBERTa、ChemGPT、MolT5
• molfeat[fcd] - FCD 記述子
• molfeat[map4] - MAP4 フィンガープリント

基本概念

Molfeat は、特徴量化を 3 つの階層的なクラスに分けて整理しています。

1. 計算器（molfeat.calc）

個々の分子を特徴ベクトルに変換する呼び出し可能なオブジェクトです。RDKit の Chem.Mol オブジェクトまたは SMILES 文字列を受け付けます。

計算器を使用する場面:

• 単一分子の特徴量化
• カスタムの処理ループ
• 直接的な特徴量計算

例:

from molfeat.calc import FPCalculator

calc = FPCalculator("ecfp", radius=3, fpSize=2048)
features = calc("CCO")  # Returns numpy array (2048,)

2. トランスフォーマー（molfeat.trans）

計算器をラップし、並列化によるバッチ処理を行う scikit-learn 互換のトランスフォーマーです。

トランスフォーマーを使用する場面:

• 分子データセットのバッチ特徴量化
• scikit-learn パイプラインとの統合
• 並列処理（CPU を自動的に活用）

例:

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

transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
features = transformer(smiles_list)  # Parallel processing

3. 事前学習済みトランスフォーマー（molfeat.trans.pretrained）

ディープラーニングモデル向けの特化トランスフォーマーで、バッチ推論とキャッシュに対応しています。

事前学習済みトランスフォーマーを使用する場面:

• 最先端の分子エンベディング
• 大規模化学データセットからの転移学習
• ディープラーニングによる特徴抽出

例:

from molfeat.trans.pretrained import PretrainedMolTransformer

transformer = PretrainedMolTransformer("ChemBERTa-77M-MLM", n_jobs=-1)
embeddings = transformer(smiles_list)  # Deep learning embeddings

クイックスタートのワークフロー

基本的な特徴量化

import datamol as dm
from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer

# Load molecular data
smiles = ["CCO", "CC(=O)O", "c1ccccc1", "CC(C)O"]

# Create calculator and transformer
calc = FPCalculator("ecfp", radius=3)
transformer = MoleculeTransformer(calc, n_jobs=-1)

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

設定の保存と読み込み

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

# Reload exact configuration
loaded = MoleculeTransformer.from_state_yaml_file("featurizer_config.yml")

エラーを適切に処理する

# Process dataset with potentially invalid SMILES
transformer = MoleculeTransformer(
    calc,
    n_jobs=-1,
    ignore_errors=True,  # Continue on failures
    verbose=True          # Log error details
)

features = transformer(smiles_with_errors)
# Returns None for failed molecules

適切な特徴量化器の選び方

従来型の機械学習（RF、SVM、XGBoost）向け

まずはフィンガープリントから:

# ECFP - Most popular, general-purpose
FPCalculator("ecfp", radius=3, fpSize=2048)

# MACCS - Fast, good for scaffold hopping
FPCalculator("maccs")

# MAP4 - Efficient for large-scale screening
FPCalculator("map4")

解釈可能なモデル向け:

# RDKit 2D descriptors (200+ named properties)
from molfeat.calc import RDKitDescriptors2D
RDKitDescriptors2D()

# Mordred (1800+ comprehensive descriptors)
from molfeat.calc import MordredDescriptors
MordredDescriptors()

複数の特徴量化器を組み合わせる:

from molfeat.trans import FeatConcat

concat = FeatConcat([
    FPCalculator("maccs"),      # 167 dimensions
    FPCalculator("ecfp")         # 2048 dimensions
])  # Result: 2215-dimensional combined features

ディープラーニング向け

トランスフォーマーベースのエンベディング:

# ChemBERTa - Pre-trained on 77M PubChem compounds
PretrainedMolTransformer("ChemBERTa-77M-MLM")

# ChemGPT - Autoregressive language model
PretrainedMolTransformer("ChemGPT-1.2B")

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

# GIN models with different pre-training objectives
PretrainedMolTransformer("gin-supervised-masking")
PretrainedMolTransformer("gin-supervised-infomax")

# Graphormer for quantum chemistry
PretrainedMolTransformer("Graphormer-pcqm4mv2")

類似性検索向け

# ECFP - General purpose, most widely used
FPCalculator("ecfp")

# MACCS - Fast, scaffold-based similarity
FPCalculator("maccs")

# MAP4 - Efficient for large databases
FPCalculator("map4")

# USR/USRCAT - 3D shape similarity
from molfeat.calc import USRDescriptors
USRDescriptors()

ファーマコフォアベースのアプローチ向け

# FCFP - Functional group based
FPCalculator("fcfp")

# CATS - Pharmacophore pair distributions
from molfeat.calc import CATSCalculator
CATSCalculator(mode="2D")

# Gobbi - Explicit pharmacophore features
FPCalculator("gobbi2D")

よくあるワークフロー

QSAR モデルの構築

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

# Featurize molecules
transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
X = transformer(smiles_train)

# Train model
model = RandomForestRegressor(n_estimators=100)
scores = cross_val_score(model, X, y_train, cv=5)
print(f"R² = {scores.mean():.3f}")

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

バーチャルスクリーニングのパイプライン

from sklearn.ensemble import RandomForestClassifier

# Train on known actives/inactives
transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
X_train = transformer(train_smiles)
clf = RandomForestClassifier(n_estimators=500)
clf.fit(X_train, train_labels)

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

# Rank and select top hits
top_indices = predictions.argsort()[::-1][:1000]
top_hits = [screening_library[i] for i in top_indices]

類似性検索

from sklearn.metrics.pairwise import cosine_similarity

# Query molecule
calc = FPCalculator("ecfp")
query_fp = calc(query_smiles).reshape(1, -1)

# Database fingerprints
transformer = MoleculeTransformer(calc, n_jobs=-1)
database_fps = transformer(database_smiles)

# Compute similarity
similarities = cosine_similarity(query_fp, database_fps)[0]
top_similar = similarities.argsort()[-10:][::-1]

scikit-learn パイプラインとの統合

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

# Create end-to-end pipeline
pipeline = Pipeline([
    ('featurizer', MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)),
    ('classifier', RandomForestClassifier(n_estimators=100))
])

# Train and predict directly on SMILES
pipeline.fit(smiles_train, y_train)
predictions = pipeline.predict(smiles_test)

複数の特徴量化器の比較

featurizers = {
    'ECFP': FPCalculator("ecfp"),
    'MACCS': FPCalculator("maccs"),
    'Descriptors': RDKitDescriptors2D(),
    'ChemBERTa': PretrainedMolTransformer("ChemBERTa-77M-MLM")
}

results = {}
for name, feat in featurizers.items():
    transformer = MoleculeTransformer(feat, n_jobs=-1)
    X = transformer(smiles)
    # Evaluate with your ML model
    score = evaluate_model(X, y)
    results[name] = score

利用可能な特徴量化器の探索

ModelStore を使用して、利用可能なすべての特徴量化器を確認します。

from molfeat.store.modelstore import ModelStore

store = ModelStore()

# List all available models
all_models = store.available_models
print(f"Total featurizers: {len(all_models)}")

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

# Get usage information
model_card = store.search(name="ChemBERTa-77M-MLM")[0]
model_card.usage()  # Display usage examples

# Load model
transformer = store.load("ChemBERTa-77M-MLM")

高度な機能

カスタム前処理

class CustomTransformer(MoleculeTransformer):
    def preprocess(self, mol):
        """Custom preprocessing pipeline"""
        if isinstance(mol, str):
            mol = dm.to_mol(mol)
        mol = dm.standardize_mol(mol)
        mol = dm.remove_salts(mol)
        return mol

transformer = CustomTransformer(FPCalculator("ecfp"), n_jobs=-1)

大規模データセットのバッチ処理

def featurize_in_chunks(smiles_list, transformer, chunk_size=10000):
    """Process large datasets in chunks to manage memory"""
    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)
    return np.vstack(all_features)

高コストなエンベディングのキャッシュ

import pickle

cache_file = "embeddings_cache.pkl"
transformer = PretrainedMolTransformer("ChemBERTa-77M-MLM", n_jobs=-1)

try:
    with open(cache_file, "rb") as f:
        embeddings = pickle.load(f)
except FileNotFoundError:
    embeddings = transformer(smiles_list)
    with open(cache_file, "wb") as f:
        pickle.dump(embeddings, f)

パフォーマンスのヒント

1. 並列化を使用する: すべての CPU コアを活用するには n_jobs=-1 を設定します
2. バッチ処理: ループの代わりに、複数の分子をまとめて処理します
3. 適切な特徴量化器を選ぶ: フィンガープリントはディープラーニングモデルより高速です
4. 事前学習済みモデルをキャッシュする: 繰り返し使用する場合は組み込みのキャッシュを活用します
5. float32 を使用する: 精度が許す場合は dtype=np.float32 を設定します
6. 効率的にエラーを処理する: 大規模データセットでは ignore_errors=True を使用します

一般的な特徴量抽出器のリファレンス

よく使われる特徴量抽出器のクイックリファレンス:

特徴量抽出器	種類	次元数	速度	用途
ecfp	フィンガープリント	2048	高速	汎用
maccs	フィンガープリント	167	非常に高速	スキャフォールド類似性
desc2D	記述子	200+	高速	解釈可能なモデル
mordred	記述子	1800+	中速	包括的な特徴量
map4	フィンガープリント	1024	高速	大規模スクリーニング
ChemBERTa-77M-MLM	深層学習	768	低速*	転移学習
gin-supervised-masking	GNN	可変	低速*	グラフベースのモデル

*初回実行は低速ですが、以降の実行はキャッシュの恩恵を受けます

リソース

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

references/api_reference.md

以下を網羅する完全なAPIドキュメント:

• molfeat.calc - すべての計算機クラスとパラメータ
• molfeat.trans - トランスフォーマークラスとメソッド
• molfeat.store - ModelStoreの使い方
• 一般的なパターンと統合の例
• パフォーマンス最適化のヒント

読み込むタイミング: 特定の計算機を実装するとき、トランスフォーマーのパラメータを理解するとき、またはscikit-learn/PyTorchと統合するときに参照してください。

references/available_featurizers.md

カテゴリ別に整理された100種類以上の特徴量抽出器の包括的なカタログ:

• Transformerベースの言語モデル (ChemBERTa, ChemGPT)
• グラフニューラルネットワーク (GIN, Graphormer)
• 分子記述子 (RDKit, Mordred)
• フィンガープリント (ECFP, MACCS, MAP4、その他15種以上)
• ファーマコフォア記述子 (CATS, Gobbi)
• 形状記述子 (USR, ElectroShape)
• スキャフォールドベースの記述子

読み込むタイミング: 特定のタスクに最適な特徴量抽出器を選択するとき、利用可能なオプションを調べるとき、または特徴量抽出器の特性を理解するときに参照してください。

検索のヒント: grepを使用して特定の特徴量抽出器の種類を検索します:

grep -i "chembert" references/available_featurizers.md
grep -i "pharmacophore" references/available_featurizers.md

references/examples.md

一般的なシナリオの実用的なコード例:

• インストールとクイックスタート
• 計算機とトランスフォーマーの例
• 事前学習済みモデルの使用法
• Scikit-learnとPyTorchの統合
• バーチャルスクリーニングのワークフロー
• QSARモデルの構築
• 類似性検索
• トラブルシューティングとベストプラクティス

読み込むタイミング: 特定のワークフローを実装するとき、問題をトラブルシューティングするとき、またはmolfeatのパターンを学ぶときに参照してください。

トラブルシューティング

無効な分子

エラー処理を有効にして、無効なSMILESをスキップします:

transformer = MoleculeTransformer(
    calc,
    ignore_errors=True,
    verbose=True
)

大規模データセットでのメモリの問題

データセットが10万分子を超える場合は、チャンク単位で処理するか、ストリーミング方式を使用してください。

事前学習済みモデルの依存関係

一部のモデルには追加のパッケージが必要です。特定のエクストラをインストールしてください:

uv pip install "molfeat[transformer]"  # For ChemBERTa/ChemGPT
uv pip install "molfeat[dgl]"          # For GIN models

再現性

正確な設定を保存し、バージョンを記録してください:

transformer.to_state_yaml_file("config.yml")
import molfeat
print(f"molfeat version: {molfeat.__version__}")

追加リソース

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