molfeat-molecular-featurization

Molfeat — 分子特征化中心

概述

Molfeat 是一个全面的 Python 分子特征化库，通过兼容 scikit-learn 的 API，将 100 多种预训练嵌入和手工设计的特征化器统一起来。将 SMILES 字符串转换为数值表示（指纹、描述符、深度学习嵌入），用于 QSAR 建模、虚拟筛选、相似性搜索和化学空间分析。

适用场景

• 构建需要以分子特征作为输入的 QSAR/QSPR 模型
• 虚拟筛选——根据预测活性对化合物库排序
• 在分子数据库中进行相似性搜索
• 化学空间分析——聚类、可视化、降维
• 使用预训练嵌入（ChemBERTa、GIN）进行分子深度学习
• 构建与 scikit-learn 或 PyTorch 集成的特征化流水线
• 对多个分子表示进行比较和基准测试
• 进行分子操作和筛选时使用 datamol；进行基于子结构的分子操作时使用 rdkit-cheminformatics

前置条件

uv pip install molfeat

# Optional extras for specific featurizer types
uv pip install "molfeat[transformer]"   # ChemBERTa, ChemGPT, MolT5
uv pip install "molfeat[dgl]"           # GIN graph neural networks
uv pip install "molfeat[graphormer]"    # Graphormer models
uv pip install "molfeat[fcd]"           # FCD descriptors
uv pip install "molfeat[map4]"          # MAP4 fingerprints
uv pip install "molfeat[all]"           # All dependencies

快速开始

from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer

smiles = ["CCO", "CC(=O)O", "c1ccccc1", "CC(C)O"]

# Create fingerprint calculator + transformer
calc = FPCalculator("ecfp", radius=3, fpSize=2048)
transformer = MoleculeTransformer(calc, n_jobs=-1)

# Featurize batch in parallel
features = transformer(smiles)
print(f"Shape: {features.shape}")  # (4, 2048)

# Save configuration for reproducibility
transformer.to_state_yaml_file("featurizer_config.yml")

核心概念

架构：Calculator → Transformer → Store

Molfeat 将特征化分为三个层：

层	类	用途	使用场景
Calculator	molfeat.calc.*	单个分子 → 特征向量	自定义循环、单个分子
Transformer	molfeat.trans.MoleculeTransformer	通过并行处理进行批量处理	数据集、scikit-learn 流水线
Store	molfeat.store.ModelStore	发现和加载预训练模型	查找可用的特征化器

Calculator 可调用：calc("CCO") 会返回一个 numpy 数组。Transformer 将 Calculator 封装起来进行批量处理：transformer(smiles_list) 会返回一个二维数组。预训练 Transformer（PretrainedMolTransformer）支持批量 GPU 推理和缓存。

特征化器选择指南

任务	推荐项	维度	速度
通用 QSAR	ecfp（radius=3）	2048	快
骨架相似性	maccs	167	非常快
大规模筛选	map4	1024	快
可解释模型	desc2D（RDKitDescriptors2D）	200+	快
综合描述符	mordred	1800+	中等
迁移学习	ChemBERTa-77M-MLM	768	慢*
基于图的深度学习	gin-supervised-masking	可变	慢*
药效团	fcfp 或 cats2D	2048 / 21	快
3D 形状	usr / usrcat	12 / 60	快

*首次运行较慢；后续运行会使用缓存。

状态持久化

保存并重新加载精确的特征化器配置，以确保可复现性：

# Save
transformer.to_state_yaml_file("config.yml")
transformer.to_state_json_file("config.json")

# Reload
loaded = MoleculeTransformer.from_state_yaml_file("config.yml")

核心 API

1. 指纹 Calculator

from molfeat.calc import FPCalculator

# ECFP — most popular, general-purpose
ecfp = FPCalculator("ecfp", radius=3, fpSize=2048)
fp = ecfp("CCO")
print(f"ECFP shape: {fp.shape}")  # (2048,)

# MACCS keys — 167-bit structural keys, fast scaffold similarity
maccs = FPCalculator("maccs")
fp = maccs("c1ccccc1")
print(f"MACCS shape: {fp.shape}")  # (167,)

# Count-based fingerprints (non-binary)
ecfp_count = FPCalculator("ecfp-count", radius=3, fpSize=2048)

# MAP4 — MinHashed atom-pair, efficient for large databases
map4 = FPCalculator("map4")
print(f"MAP4 shape: {map4('CCO').shape}")  # (1024,)

可用的指纹类型：ecfp、fcfp、maccs、rdkit、avalon、pattern、layered、atompair、topological、map4、secfp、erg、estate（以及带有 -count 后缀的计数变体）。

2. 描述符 Calculator

from molfeat.calc import RDKitDescriptors2D, MordredDescriptors

# RDKit 2D — 200+ named properties (MW, logP, TPSA, etc.)
desc2d = RDKitDescriptors2D()
descriptors = desc2d("CCO")
print(f"2D descriptors: {len(descriptors)}")  # 200+
print(f"Feature names: {desc2d.columns[:5]}")

# Mordred — 1800+ comprehensive descriptors
mordred = MordredDescriptors()
descriptors = mordred("c1ccccc1O")
print(f"Mordred descriptors: {len(descriptors)}")  # 1800+

3. 药效团和形状 Calculator

from molfeat.calc import CATSCalculator, USRDescriptors

# CATS — pharmacophore point pair distributions
cats = CATSCalculator(mode="2D", scale="raw")
descriptors = cats("CC(C)Cc1ccc(C)cc1C")
print(f"CATS shape: {descriptors.shape}")  # (21,)

# USR — ultrafast shape recognition
usr = USRDescriptors()
shape = usr("CC(=O)Oc1ccccc1C(=O)O")
print(f"USR shape: {shape.shape}")  # (12,)

4. 使用 Transformer 进行批量处理

from molfeat.trans import MoleculeTransformer, FeatConcat
from molfeat.calc import FPCalculator

smiles = ["CCO", "CC(=O)O", "c1ccccc1", "CC(C)O", "CCCC"]

# Parallel batch processing
transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
features = transformer(smiles)
print(f"Batch shape: {features.shape}")  # (5, 2048)

# Concatenate multiple featurizers
concat = FeatConcat([
    FPCalculator("maccs"),      # 167 dims
    FPCalculator("ecfp")        # 2048 dims
])
combo_transformer = MoleculeTransformer(concat, n_jobs=-1)
combo_features = combo_transformer(smiles)
print(f"Combined shape: {combo_features.shape}")  # (5, 2215)

# Error-tolerant processing
safe_transformer = MoleculeTransformer(
    FPCalculator("ecfp"), n_jobs=-1,
    ignore_errors=True, verbose=True
)
features = safe_transformer(["CCO", "invalid", "c1ccccc1"])
# Returns None for failed molecules

5. 预训练模型嵌入

from molfeat.trans.pretrained import PretrainedMolTransformer

# ChemBERTa — RoBERTa trained on 77M PubChem compounds
chemberta = PretrainedMolTransformer("ChemBERTa-77M-MLM", n_jobs=-1)
embeddings = chemberta(["CCO", "CC(=O)O", "c1ccccc1"])
print(f"ChemBERTa shape: {embeddings.shape}")  # (3, 768)

# GIN — graph neural network pretrained on ChEMBL
gin = PretrainedMolTransformer("gin-supervised-masking", n_jobs=-1)
graph_emb = gin(["CCO", "CC(=O)O"])
print(f"GIN shape: {graph_emb.shape}")

6. ModelStore — 发现特征化器

from molfeat.store.modelstore import ModelStore

store = ModelStore()
print(f"Total available: {len(store.available_models)}")

# Search for specific model
results = store.search(name="ChemBERTa")
for model in results:
    print(f"  {model.name}: {model.description}")

# View usage and load
card = store.search(name="ChemBERTa-77M-MLM")[0]
card.usage()
transformer = store.load("ChemBERTa-77M-MLM")

常见工作流

工作流 1：构建 QSAR 模型

from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer
from sklearn.ensemble import RandomForestRegressor
from sklearn.model_selection import cross_val_score

# Featurize molecules
transformer = MoleculeTransformer(FPCalculator("ecfp", radius=3), n_jobs=-1)
X = transformer(smiles_train)
print(f"Features shape: {X.shape}")

# Train and evaluate
model = RandomForestRegressor(n_estimators=100)
scores = cross_val_score(model, X, y_train, cv=5, scoring='r2')
print(f"R² = {scores.mean():.3f} ± {scores.std():.3f}")

# Save for deployment
transformer.to_state_yaml_file("production_featurizer.yml")

工作流 2：虚拟筛选流水线

from sklearn.ensemble import RandomForestClassifier

# Step 1: Featurize known actives/inactives
transformer = MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)
X_train = transformer(train_smiles)

# Step 2: Train classifier
clf = RandomForestClassifier(n_estimators=500, n_jobs=-1)
clf.fit(X_train, train_labels)

# Step 3: Screen library (e.g., 1M compounds)
X_screen = transformer(screening_smiles)
predictions = clf.predict_proba(X_screen)[:, 1]

# Step 4: Rank and select top hits
top_indices = predictions.argsort()[::-1][:1000]
top_hits = [screening_smiles[i] for i in top_indices]
print(f"Top 1000 hits selected from {len(screening_smiles)} compounds")

工作流 3：特征化器基准测试

from molfeat.calc import FPCalculator, RDKitDescriptors2D
from sklearn.metrics import roc_auc_score

featurizers = {
    'ECFP': FPCalculator("ecfp"),
    'MACCS': FPCalculator("maccs"),
    'Descriptors': RDKitDescriptors2D(),
}

for name, calc in featurizers.items():
    transformer = MoleculeTransformer(calc, n_jobs=-1)
    X_train = transformer(smiles_train)
    X_test = transformer(smiles_test)
    clf = RandomForestClassifier(n_estimators=100)
    clf.fit(X_train, y_train)
    auc = roc_auc_score(y_test, clf.predict_proba(X_test)[:, 1])
    print(f"{name}: AUC = {auc:.3f}")

常见用法

用法：集成 Scikit-learn 流水线

from sklearn.pipeline import Pipeline
from sklearn.ensemble import RandomForestClassifier

pipeline = Pipeline([
    ('featurizer', MoleculeTransformer(FPCalculator("ecfp"), n_jobs=-1)),
    ('classifier', RandomForestClassifier(n_estimators=100))
])
pipeline.fit(smiles_train, y_train)
predictions = pipeline.predict(smiles_test)

用法：相似性搜索

from sklearn.metrics.pairwise import cosine_similarity

calc = FPCalculator("ecfp")
query_fp = calc("CC(=O)Oc1ccccc1C(=O)O").reshape(1, -1)  # Aspirin

transformer = MoleculeTransformer(calc, n_jobs=-1)
db_fps = transformer(database_smiles)

similarities = cosine_similarity(query_fp, db_fps)[0]
top_k = similarities.argsort()[-10:][::-1]
for i in top_k:
    print(f"  {database_smiles[i]}: {similarities[i]:.3f}")

用法：大型数据集的分块处理

import numpy as np

def featurize_chunks(smiles_list, transformer, chunk_size=10000):
    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)
        print(f"Processed {min(i+chunk_size, len(smiles_list))}/{len(smiles_list)}")
    return np.vstack(all_features)

关键参数

参数	模块	默认值	描述
method	FPCalculator	—	指纹类型：ecfp、maccs、map4 等。
radius	FPCalculator	3	环状指纹半径
fpSize	FPCalculator	2048	指纹位长度
counting	FPCalculator	False	使用计数向量而非二进制向量
n_jobs	MoleculeTransformer	1	并行工作进程数（-1 = 使用所有核心）
ignore_errors	MoleculeTransformer	False	跳过无效分子（返回 None）
verbose	MoleculeTransformer	False	记录处理详情
dtype	MoleculeTransformer	float64	输出类型（节省内存时使用 float32）
mode	CATSCalculator	"2D"	距离计算模式
scale	CATSCalculator	"raw"	缩放方式：raw、num、count

最佳实践

• 使用 n_jobs=-1，在所有 CPU 核心上并行处理，大幅加快批量特征计算
• 从 ECFP 入手，构建初始基线；在尝试深度学习之前，它是最佳的通用指纹
• 处理大型数据集时使用 ignore_errors=True，避免无效 SMILES 导致流水线崩溃
• 使用 to_state_yaml_file() 保存配置，确保结果可复现，并可在之后重建完全相同的特征计算器
• 内存紧张时使用 float32：MoleculeTransformer(calc, dtype=np.float32)
• 缓存预训练嵌入：首次运行 ChemBERTa/GIN 推理较慢，后续运行会使用缓存
• 数据集超过 100K 条时分块处理，避免内存耗尽（参见 Recipes）
• 使用 FeatConcat 组合指纹，以获取互补的分子信息

故障排除

问题	原因	解决方案
ValueError: unsupported featurizer	方法名称未知	检查 FPCalculator 支持的类型，或使用 ModelStore.search()
预训练模型出现 ImportError	缺少可选依赖项	安装扩展依赖：pip install "molfeat[transformer]" 或 "molfeat[dgl]"
输出数组中包含 None	使用 ignore_errors=True 时遇到无效 SMILES	筛选结果：[f for f in features if f is not None]
大型数据集出现内存错误	一次处理的分子过多	分成每批 10K-50K 条处理（参见 Recipes）
预训练模型推理速度慢	首次运行会下载模型权重	这是正常现象；后续运行会使用缓存
流水线中形状不匹配	有效分子与无效分子混杂	确保使用 ignore_errors=True，并在输入 ML 模型前筛除 None
结果无法复现	molfeat 版本不同	固定版本并保存配置：transformer.to_state_yaml_file()

相关技能

• datamol-cheminformatics — 高级分子操作（标准化、I/O、构象）
• rdkit-cheminformatics — 低级化学信息学操作（子结构、反应、3D）
• scikit-learn — 使用 molfeat 特征的 ML 模型

参考资料

• 官方文档：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

随附资源

主 SKILL.md + 2 个参考文件。原始总计：1,273 行（SKILL.md 510 行 + api_reference.md 429 行 + available_featurizers.md 334 行）。脚本：无。示例：724 行（examples.md）。

references/available_featurizers.md：按类别整理的 100 多种 featurizer 完整目录，包括 Transformer 模型、GNN、描述符、指纹、药效团、形状、骨架和图 featurizer。每个类别均包含维度、依赖项和选择指南。纯查询类内容保留为参考资料。

references/api_reference.md：molfeat.calc、molfeat.trans 和 molfeat.store 模块的详细 API 参考。涵盖 SerializableCalculator 基类、所有带参数的计算器子类、MoleculeTransformer 方法、PretrainedMolTransformer、FeatConcat、ModelStore/ModelCard API、数据类型控制以及 PyTorch 集成模式。

原始文件处理情况：

• SKILL.md（510 行）→ 核心 API 模块 1-6、关键概念（架构、选择指南）、快速入门、工作流 1-3。“选择合适的 Featurizer”→“关键概念”中的选择指南表。“高级功能”（自定义预处理、批处理、缓存）→“实用方案”+“最佳实践”。“常见 Featurizer 参考”表→“关键概念”中的选择指南。按使用场景处理：QSAR 建模 → 工作流 1，虚拟筛选 → 工作流 2，相似性搜索 → 实用方案，化学空间 →“适用场景”项目符号，scikit-learn Pipeline → 实用方案，Featurizer 比较 → 工作流 3
• references/api_reference.md（429 行）→ 迁移至新的 references/api_reference.md。核心模式（FPCalculator、MoleculeTransformer、基础 ModelStore）移至 SKILL.md 核心 API 模块 1-6。详细类方法、SerializableCalculator 基类、PrecomputedMolTransformer 和 PyTorch 集成保留在参考资料中
• references/available_featurizers.md（334 行）→ 迁移至新的 references/available_featurizers.md。顶层摘要 →“关键概念”中的选择指南表。完整分类目录保留在参考资料中
• references/examples.md（724 行）→ 全部整合至正文：安装 →“前提条件”；计算器示例 → 核心 API 1-3；转换器示例 → 核心 API 4；预训练示例 → 核心 API 5；机器学习集成 → 工作流 1-3 + 实用方案；高级模式（自定义预处理、缓存、分块处理）→ 实用方案 + 最佳实践；故障排除 → 故障排除表。无需单独的参考文件，所有内容均已并入 SKILL.md 各章节

保留比例：约 490 行（SKILL.md）+ 约 170 行（available_featurizers）+ 约 190 行（api_reference）= 原始 1,273 行中的约 850 行（不含视为已整合的 examples.md）= 约 67%。若将 examples.md 计入分母：约 850 / 1,997 = 约 43%。