alterlab-molfeat

Molfeat - 分子特徴量化ハブ

概要

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

このスキルを使う場面

次の作業では、このスキルを使用してください。

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

対象外

シナリオ	代わりに使用
組み込みのローダーと GNN を使って MoleculeNet ベンチマークでモデルのトレーニング／評価をエンドツーエンドで行う	alterlab-deepchem
スキャフォールド分割／コールド分割を備えたラベル付きベンチマークデータセットの入手	alterlab-pytdc
低レベルのフィンガープリントまたは記述子のプリミティブ、カスタムサニタイズ、SMARTS	alterlab-rdkit
特徴量化前の分子テーブルの標準化とクリーニング	alterlab-datamol

インストール

uv pip install molfeat            # molfeat 1.0.0 (current as of 2026-09); Python >= 3.11, pulls torch + datamol

# Optional extras (molfeat 1.x)
uv pip install "molfeat[transformer]"   # Hugging Face models: ChemBERTa, ChemGPT, MolT5, ...
uv pip install "molfeat[mordred]"       # Mordred descriptors (mordredcommunity)
uv pip install "molfeat[fcd]"           # FCD / ChemNet embeddings
uv pip install "molfeat[pyg]"           # PyTorch Geometric (used by Mol-JEPA)
uv pip install "molfeat[all]"

molfeat 1.0 の破壊的変更。 DGL ベースの事前学習済み GNN（gin_supervised_*、jtvae_zinc_no_kl）、Graphormer、タンパク質特徴量計算器は、dgl および graphormer の extras とともに削除されました（map4 extra はこれまで存在したことがありません）。これらのモデルストア項目を読み込もうとすると失敗します。新しい基盤モデルの特徴量計算器は CheMeleonTransformer（2,048 次元、Zenodo から重みを取得し、チェックサムを検証）と MolJEPATransformer（CC BY-NC 4.0。trust_remote_code=True および accept_noncommercial_license=True が必要）です。従来の GIN／Graphormer 埋め込みを再現する必要がある場合は、別の環境で molfeat<1（0.11.x は Python ≤ 3.10 が必要）を固定してください。MAP4 には https://github.com/reymond-group/map4 の map4 パッケージが必要です（PyPI では入手できません）。

基本概念

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 を自動的に利用）

例：

import numpy as np
from molfeat.trans import MoleculeTransformer
from molfeat.calc import FPCalculator

transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1, dtype=np.float32)
features = transformer(smiles_list)  # (n_mols, 2048) array; without dtype you get a list of arrays

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

バッチ推論とキャッシュ機能を備えた、ディープラーニングモデル向けの専用トランスフォーマーです。

事前学習済みトランスフォーマーを使う場面：

• 最先端の分子埋め込み
• 大規模な化学データセットを使った転移学習
• ディープラーニング向けの特徴量抽出

例（PretrainedMolTransformer は抽象基底クラスです。具象サブクラスをインスタンス化してください）：

import numpy as np
from molfeat.trans.pretrained import PretrainedHFTransformer

transformer = PretrainedHFTransformer(kind="ChemBERTa-77M-MLM", notation="smiles", dtype=np.float32)
embeddings = transformer(smiles_list)  # (n_mols, 384) mean-pooled embeddings

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

基本的な特徴量化

import numpy as np
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 (dtype makes the output a single array)
calc = FPCalculator("ecfp", radius=3)
transformer = MoleculeTransformer(calc, n_jobs=-1, dtype=np.float32)

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

エラーを適切に処理する

# ignore_errors is an argument of the CALL, not the constructor
# (a constructor kwarg is silently swallowed and the call still raises)
transformer = MoleculeTransformer(calc, n_jobs=-1, dtype=np.float32, verbose=True)

features, valid_ids = transformer(smiles_with_errors, ignore_errors=True)
# features: rows for the molecules that featurized; valid_ids: their input positions
# transformer.transform(smiles_with_errors, ignore_errors=True) instead keeps None placeholders

適切な特徴量計算器の選び方

従来の機械学習（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 (needs the map4 package from GitHub)
FPCalculator("map4")

解釈可能なモデル向け：

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

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

複数の特徴量計算器を組み合わせる（FeatConcat が受け付けるのはフィンガープリント名または FPVecTransformer オブジェクトであり、FPCalculator ではありません）：

from molfeat.trans import FeatConcat

concat = FeatConcat(
    ["maccs", "ecfp"],                    # 167 + 2048 dimensions
    params={"ecfp": {"length": 2048}},    # FPVecTransformer's ecfp default length is 2000
    dtype=np.float32,
)
X = concat(smiles)                        # (n_mols, 2215); concat.length == 2215

深層学習向け

Transformer ベースの埋め込み：

# ChemBERTa - Pre-trained on 77M PubChem compounds
PretrainedHFTransformer(kind="ChemBERTa-77M-MLM", notation="smiles")

# ChemGPT - Autoregressive language model (SELFIES input)
PretrainedHFTransformer(kind="ChemGPT-1.2B", notation="selfies")

基盤モデルの埋め込み（molfeat 1.x）：

from molfeat.trans.pretrained import CheMeleonTransformer, MolJEPATransformer

CheMeleonTransformer()                    # 2,048-d descriptor-foundation-model fingerprints
MolJEPATransformer(trust_remote_code=True,
                   accept_noncommercial_license=True)   # CC BY-NC 4.0 weights

レガシーの DGL GIN（gin_supervised_*）および Graphormer モデルは、molfeat 1.0 で削除されました。

類似性検索向け

# 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 (189-d in 2D)
from molfeat.calc import CATS
CATS()                      # CATS(use_3d_distances=True) for the 3D variant

# Gobbi - Explicit 2D pharmacophore features
from molfeat.calc import Pharmacophore2D
Pharmacophore2D(factory="gobbi")

一般的なワークフローと高度なパターン

エンドツーエンドのレシピ（QSAR モデルの構築、バーチャルスクリーニング、類似性検索、scikit-learn パイプラインとの統合、フィーチャライザーの比較）、ModelStore の検索、高度な使い方（カスタム前処理、チャンク単位のバッチ処理、計算コストの高い埋め込みのキャッシュ）は、このドキュメントを簡潔に保つために別の場所へ移動しました。

そのままコピーして使えるワークフローおよび高度なパターンのレシピ全体については、references/workflows_and_patterns.md を参照してください。その他の実行可能な例（PyTorch のトレーニング、グリッドサーチ、3D コンフォーマー）は、references/examples.md にあります。

パフォーマンスのヒント

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

一般的なフィーチャライザーのリファレンス

よく使用されるフィーチャライザーのクイックリファレンス：

フィーチャライザー	種類	次元数	速度	用途
ecfp	フィンガープリント	2048	高速	汎用
maccs	フィンガープリント	167	非常に高速	スキャフォールドの類似性
desc2D	記述子	223	高速	解釈可能なモデル
mordred	記述子	1800+	中速	包括的な特徴量
map4	フィンガープリント	2048	高速	大規模スクリーニング
ChemBERTa-77M-MLM	深層学習	384	低速*	転移学習
CheMeleonTransformer	基盤モデル	2048	低速*	記述子で事前学習した埋め込み

*初回の実行は低速ですが、以降の実行ではキャッシュの効果が得られます

リソース

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

references/api_reference.md

以下を網羅した、完全な API ドキュメントです。

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

読み込むタイミング： 特定の計算器を実装する場合、Transformer のパラメーターを理解する場合、または scikit-learn/PyTorch と統合する場合に参照してください。

references/available_featurizers.md

カテゴリ別に整理された、100 種類以上のすべてのフィーチャライザーを網羅するカタログです。

• Transformer ベースの言語モデル（ChemBERTa、ChemGPT）
• グラフニューラルネットワーク（GIN、Graphormer — レガシー、molfeat 1.0 で削除）
• 分子記述子（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

一般的なシナリオ向けの実用的なコード例です。

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

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

トラブルシューティング

無効な分子

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

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

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

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

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

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

uv pip install "molfeat[transformer]"  # For ChemBERTa/ChemGPT/MolT5
uv pip install "molfeat[pyg]"          # For Mol-JEPA (with the transformer extra)

molfeat 1.x に dgl エクストラはありません。DGL GIN モデルは削除されました。

再現性

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

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

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