K-Dense-AI/scientific-agent-skills / skills/genomic-coordinates
genomic-coordinates
VerifiedConverts genomic intervals between coordinate conventions, normalises and compares variant representations, and detects assembly or contig-naming mismatches before they corrupt an analysis. Used whenever coordinates cross a format, tool, or assembly boundary - converting between BED, GFF/GTF, VCF, SAM/BAM, WIG, PSL, genePred, Picard interval_list, or region strings; reconciling 0-based half-open with 1-based inclusive; left-aligning or trimming indels; checking whether two variant records describe the same change; mapping genomic to transcript, CDS, or protein positions; auditing a BED/GTF/VCF for convention violations; or diagnosing GRCh37 vs hg19 vs GRCh38 vs T2T, chr-prefix, and liftover problems. Triggers include "off by one", "0-based", "1-based", "half-open", "coordinate system", "left-align", "normalize variant", "bcftools norm", "chr prefix", "wrong genome build", "liftover", "REF mismatch", and "HGVS".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
| references/format-conventions.md | markdown | 12.0 KB |
| references/reference-builds.md | markdown | 7.8 KB |
| references/transcript-coordinates.md | markdown | 8.2 KB |
| references/variant-representation.md | markdown | 7.9 KB |
| scripts/_common.py | script | 14.4 KB |
| scripts/audit_intervals.py | script | 20.7 KB |
| scripts/check_contigs.py | script | 16.8 KB |
| scripts/convert_coords.py | script | 7.4 KB |
| scripts/normalize_variant.py | script | 11.0 KB |
references/reference-builds.md
View on GitHub# Reference builds, contig naming, and liftover
A coordinate is meaningless without the assembly it was measured against. Two
files can share contig names, share a coordinate range, join cleanly, and refer
to different parts of the genome.
All lengths below were read from the UCSC `bigZips` `chrom.sizes` for each
assembly; all 24 nuclear lengths in the bundled tables were rechecked against
those downloads on 2026-10-01. GRCh37 mitochondrial context is documented by UCSC. `scripts/check_contigs.py` carries the same table and
matches files against it.
## Discriminating lengths
| Contig | GRCh37 / hg19 | GRCh38 / hg38 | T2T-CHM13v2.0 / hs1 |
| --- | --- | --- | --- |
| chr1 | 249,250,621 | 248,956,422 | 248,387,328 |
| chr2 | 243,199,373 | 242,193,529 | 242,696,752 |
| chrX | 155,270,560 | 156,040,895 | 154,259,566 |
| chrY | 59,373,566 | 57,227,415 | 62,460,029 |
| chrM / MT | 16,571 *(hg19)* / 16,569 *(GRCh37)* | 16,569 | 16,569 |
```bash
python3 check_contigs.py --identify unknown.fa.fai
```
## GRCh37 is not hg19
They are the same assembly for every primary chromosome except the
mitochondrion. UCSC's hg19 kept the older `NC_001807` sequence at **16,571 bp**;
GRCh37 adopted the revised Cambridge Reference Sequence (rCRS, `NC_012920`) at
**16,569 bp**. GRCh38 also uses rCRS, so chrM length distinguishes hg19 from
everything else but does not distinguish GRCh37 from GRCh38.
Consequences:
- Mitochondrial coordinates and alleles cannot be compared by renaming alone;
some positions agree while others shift or refer to different bases.
- Use reference-aware sequence mapping and allele checks, or re-call from reads,
before comparing mtDNA calls. Re-calling is not the only possible conversion.
The two also differ in naming and in alternate-haplotype handling:
| | GRCh37 (Ensembl/NCBI) | hg19 (UCSC) |
| --- | --- | --- |
| Autosomes | `1`, `2`, … | `chr1`, `chr2`, … |
| Mitochondrion | `MT` (16,569) | `chrM` (16,571) |
| Alt haplotypes | `GL000250.1`-style | 9 `chr6_cox_hap2`-style contigs |
| Unplaced | `GL000191.1`-style | `chrUn_gl000191` |
### The b37 family
`b37` (Broad) is GRCh37 with plain naming and rCRS `MT`. `hs37d5` (1000 Genomes
phase 2) is b37 plus a decoy contig (`hs37d5`) and the EBV genome. Shared primary
sequences can use an audited name map without liftover. Whole files are not
equivalent: decoy/EBV records have no counterpart in a smaller reference, and
reads may map elsewhere or remain unmapped when decoys are removed.
## GRCh38 and its ALT contigs
The base UCSC `hg38.chrom.sizes` download checked in this review has 455
sequences: 25 primary/mitochondrial, **261 `_alt`**, 42 `_random`, and 127 `chrUn_`.
These counts describe that download, not every GRCh38 patch or analysis set. The ALT contigs are alternate representations of
regions that are genuinely polymorphic — mostly MHC, and the HLA haplotypes.
ALT sequence can affect multi-mapping, MAPQ and downstream coverage. The
outcome depends on the aligner and its ALT handling; equal alignments do not
universally receive MAPQ 0. Use the reference bundle and ALT-aware alignment
procedure documented for the chosen pipeline. A no-ALT set is a distinct
analysis choice, not a universal default.
Some analysis sets mask duplicated regions such as chrY PARs. Contig lengths
cannot reveal masking or same-length substitutions. Record the exact FASTA
checksum and sequence dictionary, not just a build label.
Patch releases (`GRCh38.p13`, `p14`) add `_fix` and new `_alt` contigs but never
move a coordinate on a primary chromosome. Shared unchanged sequences keep their coordinates; patch-contig availability differs.
## T2T-CHM13
CHM13v2.0/hs1 is a different assembly, not a GRCh38 patch. Many coordinates
shift and newly resolved sequence may lack a GRCh38 counterpart. The v2.0
bundle includes chromosome Y from HG002, not the CHM13 cell line. Choose
annotations explicitly released for the target assembly and treat unresolved
or multi-mapped liftover regions as such.
## Contig naming
Four naming schemes are in circulation for the same chromosome:
```
chr1 UCSC
1 Ensembl, NCBI, GATK b37
NC_000001.11 RefSeq accession (GRCh38); NC_000001.10 is GRCh37
CM000663.2 GenBank accession (GRCh38); CM000663.1 is GRCh37
```
Note that the accession's version suffix, not the base accession, carries the
build. `NC_000001.10` and `NC_000001.11` differ only in the last character and
are different assemblies.
When sequences are proven identical, renaming is the fix; `bcftools annotate --rename-chrs`, `samtools reheader`,
and a two-column mapping file all do it. Two rules:
- Rename the **smaller, cheaper** file, and rename it to match the reference —
never rename the reference.
- `chrM` ↔ `MT` is safe only after confirming the mitochondrial sequences match.
GRCh37/GRCh38 commonly use rCRS, while hg19 uses a different chrM. This says
nothing about nuclear compatibility between GRCh37 and GRCh38.
An ordinary text join across naming schemes may not error. It returns the rows that happen to
match — often zero, sometimes a misleading subset when one file is partly
renamed. `check_contigs.py` reports style and exact-name conflicts, but alias folding
is diagnostic only. The normalizer requires exact FASTA names and does not
silently map `chrM` to `MT` or a case variant.
## Liftover
`liftOver` (UCSC, with a `.chain` file) and `CrossMap` (which also handles BAM,
VCF, and BigWig) are the working tools. Both depend on a specific source-to-target chain and supported format semantics:
- **Coordinates can vanish.** A region deleted from the newer assembly has no
target. liftOver writes these to its unmapped file, which is easy to ignore and
should be counted every time.
- **Mappings can be one-to-many.** A region duplicated in the target maps to
several places; taking the first is a silent choice.
- **Strand can flip.** Inverted segments between builds mean a plus-strand
feature lifts to the minus strand. Interval files carry this fine; anything
where sequence orientation matters (primer sites, guide RNAs, motif hits) does
not.
- **Interval endpoints can lift independently.** A long feature can lift to a
different length, or split.
- **Variants need more than coordinates.** After lifting a VCF, `REF` may no
longer match the new reference, and if the segment inverted, `REF` and `ALT`
need reverse-complementing. CrossMap has VCF-specific handling and rejected-record output; inspect both
mapped and unmapped files. Support varies by variant type, and a successful
coordinate mapping alone does not establish allele or genotype correctness. Always re-run `normalize_variant.py` against the *target* reference
afterwards and count the `MISMATCH` rows.
Lifting twice — 37 → 38 → 37 — does not reliably return the original
coordinates. Reprocessing reads against the target build can avoid some liftover losses,
but accuracy still depends on the pipeline; it is not a universal guarantee.
## A note on what to record
Coordinates in a results table, a figure, or a supplementary file should say
which build they are in, next to the numbers. "chr7:5,530,601-5,530,625" is not a
location. "chr7:5,530,601-5,530,625 (GRCh38)" is.
## Official sources reviewed 2026-10-01
- UCSC size tables: [hg19](https://hgdownload.soe.ucsc.edu/goldenPath/hg19/bigZips/hg19.chrom.sizes),
[hg38](https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes),
[hs1](https://hgdownload.soe.ucsc.edu/goldenPath/hs1/bigZips/hs1.chrom.sizes).
- [UCSC assembly FAQ](https://genome.ucsc.edu/FAQ/FAQreleases.html): mitochondrial
reference and naming differences. Sizes are signatures, not sequence checksums.
- [T2T CHM13 release notes](https://github.com/marbl/CHM13): v2.0 and HG002 Y.
- [CrossMap documentation](https://crossmap.readthedocs.io/en/latest/): format-specific
mapping and VCF limitations. No whole-genome liftover was executed in this review.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |