molfeat

Molfeat - 分子特征化中心

概述

Molfeat 是一个全面的 Python 分子特征化库，整合了 100 多种预训练嵌入和手工设计的特征化器。将化学结构（SMILES 字符串或 RDKit 分子）转换为数值表示，用于 QSAR 建模、虚拟筛选、相似性搜索和深度学习应用等机器学习任务。它支持快速并行处理、兼容 scikit-learn 的转换器以及内置缓存。

何时使用此技能

在以下场景中使用此技能：

• 分子机器学习：构建 QSAR/QSPR 模型、预测属性
• 虚拟筛选：根据生物活性对化合物库进行排序
• 相似性搜索：查找结构相似的分子
• 化学空间分析：聚类、可视化、降维
• 深度学习：使用分子数据训练神经网络
• 特征化流水线：将 SMILES 转换为可用于机器学习的表示
• 化学信息学：任何需要提取分子特征的任务

安装

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 将特征化组织为三个层级的类：

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

用于深度学习

基于 Transformer 的嵌入：

# 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. 使用并行化：设置 n_jobs=-1 以利用所有 CPU 核心
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
)

大型数据集的内存问题

对于超过 100K 个分子的数据集，请分块处理或使用流式处理方法。

预训练模型依赖项

某些模型需要额外的软件包。安装特定的扩展项：

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