molfeat

Molfeat - 分子特徴量化ハブ

概要

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

バージョンに関する注記： 例は molfeat 0.11.0（PyPI安定版、2025年5月）を対象としています。Python 3.9～3.10 が必要です（requires-python は3.11未満に上限設定されています）。datamol ≥0.8.0 と PyTorch ≥1.13 に依存します。0.8.7以降は、rawの rdkit.Chem.Mol よりdatamolの Mol オブジェクトを優先してください。0.10.1以降、フィンガープリント計算器は内部でRDKitの rdFingerprintGenerator APIを使用します。0.11.0以降、事前学習済みモデルはメモリに読み込まれ、ベースモデルは自動的にPyTorchの評価モードに設定されます。

このスキルを使う場面

次の作業を行う場合に、このスキルを使用してください：

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

インストール

Python 3.9または3.10の環境を使用してください（molfeat 0.11.0時点では、3.11以降にはインストールできません）：

uv pip install "molfeat==0.11.0"

# With all pip-installable optional dependencies
uv pip install "molfeat[all]==0.11.0"

オプションの依存関係エクストラ（PyPI）：

• molfeat[dgl] — GNNモデル（GINのバリアント）。上流では dgl<=2.0 を推奨しています（新しいDGLではgraphboltの問題が発生するため）
• molfeat[graphormer] — Graphormerモデル
• molfeat[transformer] — ChemBERTa、ChemGPT、MolT5
• molfeat[fcd] — FCD記述子
• molfeat[pyg] — PyTorch Geometricの特徴量化器
• molfeat[viz] — NGLViewの可視化ウィジェット

外部の特徴量化器： MAP4はmolfeatのエクストラに含まれていません。reymond-group/map4から別途インストールしてください。一部の大容量依存関係（DGL、dgllife、graphormer-pretrained）はconda-forge経由でのインストールが簡単です。詳しくはオプションの依存関係をご覧ください。

主な概念

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

Featurizer の選択と一般的なワークフロー

タスクに応じた Featurizer の選択 — 従来型 ML（RF、SVM、XGBoost）、深層学習、類似性検索、ファーマコフォアベースの手法 — と、QSAR モデル構築、バーチャルスクリーニング、類似性検索、scikit-learn パイプラインとの統合、複数の Featurizer の比較に関する具体的なワークフローは、 references/choosing_a_featurizer.md に記載されています。

Featurizer の全リストは references/available_featurizers.md に記載されています。その他の例は references/examples.md を参照してください。

利用可能な Featurizer の確認

ModelStore を使って、利用可能なすべての Featurizer を確認できます。

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)

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

import numpy as np

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)

高コストな埋め込みのキャッシュ

可能な場合は、molfeat に組み込まれている事前学習済みモデルのキャッシュを優先してください。カスタム埋め込みをキャッシュする場合は、pickle の代わりに NumPy 配列を使用してください（信頼できないファイルを読み込む際に、pickle は任意のコードを実行する可能性があります）。

import numpy as np
from pathlib import Path

cache_file = Path("embeddings_cache.npz")  # fixed path under your project
transformer = PretrainedMolTransformer("ChemBERTa-77M-MLM", n_jobs=-1)

if cache_file.exists():
    embeddings = np.load(cache_file)["embeddings"]
else:
    embeddings = transformer(smiles_list)
    np.savez(cache_file, embeddings=embeddings)

パフォーマンスのヒント

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

よく使われる Featurizer のリファレンス

頻繁に使用される Featurizer のクイックリファレンス：

Featurizer	種類	次元数	速度	用途
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 種類以上のすべての Featurizer の包括的なカタログです。

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

読み込むタイミング： 特定のタスクに最適な Featurizer を選択する場合、利用可能な選択肢を調べる場合、または Featurizer の特性を理解する場合に参照してください。

検索のヒント： grep を使って、特定の Featurizer の種類を検索できます。

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
)

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

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

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

一部のモデルでは追加のパッケージが必要です。再現性を確保するため、バージョンを固定して必要な追加パッケージをインストールしてください：

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

再現性

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

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

関連スキル

• datamol：datamol Python ライブラリ（import datamol as dm）を通じて RDKit をラップし、分子ケモインフォマティクスを実行します。ネイティブの rdkit.Chem.Mol オブジェクトを返します…
• rdkit：RDKit（Python）を使用して SMILES、MOL/SDF、InChI を読み書きし、記述子（MW、LogP、TPSA）を計算し、Morgan/…を生成する方法を案内します。
• medchem：RDKit と datamol を基盤に、Python の medchem ライブラリ（datamol-io、v2.0.5）を使用して低分子ライブラリをフィルタリングし、トリアージします。