encode-ccres-database

ENCODE 数据库技能

此技能支持通过 SCREEN GraphQL API 查询 ENCODE cCRE（候选顺式调控元件）注册库。它通过分析生化特征（DNase、H3K4me3、H3K27ac、CTCF），帮助识别具有功能的非编码 DNA 元件（如启动子、增强子和绝缘子）。

前提条件

1. uv：阅读 uv 技能，并按照其中的设置说明确保已安装 uv 且其路径已添加到 PATH。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/encode_ccres_database_LICENSE.txt，则 (1) 显著提醒用户查看 https://www.encodeproject.org/help/rest-api/ 上的条款，然后 (2) 创建该文件，记录通知文本和时间戳。

核心规则

• 使用封装脚本：查询数据库时，始终执行提供的辅助脚本，不要直接访问数据库。这些脚本会自动妥善执行所需的速率限制。
• 解析输出：不要使用 cat 将整个 JSON 输出文件读入上下文，因为文件可能非常大。必须使用 jq 高效解析并提取相关字段。
• 通知：如果使用此技能，确保在输出中提及。

快速开始

# Search cCREs by coordinates
uv run scripts/screen_api.py search --chromosome chr11 \
  --start 5205263 --end 5207263 \
  --output /tmp/search.json

# Get details for a specific cCRE
uv run scripts/screen_api.py details EH38E2941922 \
  --output /tmp/details.json

所有子命令都会将 JSON 写入磁盘。始终将输出保存在 /tmp/ 等临时位置。

识别高置信度（“Type A”）生物样本

ENCODE 中的生物样本通常根据数据完整性进行分类。“Type A”（或高置信度）生物样本，是指具有全部四种核心表观遗传标记实验数据的样本：DNase、H3K4me3、H3K27ac 和 CTCF。

biosamples 和 details 命令会自动为每个生物样本的输出添加一个 is_type_a 布尔标记。

示例：查找高置信度细胞类型

uv run scripts/screen_api.py biosamples --output /tmp/biosamples.json
# Use jq to filter for Type A biosamples
jq '.data.ccREBiosampleQuery.biosamples[] | select(.is_type_a == true) | .displayname' /tmp/biosamples.json

解析输出（重要）

不要使用 cat 将整个 JSON 输出文件读入上下文，
**因为文件可能非常大。**请改用 jq，高效解析并提取脚本保存的 JSON 文件中的相关字段。如果系统中没有 jq，请编写自己的 Python 筛选代码（例如，python3 -c "import json..."）提取所需数据。

如需了解各命令返回的 JSON 结构的完整参考（以便知道要用 jq 查询哪些字段），请阅读 references/json_output_structure.md。

可用命令

• search：按坐标、登录号或表观遗传信号搜索 cCRE。

  uv run scripts/screen_api.py search \
      --chromosome chr11 --start 5205263 --end 5207263 \
      --output /tmp/search.json
  

• nearby-genes：查找指定 cCRE 登录号附近的基因。

  uv run scripts/screen_api.py nearby-genes \
      EH38E1516972 --output /tmp/nearby.json
  

• details：获取特定 cCRE 的详细信息和生物样本特异性最大 Z 分数。

  uv run scripts/screen_api.py details EH38E2941922 \
      --output /tmp/details.json
  

• biosamples：获取某个组装版本的生物样本元数据。

  uv run scripts/screen_api.py biosamples \
      --output /tmp/biosamples.json
  

• orthologs：获取另一组装版本中的直系同源 cCRE。

  uv run scripts/screen_api.py orthologs EH38E2941922 \
      --output /tmp/orthologs.json
  

• linked-genes：通过 HiC 或 eQTL 等方法查找关联基因。

  uv run scripts/screen_api.py linked-genes \
      EH38E1516972 --output /tmp/linked.json
  

• gene-expression：获取指定基因在所有生物样本中的基因表达量（TPM）。该命令会在内部将基因符号解析为 Ensembl 基因 ID，然后查询各生物样本的 RNA-seq 定量结果。

  uv run scripts/screen_api.py gene-expression GAPDH \
      --output /tmp/gene_expr.json
  

• entex：获取某个 cCRE 或基因组区域的 ENTEx 数据。

  uv run scripts/screen_api.py entex \
      --accession EH38E1310345 \
      --output /tmp/entex.json
  

  uv run scripts/screen_api.py entex \
      --region chr1:1000068:1000409 \
      --output /tmp/entex.json
  

• gwas：查询全基因组关联研究、SNP 或富集数据。

  uv run scripts/screen_api.py gwas studies \
      --output /tmp/gwas.json
  

  uv run scripts/screen_api.py gwas snps --study \
      Ahola-Olli_AV-27989323-Eotaxin_levels \
      --output /tmp/gwas_snps.json
  

大多数命令都可以通过 --assembly mm10 或 --assembly grch38 标志显式指定组装版本。默认情况下，脚本使用 grch38，但如果未找到结果或查询失败，则会自动回退到 mm10。

ENCODE Portal REST API（直接访问）

若要访问 SCREEN 中未表示为 cCRE 的原始实验、ChIP-seq 峰或其他数据集，请使用 scripts/encode_portal_api.py 脚本。它支持对 ENCODE Portal REST API 进行自定义查询。

用法

uv run scripts/encode_portal_api.py search "type=Experiment&target.label=ZNF549" --output /tmp/znf549_experiments.json

数据分析技巧

分析从 ENCODE 下载的 .bed 或 .bigBed 文件时，强烈建议使用标准生物信息学工具来查找重叠区域（例如基因启动子与峰之间的重叠）：

• bedtools：对基因组区间进行快速数学运算。
• bigBedToBed：将二进制 BigBed 文件转换为可读的 BED 格式。
• pybedtools：bedtools 的 Python 封装。

如果这些工具未预先安装，请编写自定义逻辑。

自定义查询（SCREEN GraphQL）

如果需要执行脚本不支持的复杂 GraphQL 查询，请阅读 references/graphql_schema.md，了解 SCREEN GraphQL API 中可用的查询、参数和返回字段。