企业官网建设流程全解析

• 科学计算
• 科研
• 机器学习

导读

本文聚焦 RDKit 的rdkit.Chem.FeatMaps.FeatMaps模块（源码位于 rdkit/Chem/FeatMaps/FeatMaps.py），系统讲解化学特征图（Feature Map，药效团的核心数据表示）的构建、打分与操作。读完本文，你将掌握：如何用FeatMapParams为不同特征族定义空间打分轮廓、如何用FeatMap对探针分子特征批量打分并理解All / Closest / Best三种打分模式、如何利用方向一致性增强药效团匹配的可靠性，以及如何通过FeatMapParser用文本格式定义可复用的特征图。文中所有结论均以本仓库源码与单元测试为直接依据。

FeatMaps 在 RDKit 中的定位与整体架构

FeatMaps是 RDKit 化学信息工具链中用于表示和比较"化学特征空间分布"的模块，典型应用是构建药效团模型（pharmacophore）：从一组活性分子中提炼出共同的特征（芳香环、氢键供体/受体、疏水中心等）及其空间位置，再用它去匹配和打分新分子。

本模块的 API 文档页面 Docs/Book/source/rdkit.Chem.FeatMaps.FeatMaps.rst 通过 Sphinx 的automodule指令自动生成，与其配套的还有 FeatMapPoint.rst、FeatMapParser.rst、FeatMapUtils.rst，共同构成 rdkit.Chem.FeatMaps 包的四个子模块。四个子模块的职责划分如下：

特征点 FeatMapPoint：位置、权重与方向

特征图的基本单元是FeatMapPoint（FeatMapPoint.py），它继承自ChemicalFeatures.FreeChemicalFeature，因此天然拥有GetFamily()（特征族，如 Aromatic、Acceptor）、GetType()（特征类型）、GetPos()（三维坐标Point3D）等能力，并额外扩展了两项属性：

• weight：该特征点的权重，默认0.0，参与打分时的乘法因子；
• featDirs：方向向量列表（每个元素为Geometry.Point3D），用于表示特征的方向性（如氢键受体的孤对电子方向）。

FeatMapPoint.initFromFeat(feat)负责从任意FreeChemicalFeature复制族、类型、位置与方向列表；GetDist2(other)返回两点间距离平方（(self.GetPos() - other.GetPos()).LengthSq()），这是后续半径判断的基础。

方向匹配 GetDirMatch

GetDirMatch(other, useBest=True)计算两个特征点的方向一致性，逻辑如下（FeatMapPoint.py）：

• 任一方无方向向量（featDirs为空）时返回1.0（方向不影响分数）；
• useBest=True：取两方向集合中所有点积的最大值，表示"存在一个最匹配的方向组合"；
• useBest=False：累加所有方向点积后除以len(self.featDirs) * len(other.featDirs)，即平均点积。

该文件内嵌的 doctest 验证了典型行为：两个完全对齐的方向返回1.0，完全反平行返回-1.0，部分对齐（如(0,0,1)与(0,1,0)）返回0.0。这个返回值范围是 [-1, 1]，下游FeatMap.GetFeatFeatScore会直接使用它。

打分模式与参数：两个枚举类 + FeatMapParams

FeatMapScoreMode：特征图打分模式

FeatMaps.py 定义了三种模式，控制"探针特征"如何与特征图中的特征配对：

FeatDirScoreMode：方向打分模式

FeatMapParams：每特征族的打分参数

每个特征族在特征图中都需要一个FeatMapParams实例（FeatMaps.py）：

轮廓枚举FeatMapParams.FeatProfile提供三种打分函数：

• Gaussian（0）：score = exp(-d² / width)，距离越近分越高，平滑衰减；
• Triangle（1）：score = 1 - d / width（d < width 时），线性衰减；
• Box（2）：半径内恒为1.0，硬截断。

核心类 FeatMap：构建与打分

FeatMap是模块的核心类，类级属性dirScoreMode、scoreMode、params作为默认值，实例化时可通过FeatMap(params=None, feats=None, weights=None)传入参数表、特征列表与权重列表。

构建特征图

• AddFeature(feat, weight=None)：把任意FreeChemicalFeature转成FeatMapPoint加入特征图；若self.params非空而feat.GetFamily()不在其中，会抛出ValueError（FeatMaps.py）。
• AddFeatPoint(featPt)：直接加入一个FeatMapPoint实例，同样校验族是否在 params 中。
• 查询与删除：GetFeatures()返回全部、GetNumFeatures()返回数量、GetFeature(i)按索引取、DropFeature(i)删除。
• __str__以表格形式输出每个特征点的序号、族、坐标（x/y/z）与权重（FeatMaps.py）。

_initializeFeats要求feats与weights长度一致，否则抛ValueError('feats and weights lists must be the same length')。

单特征打分 GetFeatFeatScore

GetFeatFeatScore(feat1, feat2, typeMatch=True)（FeatMaps.py）的完整算法：

1. 若typeMatch=True且两特征族不同，直接返回0.0；
2. 计算距离平方d2 = feat1.GetDist2(feat2)，若d2 > radius²返回0.0；
3. 按featProfile计算空间得分（Gaussian / Triangle / Box）；
4. 乘以feat1.weight；
5. 若dirScoreMode != Ignore，再乘以方向匹配分（DotPosRange时先做(dirScore + 1)/2缩放）。

该方法的数值行为有完整单元测试佐证：UnitTestFeatMap.py 中，Gaussian 模式下距离 1.0 与 1.5 分别得到exp(-1)、exp(-2.25)，距离 2.1（超过 radius=2.0）得 0；Triangle 模式（width=2.0, radius=3.0）距离 1.0 得 0.5、距离 2.1 得 0；Box 模式半径内恒等于权重1.1。

批量打分 ScoreFeats

ScoreFeats(featsToScore, mapScoreVect=None, featsScoreVect=None, featsToFeatMapIdx=None)（FeatMaps.py）是特征图与探针分子特征集合比对的主入口，返回总得分，同时可选地回填三个向量：

• mapScoreVect：长度等于特征图特征数，记录特征图中每个特征从各探针特征获得的累计分数；
• featsScoreVect：长度等于探针特征数，记录每个探针特征获得的分数；
• featsToFeatMapIdx：记录每个探针特征命中了特征图中哪些特征的索引（All 模式为列表，Closest/Best 模式为单元素列表）。

三种模式的具体行为差异（源码 + 测试双重印证，见 UnitTestFeatMap.py）：

• All 模式：featsScoreVect[oIdx] += lScore，mapScoreVect[sIdx] += lScore，总分为sum(featsScoreVect)；
• Closest 模式：先找距离最近的同族特征（d < featsScoreVect[oIdx]时更新），再统一用GetFeatFeatScore结算；
• Best 模式：每个探针特征只保留使其得分最高的特征图特征（lScore > featsScoreVect[oIdx]时更新）。

测试用例（Box 轮廓简化计算）中：三个图特征权重 1.1/1.1/2.1，探针特征（Aromatic @(0,1,0)、Acceptor @(1.5,0,0)）在 All 模式下总分为4.3，Closest 模式为2.1，Best 模式为3.2，且三种模式均满足sum(mapScoreVect) == sum(featsScoreVect) == totScore。

方向打分测试见 UnitTestFeatMap.py：DotFullRange下方向反平行得-1.1（负贡献）、正交得0.0；切换为DotPosRange后反平行得0.0、同向得1.1。

文本格式特征图：FeatMapParser

为了便于人工编辑和复用特征图，模块提供了FeatMapParser（FeatMapParser.py）。它支持三种输入：文件对象（file=）、字符串（data=）、字符串列表，均可通过Parse()得到FeatMap。

文本语法

文件内嵌文档给出了完整的语法示例（FeatMapParser.py）：

ScoreMode=All DirScoreMode=Ignore BeginParams family=Aromatic radius=2.5 width=1.0 profile=Gaussian family=Acceptor radius=1.5 EndParams # optional BeginPoints family=Acceptor pos=(1.0, 0.0, 5.0) weight=1.25 dir=(1, 1, 0) family=Aromatic pos=(0.0,1.0,0.0) weight=2.0 dir=(0,0,1) dir=(0,0,-1) family=Acceptor pos=(1.0,1.0,2.0) weight=1.25 EndPoints

语法要点：

• 顶层键值对ScoreMode、DirScoreMode的取值对应上述枚举名；注意解析时大小写不敏感（scoreMode、dirscoremode均可识别），但非法取值会抛FeatMapParseError；
• BeginParams ... EndParams块为每个family定义一个FeatMapParams，可写radius、width、profile（取值Gaussian/Triangle/Box），family必须存在；
• BeginPoints ... EndPoints块定义特征点：family必需，pos=(x,y,z)定义坐标（必须恰好三个分量），weight定义权重，dir=(x,y,z)可重复出现以追加多个方向向量；
• #为注释符，行尾\支持续行（FeatMapParser.py）。

解析行为与错误处理

ParseParamBlock用正则([a-zA-Z]+) *= *(\S+)逐项提取参数；ParseFeatPointBlock用([a-zA-Z]+) *= *切分特征点字段。所有非法关键字、未知 profile、缺少EndParams/EndPoints、坐标分量数不为 3 等都会抛出FeatMapParseError（坐标错误为ValueError），详见 UnitTestFeatMapParser.py 中的 12 组负例测试。正例测试则验证了三种输入方式（字符串、字符串列表、流对象）解析结果一致，且权重、方向数量、族顺序均正确还原。

特征图操作工具：FeatMapUtils

FeatMapUtils.py 提供特征图之间的合并能力，由三组枚举控制策略：

• MergeMethod：合并后新点的位置策略——WeightedAverage（按权重加权平均）、Average（简单平均）、UseLarger（取权重较大者位置）；
• MergeMetric：判定两个点"是否需要合并"的准则——NoMerge、Distance（距离低于阈值）、Overlap（重叠百分比超过阈值）；
• DirMergeMode：方向向量的合并方式——NoMerge（保留全部方向）或Sum（向量求和）。

关键函数：

• GetFeatFeatDistMatrix(fm, mergeMetric, mergeTol, dirMergeMode, compatFunc)：构建特征间距离/重叠矩阵，compatFunc默认为familiesMatch（仅同族可合并）。注意文档与源码的明确提示：mergeTol在 Distance 模式下是合并距离上限，在 Overlap 模式下是重叠分数下限；
• MergeFeatPoints(fm, ...)：迭代合并互为最近邻的点对，直至无可合并项，返回是否发生合并（布尔值）；
• CombineFeatMaps(fm1, fm2, ...)：复制两张特征图（参数取自fm1），按需执行合并，返回新特征图。

这些工具适合"多分子药效团提炼"场景：先对每个分子生成特征图，再用CombineFeatMaps叠加合并，得到覆盖全活性系列的共同特征分布。

端到端实战：从分子特征到特征图打分

结合上述全部 API，一个完整的实战流程如下：

from rdkit import Chem from rdkit.Chem import ChemicalFeatures from rdkit.Chem.FeatMaps import FeatMaps from rdkit import RDConfig import os # 1. 用特征定义文件（fdef）构建分子特征工厂 fdefName = os.path.join(RDConfig.RDDataDir, 'BaseFeatures.fdef') factory = ChemicalFeatures.BuildFeatureFactory(fdefName) # 2. 提取分子的化学特征（返回 FreeChemicalFeature 元组） mol = Chem.MolFromSmiles('c1ccccc1C(=O)O') feats = factory.GetFeaturesForMol(mol) # 每个特征含 Family / Type / 3D 位置 # 3. 为特征图涉及的每个特征族定义打分参数 params = {} for f in feats: if f.GetFamily() not in params: p = FeatMaps.FeatMapParams() p.radius = 2.5 p.width = 1.0 p.featProfile = FeatMaps.FeatMapParams.FeatProfile.Gaussian params[f.GetFamily()] = p # 4. 构建特征图（也可以从文本用 FeatMapParser 加载） fm = FeatMaps.FeatMap(params=params) for f in feats: fm.AddFeature(f, weight=1.0) # 5. 用另一组特征对特征图打分（返回总得分） queryFeats = factory.GetFeaturesForMol(Chem.MolFromSmiles('c1ccccc1N')) score = fm.ScoreFeats(queryFeats) print('similarity score:', score)

实践要点：

• weight是打分灵敏度的重要旋钮，AddFeature时可以按特征重要性赋权；
• 若只关心"存在性"匹配，使用Box轮廓 +Best模式最直观；若希望累积多个特征的重叠程度，使用Gaussian+All模式；
• 分子若有 3D 构象，特征会带有方向信息（如featDirs），此时开启DirScoreMode.DotPosRange可要求方向一致，避免仅凭位置匹配的假阳性。

相关资源导航

• 模块源码：rdkit/Chem/FeatMaps/FeatMaps.py、FeatMapPoint.py、FeatMapParser.py、FeatMapUtils.py
• 单元测试：UnitTestFeatMap.py、UnitTestFeatMapParser.py、UnitTestFeatMapPoint.py、UnitTestFeatMapUtils.py
• 特征来源：ChemicalFeatures.BuildFeatureFactory与GetFeaturesForMol（ChemicalFeatures.py），fdef 定义文件示例见 Data/BaseFeatures.fdef
• API 文档：本文对应的 Sphinx 页面 rdkit.Chem.FeatMaps.FeatMaps.rst 及其姊妹页面 FeatMapPoint.rst、FeatMapParser.rst、FeatMapUtils.rst

• 科学计算
• 科研
• 机器学习