mcpField
M
molfeat

molfeat

github.com/k-dense-ai数据与数据库55.1k1.9k 次安装2 天前更新
代码仓库

关于 molfeat

molfeat 是一项将 SMILES 或 RDKit 分子转换为机器学习和相似性搜索特征的流程技能。它涵盖指纹、描述符、药效团和预训练嵌入，并指导数据对齐与避免泄漏的评估。

主要功能

  1. 01计算分子指纹
  2. 02生成描述符和药效团
  3. 03创建预训练分子嵌入
  4. 04批量处理并验证输入
  5. 05保存和重新加载特征器配置

适用场景

  1. 01构建分子机器学习输入
  2. 02比较适用于实验终点的分子表征
  3. 03按分子相似性筛选化合物
  4. 04建立可复现的 QSAR 特征流程

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/k-dense-ai/scientific-agent-skills --skill molfeat

安装后在 Claude Code 中输入/molfeat确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
api_reference.md
available_featurizers.md
choosing_a_featurizer.md
examples.md

详细介绍

Molfeat — 小分子特征化

何时使用

使用本技能可将 SMILES 或 RDKit 分子转换为指纹、描述符、药效团或预训练嵌入，用于分子机器学习和相似性搜索。在同一分子划分和测定终点上比较不同表示。

本技能针对 Molfeat 1.0.0。之前 0.11 运行时的指导已过时：1.x 支持现代 Python，并移除了 DGL/DGLLife、旧版 Graphormer 和蛋白质适配器。历史模型库卡片仍可能列出已移除的适配器。带标签的 1.0 迁移指南和源代码优先于文档 stable URL 上仍在提供的旧页面。

安装

创建隔离环境。核心示例在 Python 3.13.3/macOS Apple Silicon 上执行，使用 Molfeat 1.0.0、datamol 0.13.0、RDKit 2026.03.6 和 PyTorch 2.14.1。

uv venv --python 3.13 .venv-molfeat
uv pip install --python .venv-molfeat/bin/python "molfeat==1.0.0"

在 Windows 上使用 .venv-molfeat\Scripts\python.exe 作为解释器路径。上游支持 Python 3.11–3.14；macOS Intel 使用 Python 3.11–3.12、PyTorch 2.2.x、NumPy<2 和 Transformers<5。其他平台需要 PyTorch>=2.5。让 Molfeat 的平台标记解析这些约束；不要将 Apple Silicon 的版本锁定复制到 Intel。

使用同一解释器仅安装所需的额外依赖：molfeat[transformer]==1.0.0 用于 Hugging Face 模型，[mordred] 用于 mordredcommunity，[pyg] 用于图张量，[fcd] 用于 ChemNet 嵌入，[selfies] 用于 SELFIES 转换，[cache] 用于 HDF5/Parquet，[viz] 用于可视化，[cloud] 用于 S3/GCS 存储。DGL 和 Graphormer 额外依赖已不存在。预训练推理可能下载大量权重；请先检查模型许可、磁盘空间和设备要求。

工作流

  1. 保留源记录 ID、标签、原始结构和已声明的盐、立体化学、互变异构体、电荷及重复化合物处理策略。标准化会改变化学身份；对训练和预测应用相同策略。
  2. 从显式的 ECFP 基线开始。计算器处理单个分子；MoleculeTransformer 对其进行批处理。datamol.Mol 是 RDKit 的分子类型。
  3. 记录被拒绝的位置，并对齐所有关联数组。单独检查描述符的 NaN/Inf：成功解析并不保证特征有限。
  4. 在训练折内拟合任何特征选择、插补、缩放和模型。优先使用适合科学问题的骨架/分组或时间划分；随机划分可能泄漏近似类似物或重复测量。
  5. 保存特征化器状态、有序特征名称、包版本、分子预处理策略和输入 ID。迁移到 1.x 后重新验证旧状态。
指纹基线和无效记录
import numpy as np
from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer

smiles = ["CCO", "invalid", "CC(=O)O", "c1ccccc1"]
record_ids = np.array(["ethanol", "rejected", "acetate", "benzene"])
y = np.array([0.1, 9.9, 0.2, 0.3])  # toy labels only
calc = FPCalculator("ecfp", radius=2, fpSize=2048, includeChirality=True)
transformer = MoleculeTransformer(calc, n_jobs=1, dtype=np.float32)
X, valid_ids = transformer(smiles, ignore_errors=True)
assert X.shape == (3, 2048)
X_ids, y_valid = record_ids[valid_ids], y[valid_ids]
assert valid_ids == [0, 2, 3]
assert np.isfinite(X).all()

ignore_errors 属于调用，而不是构造函数。为 True 时，__call__ 返回过滤后的特征和原始输入位置；为 False 时，对失败的分子抛出异常。transform(..., ignore_errors=True) 保留位置，对失败项使用 None。切勿独立过滤每个特征块后再拼接。

ECFP 半径是键半径：radius=2 表示 ECFP4；radius 3 表示 ECFP6。在 1.0.0 中，FPCalculator("ecfp") 默认 radius 2 和 2048 位。FPVecTransformer 具有不同的默认长度 2000，因此使用它时请指定 length=2048。

配置往返
transformer.to_state_yaml_file("featurizer.yml")
loaded = MoleculeTransformer.from_state_yaml_file("featurizer.yml")
np.testing.assert_array_equal(loaded(["CCO"]), transformer(["CCO"]))

仅加载受信任的配置/构件。状态可以识别 Python 类和自定义序列化可调用对象；YAML/JSON 并不能使任意第三方状态安全。状态保存的是配置，而不是测定标签、预处理决策或训练好的 QSAR 模型。

预训练嵌入

仅作说明；已检查导入和签名，但未下载任何模型权重：

from molfeat.trans.pretrained import PretrainedHFTransformer

embedder = PretrainedHFTransformer(
    kind="ChemBERTa-77M-MLM", pooling="mean", concat_layers=-1,
    device="cpu", max_length=128, preload=False,
)
# First inference downloads/loads the model.
# embeddings = embedder(["CCO", "c1ccccc1"])

PretrainedMolTransformer 是基类，不是模型名称工厂。请使用具体的适配器。嵌入宽度取决于 checkpoint、池化方式和所选层；不要假定为 768。检查 token 长度：在 max_length 处截断可能丢弃化学信息。请为每个保存的嵌入缓存保留模型 revision、tokenizer、notation、池化方式和最大长度。

选择并发现表示

需求起点检查项
指纹基线FPCalculator("ecfp", radius=2, fpSize=2048)手性、位碰撞、固定参数
结构键FPCalculator("maccs")167 个条目，包括未使用的零位
命名描述符RDKitDescriptors2D()列取决于 RDKit；检查非有限值
药效团对CATS()距离分箱决定宽度；2D 默认为 189
3D 形状USRDescriptors() / USRDescriptors("USRCAT")需要构象；12 / 60 个条目
预训练语言模型PretrainedHFTransformer(...)权重、许可证、tokenization、池化方式

有效名称和可选后端参见可用特征化器，批处理/存储语义参见 API 契约，预处理、拼接、3D 和相似度参见完整示例，防泄漏 QSAR 和有界内存筛选参见模型选择。

若要发现模型，请构造 ModelStore() 并检查 available_models，或使用精确的 search(name=...)。首次发现调用会读取公开 HTTPS 元数据。卡片的 usage() 以字符串形式返回代码；请审查它，而不要自动执行它。store.load(...) 返回 (artifact, ModelInfo)，而不是特征化器。历史卡片不能证明某个适配器受支持。

性能与可复现性

对于小型任务和调试，请使用 n_jobs=1。在实际工作负载上对受限并行进行基准测试；n_jobs=-1 可能使内存使用成倍增加，并与 scikit-learn 的嵌套并行叠加。请持久化每个分块，或在继续之前对其评分；累积每个分块并调用 vstack 仍需要将完整矩阵保存在内存中。缓存键必须包含分子标识、预处理、所有特征化器设置、包/模型版本以及行顺序。

来源与验证

已于 2026-10-01 对照 release、包元数据 和带标签的源代码进行审查。 本地测试覆盖核心特征化契约和小型合成工作流；它们不能确立预测有效性或预训练/可选后端推理支持。

引用 Scientific Agent Skills

本技能属于 K-Dense 的 Scientific Agent Skills。如果它对稿件、报告、演示或代码发布有实质性贡献，请将该论文添加到参考文献或软件部分，并告知用户你已这样做：

Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065

请始终引用当前版本。DOI 和 https://arxiv.org/abs/2609.00065 会解析到最新的 arXiv 版本，因此绝不要附加诸如 v1 之类的版本后缀。当网络访问可用时，请在撰写参考文献之前获取 https://arxiv.org/abs/2609.00065（或 http://export.arxiv.org/api/query?id_list=2609.00065），并从该记录中获取作者列表、年份和版本。如果记录列出了期刊参考文献或出版商 DOI，请改为引用已发表版本。

评论

支持 Markdown