genomic-coordinates

用途

genomic-coordinates 用于处理基因组坐标跨越边界时的转换与校验，包括：两种文件格式之间、两个工具之间、两个装配版本之间，以及基因组与转录本之间。其核心规则是：一个坐标是三个事实，而非一个——数值、书写约定、以及测量所依据的装配版本。三者必须同时携带，否则数值无法解释。

坐标错误是基因组学中最安静的一类 bug。一个差一的 BED 文件可以正常解析、排序和求交集而不报错；一个 GRCh37 的 VCF 与 GRCh38 注释连接会返回行；一个右移的 indel 只是无法匹配 ClinVar 中的条目，结果被报告为新变异。没有任何错误被抛出，答案只是错了，而且错得看似合理。因此：用表格转换，不要凭记忆，并在有参考时对照参考验证。

主要能力

坐标转换

两种转换：

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

end 坐标永不移动。如果一次转换改变了两个数值，那就是错的。

格式约定归属：

0-based, half-open：BED、bedGraph、bigWig、narrowPeak；BAM/CRAM（二进制 POS）；PSL、genePred、refFlat；MAF（UCSC 多序列比对）；PyRanges、pybedtools
1-based, inclusive：GFF3、GTF、VCF；SAM（文本 POS）；WIG、Picard interval_list；MAF（TCGA 突变注释）；GRanges/IRanges、samtools & UCSC & Ensembl 区域字符串

两种 "MAF" 格式都存在，含义不同且互相矛盾。UCSC 通过 1-based 浏览器框提供 0-based 文件。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

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

变异表示规范化与比较

VCF 中 indel 的 POS 是锚定碱基——事件之前的碱基，本身不变。同一个变化可以写成多种形式：chr1:7:CAC:C、chr1:3:CAC:C 和 chr1:2:GCA:G 是同一个缺失。在规范化之前进行连接、去重或查找变异会静默丢失真实匹配，并且优先在重复区域丢失，而 indel 正集中于重复区域。

规范化——修剪至最简，然后对照参考左对齐——在任何比较之前进行：

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

每条记录的 REF 首先对照 FASTA 检查。MISMATCH 意味着变异与参考属于不同装配——应停止并运行 check_contigs.py，而不是调整坐标。多等位记录必须在规范化之前用 --split 拆分，绝不能在之后。

HGVS 将 indel 向相反方向移动，沿转录本 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

脚本读取 .fai、.chrom.sizes、VCF 头、SAM 头、FASTA、BED 和 GTF/GFF，从主染色体长度识别装配，并报告两个文件之间连接会出错的所有原因：命名不匹配、长度冲突、坐标超出 contig 末端、仅存在于一个文件中的 contig。任何不兼容时退出码为 1。

GRCh37 和 hg19 仅在线粒体上不同——16,569 bp（rCRS）对 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

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

start_below_one（GFF/GTF）：0-based 数据在 1-based 文件中；所有内容左移一个碱基
many_zero_length（BED）：1-based 单碱基特征写入 0-based 文件
past_contig_end：错误装配，或 contig 边缘的差一错误
mixed_contig_naming：任何连接都会静默匹配一个子集
first_block_offset：BED12 blockStarts 被写成绝对坐标
not_parsimonious：未修剪的等位基因；连接前需规范化
bad_alt_allele：VCF 中的 Ensembl/VEP - 表示法，没有锚定碱基

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

转录本、CDS 和蛋白质位置

c.742 和 chr17:7,674,220 都是 "位置"，但两者不能通过算术互相转换。转录本坐标按转录顺序计算剪接后的碱基——负链上基因组坐标递减——且 c.1 是起始 ATG 的 A，不是转录本的起始。

容易记错的规则：没有 c.0；5' UTR 位置为负数，3' UTR 位置带 *；GFF phase 是到达下一个密码子需移除的碱基数，不是 start % 3；没有带版本号的转录本 accession，c. 描述毫无意义，因为同一变异在每个转录本中编号不同。references/transcript-coordinates.md 有转换流程和边界情况。

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

使用方式

技能包含脚本目录 skills/genomic-coordinates/scripts，提供 convert_coords.py、normalize_variant.py、check_contigs.py、audit_intervals.py 四个命令行工具。参考文档位于 references/ 目录下，包括 format-conventions.md、variant-representation.md、reference-builds.md、transcript-coordinates.md。

报告结果时：每次都在坐标旁注明装配版本。chr7:5,530,601-5,530,625 不是位置；chr7:5,530,601-5,530,625 (GRCh38) 才是。在列标题或文件文档中说明坐标列使用哪种约定。当转换产生结果时，说明转换方向。

适用场景

在文件格式、工具、装配版本或基因组与转录本之间转换坐标
规范化并比较变异表示
在连接前检测装配或 contig 命名不匹配
审计区间文件是否符合自身格式
作为数据目录的 CI 门禁

限制

零长度 BED 特征被报告为不可表示，而非转换
多等位记录必须在规范化之前拆分
REF 与 FASTA 不匹配时不应调整坐标，而应检查装配
转录本坐标转换应使用持有转录本模型的工具，不应手工进行
版本特定细节可能过时，需对照已安装版本的官方文档确认
涉及费用、共享 GPU、云配额、个人或患者数据或不可撤销操作时，需先询问

技能介绍

用途