Genome builds and liftover

Every record that carries positions carries its build. A VCF declares it in its header: the contig lengths are the surest sign (chromosome 1 is 249,250,621 bp in hg19 and 248,956,422 bp in hg38), and an assembly= or ##reference line is read too. A reference genome on the runner declares it through its index. The data panel shows the build and whether chromosomes are named chr1 or 1.

Cross-build joins are refused

A tool whose model is bound to one build refuses the other. MuTopia's models are hg38: an hg19 VCF stops at the Start board with "The VCF is hg19; MuTopia's models are hg38", and a VCF and a reference on different builds stop the same way. Chromosome naming is reconciled where it can be: a VCF naming chromosomes 1, 2, … against a reference naming them chr1, chr2, … runs, the runner telling MuTopia to add the prefix; the reverse stops with a message. A VCF that does not say its build is let through with a warning. Tally goes further: it reads the build off 200 REF alleles against hg19 and hg38, so a file whose header says nothing is still placed, and one whose header is wrong is caught (see From variants to spectra).

Liftover

The Liftover function moves a VCF between hg19 and hg38 on the runner. It uses pyliftover with UCSC's chain files, pinned by sha256 and fetched once; a chain file that does not match its pin is removed and the run stops. Each position is lifted on its own. A record whose position has no image in the target build, lands on another chromosome, or flips strand is written to unmapped.vcf with the reason; with the target build's FASTA bound, so is a record whose REF is not the target's base at its new position (ref_changed), which MuTopia would otherwise stop on; the rest go to lifted.vcf with the target build's contig lengths in the header, so the lifted file is read as the build it now is. The report names counts and reasons, and one click adds the lifted VCF to the records. Checked on a PCAWG consensus VCF: 17,416 of 17,494 positions lifted, and the REF alleles of 300 sampled lifted positions all matched hg38.

| Direction | Chain | sha256 | |---|---|---| | hg19 → hg38 | hg19ToHg38.over.chain.gz | 5c0598e5… | | hg38 → hg19 | hg38ToHg19.over.chain.gz | 14a712e8… |