unibind-database

UniBind 数据库技能

UniBind 是一个收录 9 个物种中直接 TF–DNA 相互作用的数据库，通过 DAMO 框架整合了 ChIP-seq 峰与 JASPAR TF 结合谱。

前置条件

1. uv：阅读 uv 技能，并按照其设置说明确保已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/unibind_database_LICENSE.txt，则 (1) 显著提醒用户查看 https://unibind.uio.no/ 和 https://unibind.uio.no/api/overview 上的条款，然后 (2) 创建文件，记录通知文本和时间戳。

快速开始

查询命令默认将 JSON 输出到 stdout。大多数输出都足够精简，可直接阅读。对于较大的输出（list_cell_lines、list_tfs），请通过 jq 提取所需字段。

uv run <SKILL DIR>/scripts/unibind_api.py list_species

download_tfbs 命令会改为将 BED/FASTA 文件写入 --output-dir。如有需要，也可以在任何查询命令中使用 --output <path> 将结果保存到文件。

核心规则

• 使用封装脚本：查询数据库时，务必始终执行提供的辅助脚本，而不是直接访问数据库。这些脚本会自动妥善遵守所需的速率限制。
• 输出：查询命令会将 JSON 输出到 stdout。大多数响应都很精简，可直接阅读。
• 大型结果：list_cell_lines 和 list_tfs 会生成较大的输出。请通过 jq 提取特定字段，而不要将完整输出读入上下文。
• 保存到文件：需要稍后引用数据或使用 jq 处理非常大的结果时，请使用 --output <path>。
• 分页：使用 --page 和 --page-size（最大值为 1000）对大型结果集进行分块。
• 排序：在任何列表命令中使用 --order field_name（降序时在前面加 -）。
• 通知：如果使用了此技能，请确保在输出中提及。

实用脚本

将 <SKILL DIR> 替换为此技能目录的绝对路径。

1. 列出物种

uv run <SKILL DIR>/scripts/unibind_api.py list_species

2. 列出集合

uv run <SKILL DIR>/scripts/unibind_api.py list_collections

3. 列出细胞系和 TF（输出较大——使用 jp）

这些命令会返回大型数据集。使用 uvx --from jmespath jp 仅提取所需字段。

uv run <SKILL DIR>/scripts/unibind_api.py list_cell_lines | uvx --from jmespath jp "results[].name"
uv run <SKILL DIR>/scripts/unibind_api.py list_tfs | uvx --from jmespath jp "results[].tf_name"

4. 列出和筛选数据集（以及特定谱系数据集）

使用以下参数筛选数据集：

• --species（例如，“Homo sapiens”）
• --tf-name（例如，“CTCF”）
• --cell-line（例如，“mESC”）
• --collection（例如，Permissive、Robust）
• --search（搜索词）
• --biological-condition（生物条件或来源）
• --data-source（数据来源，例如，“ENCODE”）
• --has-pvalue（“true”或“false”）
• --identifier（例如，“GSE60130”）
• --jaspar-id（JASPAR 数据库谱矩阵 ID）
• --model（预测模型）
• --summary（摘要筛选条件）
• --threshold-pvalue（p 值阈值）

使用 list_datasets 查询标准数据集，或使用 list_specific_datasets 进行特定谱系查询。

uv run <SKILL DIR>/scripts/unibind_api.py list_datasets --species "Homo sapiens" --tf-name "CTCF" --data-source "ENCODE"
uv run <SKILL DIR>/scripts/unibind_api.py list_specific_datasets --species "Mus musculus" --cell-line "mESC"

5. 获取数据集详情

uv run <SKILL DIR>/scripts/unibind_api.py get_dataset "EXP047889.HMLE-Twist-ER_breast_cancer.SMAD3"

6. 下载 TFBS 文件（BED / FASTA）

将数据集的所有 TFBS 文件下载到本地目录。使用 --format bed（默认）或 --format fasta。

uv run <SKILL DIR>/scripts/unibind_api.py download_tfbs "EXP047889.HMLE-Twist-ER_breast_cancer.SMAD3" --output-dir /tmp/tfbs --format bed

反模式

• 不要尝试使用 UniBind API 查询特定的基因组区间、位置或基因。
• 不要猜测或虚构基因组坐标。如果要提取本地 BED 轨道，以便离线进行 bedtools 交集分析，请始终使用 ensembl-database 进行外部核验。
• 不要将其用于基序模型（PFM）。请改用 jaspar-database 技能。
• 不要将其用于基因表达数据。UniBind 仅存储结合事件。
• 不要仅凭数据集列表推断组织特异性表达。
• 不要使用 cat 将大型 JSON 输出文件读入上下文。输出文件太大。请使用 jq 或自行编写代码解析输出文件。