molfeat

Molfeat - 分子特征化中心

概览

Molfeat 是一个全面的 Python 分子特征化库，整合了 100 多种预训练嵌入和手工设计的特征计算器。将化学结构（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 起，优先使用 datamol Mol 对象，而非原始的 rdkit.Chem.Mol。从 0.10.1 起，指纹计算器在内部使用 RDKit 的 rdFingerprintGenerator API。从 0.11.0 起，预训练模型会载入内存，基础模型也会自动设为 PyTorch 评估模式。

何时使用此技能

在以下情形中使用此技能：

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

安装

使用 Python 3.9 或 3.10 环境（截至 0.11.0，molfeat 无法安装在 Python 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 可视化小组件

外部特征计算器： molfeat 的额外组件不包含 MAP4 — 请单独从 reymond-group/map4 安装。某些较重的依赖项（DGL、dgllife、graphormer-pretrained）通过 conda-forge 安装更方便；请参阅可选依赖项。

核心概念

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）、深度学习、相似性搜索和基于药效团的方法——以及 QSAR 模型构建、虚拟筛选、相似性搜索、scikit-learn 流水线集成和比较多个特征化器的完整工作流示例，详见 references/choosing_a_featurizer.md。

完整的特征化器列表请参阅 references/available_featurizers.md；更多示例请参阅 references/examples.md。

发现可用的特征化器

使用 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)

批量处理大型数据集

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 内置的预训练模型缓存。对于自定义嵌入缓存，请使用 NumPy 数组而非 pickle（加载不可信文件时，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. 选择合适的特征化器：指纹比深度学习模型更快
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]==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：使用 Python medchem 库（datamol-io，v2.0.5）基于 RDKit 和 datamol 筛选和分类小分子库。