查询 ENCODE 调控元件与实验数据时，用封装脚本加…

需要查询人类/小鼠细胞类型的候选顺式调控元件（cCRE）注释或 ENCODE Portal 原始实验数据（如 ChIP-seq peaks）时使用。

适用场景

解决思路

1. 先阅读 uv 技能并按其 Setup 说明安装 uv，确保 uv 在 PATH 中。
2. 若工作区根目录不存在 .licenses/encode_ccres_database_LICENSE.txt，则先显著提醒用户查看 https://www.encodeproject.org/help/rest-api/ 的条款，然后创建该文件记录通知文本和时间戳。
3. 始终通过提供的封装脚本查询数据库，不要直接访问数据库，脚本会自动优雅地执行速率限制。
4. 不要用 cat 把整个 JSON 输出读入上下文（文件可能极大），必须用 jq 提取相关字段；若系统没有 jq，则写自己的 Python 过滤代码（如 python3 -c "import json..."）提取数据。
5. 把所有子命令的 JSON 输出保存到临时位置（如 /tmp/）。
6. 用 search 子命令按坐标、accession 或表观遗传信号搜索 cCRE：uv run scripts/screen_api.py search --chromosome chr11 --start 5205263 --end 5207263 --output /tmp/search.json。
7. 用 details 子命令获取某个 cCRE 的详细信息及各 biosample 的最大 Z-score：uv run scripts/screen_api.py details EH38E2941922 --output /tmp/details.json。
8. 用 nearby-genes 子命令查找给定 cCRE accession 附近的基因：uv run scripts/screen_api.py nearby-genes EH38E1516972 --output /tmp/nearby.json。
9. 用 biosamples 子命令获取某个 assembly 的 biosample 元数据：uv run scripts/screen_api.py biosamples --output /tmp/biosamples.json。
10. 识别高置信度（Type A）biosample：Type A 指对 DNase、H3K4me3、H3K27ac、CTCF 四种核心表观遗传标记都有实验数据的 biosample；biosamples 和 details 命令会自动为每个 biosample 输出 is_type_a 布尔标志，可用 jq '.data.ccREBiosampleQuery.biosamples[] | select(.is_type_a == true) | .displayname' /tmp/biosamples.json 过滤。
11. 用 orthologs 子命令获取另一 assembly 中的直系同源 cCRE：uv run scripts/screen_api.py orthologs EH38E2941922 --output /tmp/orthologs.json。
12. 用 linked-genes 子命令通过 HiC 或 eQTL 等方法查找关联基因：uv run scripts/screen_api.py linked-genes EH38E1516972 --output /tmp/linked.json。
13. 用 gene-expression 子命令获取某基因在所有 biosample 中的表达（TPM），它会先把基因符号解析为 Ensembl gene ID，再查询各 biosample 的 RNA-seq 定量：uv run scripts/screen_api.py gene-expression GAPDH --output /tmp/gene_expr.json。
14. 用 entex 子命令按 accession 或基因组区域获取 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。
15. 用 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。
16. 大多数命令可加 --assembly mm10 或 --assembly grch38 显式指定 assembly；默认目标是 grch38，若无结果或查询失败会自动回退到 mm10。
17. 需要原始实验、ChIP-seq peaks 或其他未在 SCREEN 中表示为 cCRE 的数据集时，用 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。
18. 分析从 ENCODE 下载的 .bed 或 .bigBed 文件时，用标准生物信息学工具找重叠（如基因启动子与 peaks 之间）：bedtools 做基因组区间的快速数学运算，bigBedToBed 把二进制 BigBed 转为可读 BED，pybedtools 是 bedtools 的 Python 封装；若这些工具未预装则写自定义逻辑。
19. 若需要脚本不支持的复杂 GraphQL 查询，阅读 references/graphql_schema.md 了解 SCREEN GraphQL API 可用的查询、参数和返回字段。
20. 若使用本技能，确保在输出中提及。
21. 需要了解各命令返回的 JSON 结构（以便知道用 jq 查哪些字段）时，阅读 references/json_output_structure.md。

适用边界 · 注意事项

• 需要查询的原始实验数据或数据集未在 SCREEN 中表示为 cCRE 时，不要用 SCREEN GraphQL 路径，应改用 ENCODE Portal REST API 脚本。
• 未安装 uv 或未完成其 Setup 时不要执行封装脚本。
• 未先提醒用户查看 ENCODE REST API 条款并创建许可记录文件前，不要开始查询。