genomic-coordinates

基因组坐标

何时使用

每当坐标跨越边界时：在两种文件格式之间、两种工具之间、两个组装版本之间，或在基因组与转录本之间。

规则

一个坐标包含三个事实，而非一个：数值、采用的坐标约定，以及测量所依据的组装版本。 三者缺一不可，否则数值便无法解释。

坐标错误是基因组学中最隐蔽的一类错误。差一位的 BED 文件仍能解析、排序和求交，且不会报错。将 GRCh37 VCF 与 GRCh38 注释联接也会返回行。右移的插入缺失变异只会匹配不上 ClinVar 中的记录，结果就是把一个变异报告为新变异。没有任何错误提示；答案只是错了，而且错得看起来还很合理。

因此：按照表格进行转换，不要凭记忆，并且只要有参考序列，就要据此验证。

两种转换

1-based inclusive  ->  0-based half-open :  start - 1,  end
0-based half-open  ->  1-based inclusive :  start + 1,  end

结束坐标永远不会移动。如果转换改变了两个数值，那就是错的。

各种格式分别采用哪种约定

0 起始，半开区间	1 起始，闭区间
BED、bedGraph、bigWig、narrowPeak	GFF3、GTF、VCF
BAM/CRAM（二进制 POS）	SAM（文本 POS）
PSL、genePred、refFlat	WIG、Picard interval_list
MAF（UCSC 多序列比对）	MAF（TCGA 突变注释）
PyRanges、pybedtools	GRanges/IRanges、samtools、UCSC 和 Ensembl 区域字符串

两种 “MAF” 格式都存在，含义不同，表示方式也不一致。UCSC 通过采用 1 起始坐标的浏览器输入框提供 0 起始文件。references/format-conventions.md 列出了完整的格式对照表和各格式的详细信息。

cd skills/genomic-coordinates/scripts

python3 convert_coords.py --list                          # the table
python3 convert_coords.py --from bed --to gff chr1 999 1000
python3 convert_coords.py --from ucsc --to bed "chr7:5,530,601-5,530,625"
python3 convert_coords.py --from granges --to pyranges --input regions.tsv

contig  input                 output           length  status  detail
chr7    chr7:5530601-5530625  5530600-5530625  25      ok

零长度 BED 特征（chromStart == chromEnd，表示合法的插入点）会被报告为 unrepresentable，而不会转换为 end = start - 1。如果存在任何退化或无效区间，退出代码为 1。

变异不是区间

对于插入缺失变异，VCF 中的 POS 是锚定碱基——事件发生之前的碱基，且该碱基本身未发生改变。同一个变异可以有多种写法：chr1:7:CAC:C、chr1:3:CAC:C 和 chr1:2:GCA:G 表示同一个缺失。在规范化之前联接、去重或查询变异，会悄无声息地丢失真实匹配；而且在插入缺失变异集中的重复序列区域，丢失的匹配会更多。

进行任何比较之前，先规范化——精简表示形式，然后根据参考序列向左对齐：

python3 normalize_variant.py --fasta ref.fa chr1 7 CAC C
python3 normalize_variant.py --fasta ref.fa --split --input cohort.vcf
python3 normalize_variant.py --fasta ref.fa --compare chr1:7:CAC:C chr1:2:GCA:G

input         normalized    type      pos_shift  ref_check  changed
chr1:7:CAC:C  chr1:2:GCA:G  deletion  5          ok         yes

首先会检查每条记录的 REF 是否与 FASTA 一致。MISMATCH 表示变异与参考序列来自不同的组装版本——请停止操作并运行 check_contigs.py，不要调整坐标。多等位记录必须在规范化之前使用 --split 拆分，绝不能在规范化之后拆分。

HGVS 会将插入缺失变异朝相反方向移动，即沿转录本向 3' 端移动。对于负链基因，这与 VCF 向左对齐的基因组方向相反。详情和完整流程：references/variant-representation.md。

信任联接结果前先检查组装版本

python3 check_contigs.py --identify unknown.fa.fai
python3 check_contigs.py variants.vcf annotation.gtf --genome GRCh38.fa.fai

file          kind    contigs  naming        assembly  detail
ref.fa.fai    sizes   25       plain         GRCh37    24/24 primary chromosome lengths match;
                                                       chrM is 16569 bp, i.e. GRCh37/38 (rCRS MT)

该脚本会读取 .fai、.chrom.sizes、VCF 头部、SAM 头部、FASTA、BED 和 GTF/GFF，根据主染色体长度识别组装版本，并报告两个文件联接时可能出错的所有原因：命名不匹配、长度冲突、坐标超出 contig 末端，以及只存在于一个文件中的 contig。任何不兼容情况都会导致退出代码为 1。

GRCh37 和 hg19 仅线粒体不同——rCRS 长度分别为 16,569 bp 和 16,571 bp。核基因组坐标完全一致，因此混用的流水线仍可正常运行，只有 mtDNA 结果会出错。check_contigs.py 会报告识别到的组装版本。有关组装版本、命名方案、ALT contig 和 liftover 陷阱的信息，请参阅：references/reference-builds.md。

根据文件自身的格式进行审计

python3 audit_intervals.py peaks.bed
python3 audit_intervals.py gencode.gtf --genome hg38.chrom.sizes
python3 audit_intervals.py cohort.vcf --genome GRCh38.fa.fai

查找坐标错误留下的证据：

发现	证明的情况
GFF/GTF 中的 start_below_one	以 1 为起点的文件中存在 0 起点数据；所有坐标都向左偏移了一个碱基
BED 中的 many_zero_length	以 0 为起点的文件中写入了以 1 为起点的单碱基特征
past_contig_end	参考基因组版本错误，或 contig 边界处存在偏移一个碱基的错误
mixed_contig_naming	任何连接都会悄无声息地只匹配其中一个子集
first_block_offset	BED12 的 blockStarts 写成了绝对坐标
not_parsimonious	等位基因未修剪；连接前先进行标准化
bad_alt_allele	VCF 中使用了 Ensembl/VEP 的 - 表示法，而 VCF 不允许缺少锚定碱基

出现任何致命问题时，退出代码为 1，因此可用作数据目录的 CI 门禁。

转录本、CDS 和蛋白质位置

c.742 和 chr17:7,674,220 都表示“位置”，但两者无法通过算术运算互相转换。转录本坐标按转录方向计算剪接后的碱基；在负链上，基因组坐标递减；而 c.1 指的是起始 ATG 中的 A，不是转录本的起始位置。

容易记错的规则包括：不存在 c.0；5' UTR 位置为负数，3' UTR 位置带有 *；GFF phase 表示到达下一个密码子时需要移除的碱基数，而不是 start % 3；并且，如果没有带版本号的转录本登录号，c. 描述就毫无意义，因为同一变异在不同转录本中的编号各不相同。references/transcript-coordinates.md 中介绍了转换步骤和边界情况。

请使用包含转录本模型的工具进行转换——VEP、bcftools csq、Mutalyzer、hgvs 包——不要手动转换。

报告结果

每次都要在坐标旁注明参考基因组版本。 chr7:5,530,601-5,530,625 不是一个完整的位置；chr7:5,530,601-5,530,625 (GRCh38) 才是。请在列标题或文件文档中注明坐标列使用的约定。进行转换后，请注明转换方向。

参考资料

• references/format-conventions.md — 各格式采用的坐标约定及其详细说明、BED12 区块规则、区域字符串语法和工具行为。
• references/variant-representation.md — VCF 等位基因约定、标准化算法、等价性检查、多等位基因拆分，以及 HGVS 与 VCF 的差异。
• references/reference-builds.md — 参考基因组版本特征、GRCh37 与 hg19 的区别、ALT contig、命名方案和 liftover 失败模式。
• references/transcript-coordinates.md — 基因组 ↔ 转录本 ↔ CDS ↔ 蛋白质坐标、HGVS 编号、phase 和转录本选择。

Agent 操作流程

1. 检查环境。 确认网络访问、API 密钥（如有需要），以及数据库当前的 API 文档和速率限制。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。对于会改变结果的任何值，应先询问，不要猜测。
3. 先运行小规模版本。 获取一条已知记录，并在批量查询前检查响应格式。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 确认标识符可解析、报告记录数量，并记录数据库版本或访问日期。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果发生这种情况	请这样做
出现 HTTP 429 或 5xx 错误	采用退避策略遵守速率限制，分批请求，并如实报告部分结果。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），调整做法并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

诚信规则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请明确说明。
• 切勿编造登录号、ID 或记录；未找到时请报告“未找到”。
• 将此处的版本特定细节视为可能过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，务必先征得同意。

相关技能

• polars-bio：用于基因组区间操作和在 Polars DataFrame 上进行生物信息学文件 I/O 的 Python 库 polars-bio，基于 Arrow 和 DataFusion 构建。
• gtars：使用 Gtars（用于基因组区间的 Rust/Python/CLI 工具包）检查并规划工作：BED RegionSet 集合代数运算（reduce、setdiff、intersec…
• geniml：使用 Geniml（0.8.4）和 Gtars 规划并审计本地基因组区间机器学习工作流：根据染色体大小验证 BED 文件…