alterlab-molfeat

Molfeat — 分子特征化中心

概述

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

何时使用此技能

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

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

不适用的场景

场景	请改用
使用内置加载器和 GNN，在 MoleculeNet 基准上端到端训练/评估模型	alterlab-deepchem
获取带有 scaffold/cold 划分的带标签基准数据集	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 扩展也一并移除（从未有过 map4 扩展）；现在加载这些模型存储条目会失败。新的基础模型特征化器包括 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 将特征化分为三个层级类：

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
)

大型数据集的内存问题

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

预训练模型依赖项

某些模型需要额外的软件包。请安装特定的附加组件：

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 套件。