alterlab-zinc-db

ZINC 数据库

概述

ZINC 是由 UCSF 维护的开放存取数据库，收录了 2.3 亿多种可购买化合物。可按 ZINC ID 或 SMILES 搜索、执行相似性搜索、下载可用于对接的 3D 结构，以及发现用于虚拟筛选和药物发现的类似物。

脚本

scripts/query_zinc.py — 通过表单编码的 POST 请求调用 ZINC22 CartBlanche API（仅使用标准库，向 stdout 输出 JSON）：

python scripts/query_zinc.py id ZINC000019632618 --wait     # ZINC-ID lookup, rows as JSON
python scripts/query_zinc.py random --count 100 --subset lead-like   # returns a task id
python scripts/query_zinc.py result <task-id>               # fetch that task's rows later

CartBlanche 的所有搜索都是异步的。 每次调用都会返回一个 JSON 任务句柄 （{"task": "<uuid>"}）。轮询 GET https://cartblanche22.docking.org/search/result/<task>： 任务运行时会返回 {"status": "PENDING", "progress": ...}， 完成后则返回 {"status": "SUCCESS", "result": {...}}。结果按来源分组 （zinc22、zinc20），未匹配的查询会列在 missing / zinc22_missing 下 （--wait 会执行轮询）。ID 查询可在几秒内完成；随机抽样则可能持续处于 PENDING 状态数分钟。

已知问题（已于 2026-09-23 验证）： smiles.txt 任务会立即完成，并返回 "zinc22_missing": [""]——服务器收不到查询内容，无论 SMILES 是以内嵌值、表单上传 还是文件的形式发送。在此问题修复前，请在 CartBlanche22 网页界面、SmallWorld （https://sw.docking.org，该站点索引 ZINC20/ZINC22 版本）或 Arthor （https://arthor.docking.org）中执行相似性搜索；并应如实说明这一点，而不是报告“未找到类似物”。

何时使用此技能

在以下情况应使用此技能：

• 虚拟筛选：为分子对接研究寻找化合物
• 先导发现：寻找可用于药物开发的市售化合物
• 结构搜索：按 SMILES 执行相似性或类似物搜索
• 化合物检索：按 ZINC ID 或供应商代码查找分子
• 化学空间探索：探索可购买化合物的多样性
• 对接研究：获取可用于对接的 3D 分子结构
• 类似物搜索：根据结构相似性查找相似化合物
• 供应商查询：查找特定化学品供应商提供的化合物
• 随机抽样：获取用于筛选的随机化合物集

不适用的情况

场景	改用
已知分子的化合物属性、同义词和生物测定数据	alterlab-pubchem
靶标的实测效力（IC50/Ki）	alterlab-chembl
将配体对接到蛋白质结合口袋	alterlab-diffdock
在本地计算描述符、筛选条件或指纹	alterlab-rdkit
对化合物库应用药物化学筛选规则（PAINS、经验规则）	alterlab-medchem

数据库版本

ZINC 已历经多个版本：

• ZINC22（当前版本）：规模最大，包含 2.3 亿多种可购买化合物，以及数十亿规模的按需合成化合物
• ZINC20：仍在维护，侧重于先导样和药物样化合物
• ZINC15：前代版本，已过时但仍有文档记录

此技能主要介绍最新、最全面的版本 ZINC22。

访问方式

Web 界面

主要访问入口：https://cartblanche22.docking.org/（zinc22.docking.org 会重定向至此） 旧版 ZINC20/ZINC15 页面（zinc.docking.org、zinc20.docking.org、zinc15.docking.org）现在 会对脚本请求返回验证码重定向，仅适合交互式使用。

API 访问

所有 ZINC22 搜索都可以通过 CartBlanche22 API 以编程方式执行：

基础 URL：https://cartblanche22.docking.org/

搜索通过表单编码的 POST 请求提交（scripts/query_zinc.py 辅助脚本使用此方式），也可以通过 curl -F 上传表单字段。端点接受内嵌值或 @file 文件上传，且每次搜索都会返回 JSON 任务句柄 （{"task": "<uuid>"}）——随后可在网页界面查看结果。通过 output_fields 表单字段传入所需列。

旧版“冒号 URL”格式（/substances.txt:zinc_id=...）无法用于当前的 CartBlanche22 服务； 请按下方所示使用表单字段。

核心功能

1. 按 ZINC ID 搜索

使用 ZINC 标识符检索特定化合物。

Web 界面：https://cartblanche22.docking.org/search/zincid

API 端点（表单字段为 zinc_ids，复数形式——单数形式 zinc_id 会返回 HTTP 400）：

# Inline list of IDs
curl -X GET "https://cartblanche22.docking.org/substances.txt" \
  -F zinc_ids="ZINC000019632618,ZINC000000000001" \
  -F output_fields="zinc_id,smiles,catalogs"

# Or upload a file of IDs (one per line)
curl -X GET "https://cartblanche22.docking.org/substances.txt" \
  -F zinc_ids=@zinc_ids.txt \
  -F output_fields="zinc_id,smiles,tranche"

两者都会返回一个任务句柄；打开打印出的 UI 任务 URL 即可查看数据行。

响应字段：zinc_id、smiles、sub_id、supplier_code、catalogs、tranche（包含 H 数量、LogP、MW、阶段）

2. 按 SMILES 搜索

使用 SMILES 表示法按化学结构查找化合物，还可选择距离参数来搜索类似物。

Web 界面：https://cartblanche22.docking.org/search/smiles

API 端点：

curl -X GET "https://cartblanche22.docking.org/smiles.txt" \
  -F smiles="c1ccccc1" -F dist=3 -F adist=3 \
  -F output_fields="zinc_id,smiles,tranche"

参数（均通过 -F 表单字段传递）：

• smiles：查询 SMILES 字符串（直接填写，或使用 @file 批量查询）
• dist：Tanimoto 距离阈值（默认值：0，即精确匹配）
• adist：匿名（图拓扑）距离，用于更广泛的搜索（默认值：0）
• output_fields：所需输出字段的逗号分隔列表

示例 - 精确匹配（dist/adist 默认为 0）：

curl -X GET "https://cartblanche22.docking.org/smiles.txt" -F smiles="c1ccccc1"

3. 按供应商代码搜索

查询特定化学品供应商的化合物，或检索特定目录中的所有分子。

Web 界面：https://cartblanche22.docking.org/search/catitems

API 端点（表单字段为 supplier_codes）：

curl -X GET "https://cartblanche22.docking.org/catitems.txt" \
  -F supplier_codes="SUPPLIER-CODE-123" \
  -F output_fields="zinc_id,smiles,supplier_code,catalogs"

使用场景：

• 确认特定供应商是否提供某种化合物
• 检索某个目录中的所有化合物
• 将供应商代码与 ZINC ID 交叉比对

4. 随机抽样化合物

生成随机化合物集，用于筛选或基准测试。

Web 界面：https://cartblanche22.docking.org/search/random

API 端点：

curl "https://cartblanche22.docking.org/substance/random.txt" -F count=100

参数（均通过 -F 表单字段传递）：

• count：要检索的随机化合物数量（默认值：100）
• subset：按子集筛选（例如，'lead-like'、'drug-like'、'fragment'）
• output_fields：自定义返回的数据字段

示例 - 随机抽取 lead-like 分子：

curl "https://cartblanche22.docking.org/substance/random.txt" \
  -F count=1000 -F subset="lead-like" -F output_fields="zinc_id,smiles,tranche"

常见工作流

工作流 1：准备对接化合物库

1. 根据目标属性或所需化学空间确定搜索条件

2. 使用适当的方法提交搜索：

   # Example: random drug-like compounds; returns a task handle for the web UI
   python scripts/query_zinc.py random --count 10000 --subset drug-like \
     --fields zinc_id,smiles,tranche
   

3. 检索并解析数据行（使用 python scripts/query_zinc.py result <task>、从 UI 任务视图导出，或从批量存储库获取 tranche 文件），将其导入 DataFrame，并按 tranche 属性筛选：

   import pandas as pd
   
   df = pd.read_csv('docking_library.tsv', sep='\t')
   
   # Tranche format: H##P###M###-phase
   # H = H-bond donors, P = LogP*10, M = MW
   

4. 从文件存储库下载用于对接的 3D 结构（见下文）

工作流 2：查找命中化合物的类似物

1. 获取命中化合物的 SMILES：

   hit_smiles = "CC(C)Cc1ccc(cc1)C(C)C(=O)O"  # Example: Ibuprofen
   

2. 使用距离阈值进行相似性搜索——在上述 smiles.txt API 问题解决之前，请在 CartBlanche22 UI 或 SmallWorld（https://sw.docking.org）中进行搜索并导出命中结果；问题修复后，可使用以下脚本形式：

   python scripts/query_zinc.py smiles "CC(C)Cc1ccc(cc1)C(C)C(=O)O" \
     --dist 5 --fields zinc_id,smiles,catalogs --wait
   

3. 分析结果，找出可购买的类似物（导出任务数据行后）：

   import pandas as pd
   
   analogs = pd.read_csv('analogs.tsv', sep='\t')
   print(f"Found {len(analogs)} analogs")
   print(analogs[['zinc_id', 'smiles', 'catalogs']].head(10))
   

4. 获取最有前景类似物的 3D 结构

工作流 3：批量检索化合物

1. 汇总 ZINC ID 列表，来源可以是文献、数据库或之前的筛选：

   zinc_ids = [
       "ZINC000000000001",
       "ZINC000000000002",
       "ZINC000000000003"
   ]
   zinc_ids_str = ",".join(zinc_ids)
   

2. 查询 ZINC22 API（一次批量请求，使用复数形式 zinc_ids）：

   curl -X GET "https://cartblanche22.docking.org/substances.txt" \
     -F zinc_ids="ZINC000000000001,ZINC000000000002" \
     -F output_fields="zinc_id,smiles,supplier_code,catalogs"
   

3. 处理结果，用于后续分析或采购

工作流 4：化学空间抽样

1. 根据筛选目标选择子集参数：

   • Fragment：MW < 250，适用于基于片段的药物发现
   • Lead-like：MW 250-350，LogP ≤ 3.5
   • Drug-like：MW 350-500，符合 Lipinski 五规则

2. 生成随机样本：

   python scripts/query_zinc.py random --count 5000 --subset lead-like \
     --fields zinc_id,smiles,tranche
   

3. 分析化学多样性并为虚拟筛选做好准备

输出字段

使用 output_fields 参数自定义 API 响应：

可用字段：

• zinc_id：ZINC 标识符
• smiles：SMILES 字符串表示
• sub_id：内部物质 ID
• supplier_code：供应商目录编号
• catalogs：提供该化合物的供应商列表
• tranche：编码后的分子属性（氢原子数、LogP、分子量、反应性阶段）

示例：

curl -X GET "https://cartblanche22.docking.org/substances.txt" \
  -F zinc_ids="ZINC000000000001" \
  -F output_fields="zinc_id,smiles,catalogs,tranche"

Tranche 系统

ZINC 根据分子属性将化合物归入不同的“tranche”：

格式：H##P###M###-phase

• H##：氢键供体数量（00-99）
• P###：LogP × 10（例如，P035 = LogP 3.5）
• M###：分子量，单位为道尔顿（例如，M400 = 400 Da）
• phase：反应性分类

示例 tranche：H05P035M400-0

• 5 个氢键供体
• LogP = 3.5
• 分子量 = 400 Da
• 反应性阶段 0

使用 tranche 数据，按类药性标准筛选化合物。

下载 3D 结构

分子对接所需的 3D 结构可通过文件存储库获取：

文件存储库：https://files.docking.org/zinc22/

结构按 tranche 分类，并提供多种格式：

• MOL2：包含 3D 坐标的多分子格式
• SDF：结构数据文件格式
• DB2.GZ：用于 DOCK 的压缩数据库格式

请参阅 ZINC 文档 https://wiki.docking.org，了解下载协议和批量访问方法。

Python 集成

提交搜索

请使用随附的 scripts/query_zinc.py（仅依赖标准库），而不要自行拼接 URL — 它会发送正确的表单编码 POST 请求，并返回 JSON 任务句柄：

import json, subprocess

def submit(*args):
    """Run query_zinc.py and return the parsed JSON (task handle or rows)."""
    out = subprocess.run(
        ["python", "scripts/query_zinc.py", *args],
        capture_output=True, text=True, check=True,
    ).stdout
    return json.loads(out)

state = submit("id", "ZINC000019632618", "--fields", "zinc_id,smiles,catalogs", "--wait")
rows = state["result"].get("zinc22") or state["result"].get("zinc20") or []

解析 tranche 代码

获取结果行后（包含 tranche 列，可从界面导出或从文件存储库读取），即可解码每个代码。LogP 段可能为负值（P-005），因此正则表达式允许有前导符号：

import re

def parse_tranche(tranche_str):
    """Parse a ZINC tranche code, e.g. 'H05P035M400-0'."""
    match = re.match(r"H(\d+)P(-?\d+)M(\d+)-(\d+)", tranche_str)
    if not match:
        return None
    return {
        "h_donors": int(match.group(1)),
        "logp": int(match.group(2)) / 10.0,
        "mw": int(match.group(3)),
        "phase": int(match.group(4)),
    }

# df["tranche_props"] = df["tranche"].apply(parse_tranche)

最佳实践

查询优化

• 从具体条件开始：先进行精确搜索，再扩大到相似性搜索
• 使用适当的距离参数：对于相近类似物，使用较小的 dist 值（1-3）；对于多样化类似物，使用较大的值（5-10）
• 限制输出字段：仅请求必要字段，以减少数据传输
• 批量查询：尽可能在单个 API 调用中组合多个 ZINC ID

性能注意事项

• 速率限制：尊重服务端资源；避免短时间内连续发送请求
• 缓存：在本地存储常用化合物
• 并行下载：下载 3D 结构时，可使用并行 wget 或 aria2c 访问文件存储库
• 子集筛选：使用先导样化合物、类药化合物或片段子集，以缩小搜索范围

数据质量

• 确认可用性：供应商目录可能会变更；大批量订购前请确认化合物是否有货
• 检查立体化学：SMILES 可能无法完整指定立体化学；请核验 3D 结构
• 验证结构：使用化学信息学工具（RDKit、OpenBabel）验证结构有效性
• 交叉参考：条件允许时，请与其他数据库（PubChem、ChEMBL）交叉核验

资源

references/api_reference.md

完整文档，包括：

• 完整的 API 端点参考
• URL 语法和参数规范
• 高级查询模式和示例
• 文件存储库的组织方式和访问方法
• 批量下载方法
• 错误处理和故障排查
• 与分子对接软件的集成

如需详细技术信息和高级用法模式，请参阅本文档。

重要免责声明

数据可靠性

ZINC 明确声明：“我们不保证任何分子适用于任何用途的质量，也不对因使用此数据库而产生的错误承担责任。”

• 化合物的可用性可能会在未通知的情况下发生变化
• 结构表示可能包含错误
• 应独立核实供应商信息
• 实验前应进行适当验证

适用范围

• ZINC 旨在用于药物发现领域的学术和研究目的
• 商业使用前请确认许可条款
• 研究已获专利的化合物时，请尊重知识产权
• 获取化合物时，请遵循所在机构的相关指南

其他资源

• CartBlanche22 界面：https://cartblanche22.docking.org/
• SmallWorld / Arthor 相似性搜索：https://sw.docking.org, https://arthor.docking.org
• ZINC Wiki：https://wiki.docking.org/
• 文件存储库：https://files.docking.org/zinc22/
• GitHub：https://github.com/docking-org/
• 主要出版物：Tingle 等，J. Chem. Inf. Model. 2023（ZINC22）；Irwin 等，J. Chem. Inf. Model. 2020（ZINC20）；Sterling 和 Irwin，J. Chem. Inf. Model. 2015（ZINC15）

引用

在出版物中使用 ZINC 时，请引用相应版本：

ZINC22： Tingle, B. I.; Tang, K. G.; Castanon, M.; Gutierrez, J. J.; Khurelbaatar, M.; Dandarchuluun, C.; Moroz, Y. S.; Irwin, J. J. "ZINC-22─A Free Multi-Billion-Scale Database of Tangible Compounds for Ligand Discovery." Journal of Chemical Information and Modeling 2023, 63(4), 1166–1176. DOI: 10.1021/acs.jcim.2c01253.

ZINC20： Irwin, J. J.; Tang, K. G.; Young, J.; et al. "ZINC20—A Free Ultralarge-Scale Chemical Database for Ligand Discovery." Journal of Chemical Information and Modeling 2020, 60(12), 6065–6073. DOI: 10.1021/acs.jcim.0c00675.

ZINC15： Sterling, T.; Irwin, J. J. "ZINC 15 – Ligand Discovery for Everyone." Journal of Chemical Information and Modeling 2015, 55, 2324–2337. DOI: 10.1021/acs.jcim.5b00559.