Skip to content
Research Agent Skillsby Kalaris Labs
Install
Scientific Databasesv1.1AdaptedMIT

genomic-coordinates

Convert genomic intervals between coordinate conventions, normalise and compare variant representations, and detect assembly or contig-naming mismatches before they corrupt an analysis. Use 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".

Install this skill

Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.

skills.sh CLI (Recommended)
npx skills add KalarisLabs/research-agent-skills --skill genomic-coordinates
uvx (Python tool runner)
uvx research-agent-skills install genomic-coordinates

Documentation & Instructions

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

The end coordinate never moves. If a conversion changed both numbers, it is wrong.

Which format is which

0-based, half-open 1-based, inclusive
BED, bedGraph, bigWig, narrowPeak GFF3, GTF, VCF
BAM/CRAM (binary POS) SAM (text POS)
PSL, genePred, refFlat WIG, Picard interval_list
MAF (UCSC multiple alignment) MAF (TCGA mutation annotation)
PyRanges, pybedtools GRanges/IRanges, samtools & UCSC & Ensembl region strings

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 rather than converted to end = start - 1. Exit code is 1 when any interval is degenerate or invalid.

Variants are not intervals

A VCF POS for an indel is the anchor base — the base before the event, itself unchanged. 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

Every record's REF is checked against the FASTA first. A MISMATCH means the variants and the reference are different assemblies — stop and run check_contigs.py rather than adjusting coordinates. Multi-allelic records must be split with --split before normalising, never after.

HGVS shifts indels the opposite way, 3'-most along the transcript. For a minus-strand gene that is the opposite genomic direction from VCF's left-alignment. Details and the full procedure: references/variant-representation.md.

Check the assembly before trusting a join

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)

The script reads .fai, .chrom.sizes, VCF headers, SAM headers, FASTA, BED, and GTF/GFF, identifies the assembly from primary-chromosome lengths, and reports every reason a join between two files would go wrong: naming mismatch, length conflict, coordinates past a contig end, contigs present in one file only. Exit code 1 on any incompatibility.

GRCh37 and hg19 differ only in the mitochondrion — 16,569 bp (rCRS) versus 16,571 bp. Nuclear coordinates are identical, so a mixed pipeline runs fine and only the mtDNA results are wrong. check_contigs.py reports which one it found. Builds, naming schemes, ALT contigs, and liftover pitfalls: references/reference-builds.md.

Audit a file against its own format

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

Looks for the evidence that a coordinate mistake leaves behind:

Finding What it proves
start_below_one in GFF/GTF 0-based data in a 1-based file; everything is one base left
many_zero_length in BED 1-based single-base features written into a 0-based file
past_contig_end wrong assembly, or an off-by-one at the contig edge
mixed_contig_naming any join will silently match one subset
first_block_offset BED12 blockStarts written as absolute coordinates
not_parsimonious untrimmed alleles; normalise before joining
bad_alt_allele Ensembl/VEP - notation in a VCF, which has no anchor base

Exit code 1 on any fatal finding, so it works as a CI gate on a data directory.

Transcript, CDS, and protein positions

c.742 and chr17:7,674,220 are both "position", and neither converts to the other by arithmetic. Transcript coordinates count spliced bases in transcription order — decreasing genomic coordinate on the minus strand — and c.1 is the A of the initiator ATG, not the start of the transcript.

The rules that get mis-remembered: there is no c.0; 5' UTR positions are negative and 3' UTR positions take a *; GFF phase is the bases to remove to reach the next codon, not start % 3; and a c. description is meaningless without a versioned transcript accession, because the same variant numbers differently in each transcript. references/transcript-coordinates.md has the conversion procedure and the boundary cases.

Do the conversion with a tool that holds the transcript model — VEP, bcftools csq, Mutalyzer, the hgvs package — not by hand.

Reporting results

State the assembly next to the coordinates, every time. chr7:5,530,601-5,530,625 is not a location; chr7:5,530,601-5,530,625 (GRCh38) is. Say which convention a coordinate column is in, in the column header or the file's documentation. When a conversion produced a result, say which direction it went.

References

  • references/format-conventions.md — every format's convention, with per-format detail, BED12 block rules, region-string syntax, and tool behaviour.
  • references/variant-representation.md — VCF allele conventions, the normalisation algorithm, equivalence checking, multi-allelic splitting, and how HGVS disagrees with VCF.
  • references/reference-builds.md — build signatures, GRCh37 vs hg19, ALT contigs, naming schemes, and liftover failure modes.
  • references/transcript-coordinates.md — genomic ↔ transcript ↔ CDS ↔ protein, HGVS numbering, phase, and transcript choice.

Agent operating procedure

  1. Check the environment. Confirm network access, API keys (if required) and the database's current API documentation and rate limits.
  2. Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
  3. Run a small version first. Fetch a single known record and check the response format before bulk queries.
  4. Execute the full task using the instructions and references above.
  5. Validate the result. Identifiers resolve, record counts are reported, and the database version or access date is recorded.
  6. Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
If this happens Do this
HTTP 429 or 5xx errors Respect rate limits with backoff, batch requests, and report partial results honestly.
A function, flag or endpoint in these instructions is missing in the installed version Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API.
A required input, identifier or parameter is ambiguous Ask the user, or state the assumption explicitly before running.

Integrity rules

  • Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
  • Never invent accession numbers, IDs or records; report 'not found' instead.
  • Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
  • Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.

Related skills

  • polars-bio: Python library polars-bio for genomic interval operations and bioinformatics file I/O on Polars DataFrames, built on Arrow and DataFusion.
  • gtars: Inspects and plans work with Gtars, the Rust/Python/CLI toolkit for genomic intervals: BED RegionSet set algebra (reduce, setdiff, intersec…
  • geniml: Plans and audits local genomic-interval machine learning workflows with Geniml (0.8.4) and Gtars: validates BED files against chromosome si…

Trigger Prompts & Evaluation Corpus

These evaluation prompts test that the agent correctly selects genomic-coordinates for relevant tasks and leaves it out for near misses.

Should trigger (3)

  • should trigger

    “My peak caller output BED looks one base off when I load it next to my GTF annotations in IGV. What's going on?”

    expects Explains BED is 0-based half-open while GTF is 1-based inclusive, and gives the conversion (start+1, end unchanged; reverse for GTF to BED). Notes the end coordinate never moves, and asks which tool/convention produced each file or suggests auditing the files for convention violations.

  • should trigger

    “I'm merging ClinVar (GRCh38 VCF) with my cohort's VCF, but a bunch of known pathogenic indels in my samples (e.g. BRCA1 deletions in repeat regions) show up as novel. I'm doing a plain join on CHROM/POS/REF/ALT in pandas. bcftools says 'REF does not match the reference' for a few records too. How do I fix this?”

    expects Diagnoses that the same indel can be written differently (non-parsimonious or not left-aligned), and recommends splitting multi-allelics then trimming and left-aligning with bcftools norm against the reference FASTA before joining. Treats the REF mismatches as a possible assembly or contig mismatch (e.g. GRCh37 vs GRCh38) and says to check the contigs and build rather than adjusting coordinates.

  • should trigger

    “I have a transcript-level HGVS c.742C>T for a TP53 variant from a clinical report and need the genomic position so I can look it up in my aligned data. Which transcript, which strand, and how do I get to the genomic coordinate safely?”

    expects Says c. positions cannot be converted by simple arithmetic and need a versioned transcript accession (e.g. NM_000546.x) and the assembly. Recommends a tool that holds the transcript model (VEP, Mutalyzer, bcftools csq or the hgvs package), notes TP53 is on the minus strand, and that the result should be reported with the assembly named.

Near misses (2)

  • near miss

    “Using polars-bio in Python, how do I compute the overlap between two BED DataFrames and then cluster the overlapping intervals, scanning the files lazily?”

    expects Uses polars-bio's overlap and cluster functions with lazy scan_bed or read_bed on Polars DataFrames. This is interval-operation API usage rather than coordinate-convention conversion or auditing.

  • near miss

    “Write a Python function that parses a tab-separated gene expression matrix and runs a differential expression test between two groups with multiple testing correction.”

    expects Provides a general differential expression workflow (e.g. t-test or a DE method with FDR correction). It has nothing to do with genomic coordinate conventions, so no coordinate skill applies.