medchem

Medchem

概述

Medchem 是由 datamol-io 开发的 Python 库，用于药物发现中的分子筛选和优先级排序。应用源自文献的类药性规则、命名警示目录、复杂度阈值、化学基团检测和自定义查询语言，以大规模筛选化合物库。筛选规则是依具体情境而定的指导原则——请结合领域专业知识和靶点知识使用。

**版本说明：**示例适用于 medchem 2.0.5（PyPI 稳定版，2024 年 11 月）。要求 Python ≥3.9。依赖 datamol 和 RDKit（会自动安装）。RuleFilters 和结构筛选类返回 pandas DataFrame。Lilly 扣分规则需要可选的原生二进制文件（mamba install lilly-medchem-rules）。

何时使用此技能

以下情况应使用此技能：

• 对化合物库应用类药性规则（Lipinski、Veber、CNS、类先导化合物）
• 根据结构警示、PAINS 或 NIBR 筛选库规则筛选分子
• 对用于命中化合物到先导化合物优化的化合物进行优先级排序
• 根据 ZINC 衍生阈值计算复杂度指标
• 检测官能团或命名子结构目录
• 使用 medchem 查询语言构建多条件筛选器

安装

uv pip install medchem datamol

可选——Eli Lilly 扣分筛选器（需要 conda-forge 原生二进制文件）：

mamba install -c conda-forge lilly-medchem-rules

核心功能

1. 药物化学规则

通过 medchem.rules 应用成熟的类药性规则。

列出可用规则：

import medchem as mc

mc.rules.RuleFilters.list_available_rules_names()
# ['rule_of_five', 'rule_of_five_beyond', 'rule_of_four', 'rule_of_three', ...]

对单个分子应用单条规则：

import datamol as dm
import medchem as mc

smiles = "CC(=O)OC1=CC=CC=C1C(=O)O"  # aspirin
mc.rules.basic_rules.rule_of_five(smiles)   # True
mc.rules.basic_rules.rule_of_cns(smiles)    # True
mc.rules.basic_rules.rule_of_veber(smiles)  # True

使用 RuleFilters 应用多条规则（返回 DataFrame）：

import datamol as dm
import medchem as mc

mols = [dm.to_mol(s) for s in smiles_list]

rfilter = mc.rules.RuleFilters(
    rule_list=["rule_of_five", "rule_of_oprea", "rule_of_cns", "rule_of_leadlike_soft"]
)
df = rfilter(mols=mols, n_jobs=-1, progress=True, keep_props=False)

# Columns: mol, pass_all, pass_any, rule_of_five, rule_of_oprea, ...
passing = df[df["pass_all"]]

使用 keep_props=True 可在结果中包含计算得出的描述符（mw、clogp、tpsa 等）。

2. 结构警示筛选器

使用 medchem.structural 检测有问题的模式。两个类均返回包含 pass_filter、status 和 reasons 列的 DataFrame。

常见警示（源自 ChEMBL 的规则集）：

import medchem as mc

alert_filter = mc.structural.CommonAlertsFilters()
df = alert_filter(mols=mol_list, n_jobs=-1, progress=True)
# df columns: mol, pass_filter, status, reasons

clean = df[df["pass_filter"]]

NIBR 筛选器（Novartis 筛选库整理规则）：

nibr_filter = mc.structural.NIBRFilters()
df = nibr_filter(mols=mol_list, n_jobs=-1, progress=True)
# df columns: mol, pass_filter, status, severity, reasons, n_covalent_motif, special_mol

默认排除 severity >= 10 的化合物（参见 NIBR 论文）。

3. 命名目录筛选器（PAINS、Brenk 等）

使用 medchem.catalogs.NamedCatalogs 获取 RDKit FilterCatalog 实例，或使用函数式 API：

import medchem as mc

# List available named catalogs
mc.catalogs.list_named_catalogs()
# ['tox', 'pains', 'pains_a', 'brenk', 'nibr', 'zinc', ...]

# Functional API — True means molecule passes (no alert match)
passes = mc.functional.alert_filter(mols=mol_list, alerts=["pains"], n_jobs=-1)

# Or via catalog objects
passes = mc.functional.catalog_filter(
    mols=mol_list,
    catalogs=[mc.catalogs.NamedCatalogs.pains()],
    n_jobs=-1,
)

4. 函数式 API

medchem.functional 提供可一次调用的封装函数，返回布尔掩码（True = 通过）：

import medchem as mc

mc.functional.rules_filter(mols=mol_list, rules=["rule_of_five", "rule_of_cns"], n_jobs=-1)
mc.functional.nibr_filter(mols=mol_list, max_severity=10, n_jobs=-1)
mc.functional.alert_filter(mols=mol_list, alerts=["pains", "brenk"], n_jobs=-1)
mc.functional.complexity_filter(mols=mol_list, complexity_metric="bertz", limit="99", n_jobs=-1)

其他辅助函数：catalog_filter、chemical_group_filter、lilly_demerit_filter（需要可选二进制文件）、macrocycle_filter、bredt_filter、protecting_groups_filter 等。

5. 化学基团

通过 medchem.groups 检测官能团和整理好的模式集合：

import medchem as mc

# Browse available group collections
mc.groups.list_default_chemical_groups()
# ['privileged_scaffolds', 'common_warhead_covalent_inhibitors', 'rings_in_drugs', ...]

group = mc.groups.ChemicalGroup(groups=["privileged_scaffolds"])
group.has_match(mol)                          # bool
group.get_matches(mol)                        # dict of group → atom indices
group.filter(mols)                            # molecules matching the group

# Returns molecules that do NOT match the group
mc.functional.chemical_group_filter(mols=mol_list, chemical_group=group, n_jobs=-1)

自定义基团可通过 groups_db 从文件加载（CSV，包含 smiles/smarts、name、group 列）。

6. 分子复杂度

将复杂度指标与预先计算的 ZINC-15 百分位阈值进行比较：

import medchem as mc

# Single molecule
cf = mc.complexity.ComplexityFilter(limit="99", complexity_metric="bertz")
cf(mol)  # True if below 99th-percentile threshold

# Batch via functional API
mc.functional.complexity_filter(
    mols=mol_list,
    complexity_metric="bertz",  # also: sas, qed, whitlock, barone, smcm, twc
    limit="99",
    n_jobs=-1,
)

# Direct metric functions
mc.complexity.WhitlockCT(mol)
mc.complexity.BaroneCT(mol)

7. 骨架约束

medchem.constraints.Constraints 匹配核心骨架并应用逐原子的约束函数，而非简单的 MW/LogP 范围。若要设置属性边界，请使用 RuleFilters、通过 mc.rules.list_descriptors() 获取的描述符，或查询语言。

import datamol as dm
import medchem as mc

core = dm.to_mol("c1ccccc1")
constraints = mc.constraints.Constraints(
    core=core,
    constraint_fns={"query": lambda mol, atom_idx, query: ...},
)
constraints(mol)

8. Medchem 查询语言

使用 medchem.query.QueryFilter 构建多条件筛选器：

import medchem as mc

# Rule + alert combination
qf = mc.query.QueryFilter('MATCHRULE("rule_of_five") AND NOT HASALERT("pains")')
mask = qf(mols=mol_list, n_jobs=-1)  # list[bool]

# CNS-like with property bounds
qf = mc.query.QueryFilter('MATCHRULE("rule_of_cns") AND HASPROP("tpsa", <=, 90)')
mask = qf(mols=mol_list, n_jobs=-1)

查询语法：

• MATCHRULE("rule_of_five") — 应用命名规则
• HASALERT("pains") — 匹配命名目录（pains、brenk、nibr、tox 等）
• HASPROP("mw", <, 500) — 比较描述符（比较运算符不加引号）
• HASGROUP("privileged_scaffolds") — 匹配化学基团
• HASSUBSTRUCTURE("c1ccccc1") — 匹配子结构
• 运算符：AND、OR、NOT

列出可用描述符：mc.rules.list_descriptors()

工作流模式

模式 1：化合物库初筛

import datamol as dm
import medchem as mc
import pandas as pd

df = pd.read_csv("compounds.csv")
mols = [dm.to_mol(s) for s in df["smiles"]]

# Drug-likeness rules
rules_df = mc.rules.RuleFilters(rule_list=["rule_of_five", "rule_of_veber"])(mols=mols, n_jobs=-1)

# PAINS + common alerts via query
qf = mc.query.QueryFilter('MATCHRULE("rule_of_five") AND NOT HASALERT("pains")')
pass_mask = qf(mols=mols, n_jobs=-1)

df["passes_rules"] = rules_df["pass_all"].values
df["drug_like"] = pass_mask
filtered_df = df[df["drug_like"]]
filtered_df.to_csv("filtered_compounds.csv", index=False)

模式 2：先导化合物优化筛选

import medchem as mc

rules_df = mc.rules.RuleFilters(rule_list=["rule_of_leadlike_soft"])(mols=candidates, n_jobs=-1)
nibr_df = mc.structural.NIBRFilters()(mols=candidates, n_jobs=-1)
complex_mask = mc.functional.complexity_filter(
    mols=candidates, complexity_metric="bertz", limit="95", n_jobs=-1
)

passes = (
    rules_df["pass_all"]
    & nibr_df["pass_filter"]
    & complex_mask
)

模式 3：检测官能团

import medchem as mc

group = mc.groups.ChemicalGroup(groups=["common_warhead_covalent_inhibitors"])
matches = [group.has_match(mol) for mol in mol_list]
warhead_mols = [mol for mol, m in zip(mol_list, matches) if m]

最佳实践

1. 上下文很重要——市售药物常常违反 Ro5；前药和天然产物是常见例外。
2. 组合使用筛选条件——规则、警示目录和复杂度阈值结合使用效果最佳。
3. 使用并行化——对于超过 1000 个分子的库，传入 n_jobs=-1。
4. 检查返回类型——RuleFilters 和结构类返回 DataFrame；功能辅助函数返回布尔数组。
5. Lilly 扣分项为可选——需单独安装 lilly-medchem-rules；功能 API 中的默认最大扣分值为 160。
6. 记录决策——保留 status、reasons 和 severity 列以供审计追踪。

资源

references/api_guide.md

按模块整理的 API 参考，包含签名、返回类型和使用模式。

references/rules_catalog.md

可用规则、警示集、复杂度指标和筛选条件选择指南目录。

scripts/filter_molecules.py

用于 CSV/TSV/SDF/SMILES 输入的批量筛选脚本，可配置规则、警示和复杂度阈值。

uv run python scripts/filter_molecules.py input.csv \
  --rules rule_of_five,rule_of_cns --pains --nibr --output filtered.csv

文档

• 官方文档：https://medchem-docs.datamol.io/
• GitHub：https://github.com/datamol-io/medchem
• PyPI：https://pypi.org/project/medchem/（2.0.5）

Agent 操作流程

1. **检查环境。**确认工具包版本和输入格式（SMILES、SDF、PDB、CIF），并在计算前对分子进行规范化处理。
2. **明确输入。**根据数据或用户确认格式、标识符和参数。对于任何会影响结果的值，应询问而非猜测。
3. **先运行小规模版本。**先处理少量分子或一个靶点，并检查输出。
4. 使用上述说明和参考资料执行完整任务。
5. **验证结果。**检查无效结构、单位一致性和预测模型的适用域。
6. **报告。**说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
分子解析或规范化失败	说明原因并跳过；绝不要悄悄丢弃或更改结构。
这些说明中的函数、标志或端点在已安装版本中不存在	查看已安装版本自己的文档（help()、--help、官方文档），进行调整并告知用户。绝不要虚构 API。
必需的输入、标识符或参数含糊不清	询问用户，或在运行前明确说明假设。

诚信规则

• 绝不捏造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，应如实说明。
• 计算预测是待验证的假设，不是实验结果；应明确标注。
• 此处与版本相关的细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须先征得同意。

相关技能

• datamol：通过 datamol Python 库（import datamol as dm）封装 RDKit，用于分子化学信息学，并返回原生 rdkit.Chem.Mol 对象…
• molfeat：使用 molfeat（0.11.0）将 SMILES 字符串或 RDKit/datamol 分子转换为数值特征；它提供计算器、scikit-learn…
• rdkit：介绍如何使用 RDKit（Python）读取和写入 SMILES、MOL/SDF 和 InChI，计算描述符（MW、LogP、TPSA），生成 Morgan/…