Genomic Coordinates

When to use

Any time a coordinate crosses a boundary: between two file formats, between two tools, between two assemblies, or between the genome and a transcript.

The rule

A coordinate is three facts, not one: the number, the convention it is written in, and the assembly it was measured against. Carry all three or the number is not interpretable.

Coordinate errors are the quietest class of bug in genomics. An off-by-one BED file parses, sorts, and intersects without complaint. A GRCh37 VCF joined against a GRCh38 annotation returns rows. A right-shifted indel simply fails to match its entry in ClinVar, and the result is a variant reported as novel. Nothing raises an error; the answer is just wrong, and it is wrong in a direction that looks plausible.

So: convert with the table, not from memory, and verify against the reference whenever a reference is available.

The two conversions

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

These formulas apply to nonempty spans on the same reference and strand. They do not encode insertions, circular wraparound, liftover, or transcript mapping.

Which format is which

Both "MAF" formats exist, they mean different things, and they disagree. UCSC serves 0-based files through a 1-based browser box. references/format-conventions.md has the full table with per-format detail.

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

Zero-length BED features (chromStart == chromEnd, a legal insertion point) are reported as unrepresentable for an inclusive target because the converter lacks feature semantics. GFF3 can encode insertion sites with equal endpoints and a feature type; that is different from an ordinary single-base interval. Exit code is 1 for invalid or unrepresentable output; valid zero-length half-open output exits 0. Output is a diagnostic TSV/JSON table, not a rewritten GFF/VCF.

--input parses BED/bedGraph, GFF/GTF, literal-allele VCF REF spans, explicit region strings, and three-column GRanges/PyRanges/Python TSVs. Other table rows are conventions only: extract an interval with a native parser and pass a triple. All bundled text readers expect uncompressed files.

Variants are not intervals

For a simple VCF indel, POS normally identifies the unchanged padding base before the event. At contig position 1 the padding can follow the event. Complex substitutions need not have an unchanged anchor. And the same change can be written many ways: chr1:7:CAC:C, chr1:3:CAC:C and chr1:2:GCA:G are one deletion. Joining, deduplicating, or looking up variants before normalising loses real matches silently, and it loses them preferentially in repeats, where indels concentrate.

Normalise — trim to parsimony, then left-align against the reference — before any comparison:

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

Literal alleles are checked against the FASTA using exact contig names. A MISMATCH can indicate an assembly, sequence, strand, or coordinate error; stop and investigate with check_contigs.py and sequence provenance. The helper rejects unsplit ALT lists: use --split for independently normalized allele keys. Its TSV discards genotypes and annotations; use bcftools norm for production

…