liftover

Converts variant coordinates from one genome build to another. Methods dispatch on a plain data frame of variants, a PGS, a PGSLibrary and a GenotypeSource.

Lifts the rows of a variant table from from.build to to.build, splitting the result into clean, unlifted and ambiguous variants.

Lifts a genotype fileset by delegating to the object's own $lift() method, which rewrites the coordinates with PLINK2 after rtracklayer::liftOver() maps them.

An object of the same class as data, holding the lifted coordinates; each method below states what becomes of the variants that fail to lift. A method with nothing to lift returns data unchanged. The PGS method is the one that modifies its input, PGS being an R6 object updated in place.

For a PGSLibrary: a new set on to.build, invisibly, holding one backbone and recording the target build in $liftover. The input set and its backbones are never touched; when every model is already on to.build, data itself is returned. Aborts on an empty set, an unsupported to.build, or a model carrying a genome build PolyGenius cannot resolve.

For a PGS: the same object, invisibly, updated in place -- $build, $variants and $liftover are overwritten. The lifted chr column comes back in the package's canonical scheme (chr1, chrX, chrMT), whichever spelling went in. Variants that failed to lift are recorded in $liftover$unlifted with error and explanation columns; ambiguous variants are dropped from $variants and left listed in attr(x$variants, "ambiguous"). A model already on to.build is returned untouched. Aborts on an unsupported to.build, an unsupported data$build, or an unavailable chain.

For a data frame: the clean lifted variants, same columns as data, positions and chromosome rewritten to the target build. Two tables ride along as attributes and are excluded from those rows: attr(result, "unlifted") — Variants no chain covers, plus those whose chromosome code could not be recognised; source columns plus error and explanation.

attr(result, "ambiguous") — Source columns, <column>.lifted target columns and a group key, covering both one-to-many mappings (one source position splitting to several targets) and many-to-one collisions (several source positions landing on one target locus). Attached only when at least one such variant exists. Aborts when data is not a data frame, when a named column is absent, when position.columns is neither length one nor two, or when the chain is unavailable.

For a GenotypeSource: a new object on to.build pointing at the lifted fileset, with two extra public fields, unlifted and ambiguous -- data.tables of the variants excluded from the output, each with a leading file column. The variants they list are dropped from the written fileset. Aborts when no chain covers the build pair or chromosome.format is invalid.

Lifting runs through rtracklayer::liftOver(), an R function, against a UCSC chain file. Unless a chain.path is given the chain is resolved through workspace$catalogs$liftoverChains, which downloads and caches it on first use. Every method needs the Bioconductor packages rtracklayer, GenomicRanges and IRanges; the call aborts with an install hint when one is missing, and when no chain covers the requested build pair.

A variant that lifts to exactly one target locus carries over with its new coordinates; alleles, escapes and registry entries are unchanged. The other three outcomes are dropped from the lifted models and recorded per model on the returned library's own registry overlay, as extra$liftover$unlifted -- read it off a model with set$models[[i]]$liftover. It is a table of chr, position, nea, ea and reason: "unlifted" (no chain covers the position) and "ambiguous", which covers both shapes of an undecidable coordinate: the position lifting to several targets, and several source loci landing on one target.

A surviving variant keeps everything attached to it. A move rebuilds the packed variant key, so the source plane is re-keyed onto the new dictionary rather than carried across, and an attached variant annotation is trimmed to the survivors and rewritten onto their lifted coordinates. The models keep the names and the mutate.models() extras the input library gave them, and $model.pairs is carried even when variants were dropped -- those statistics predate the lift, and whether they are still wanted is the caller's call rather than this function's. A set spanning two builds is the exception: converging it onto one backbone goes through absorb(), which builds a fresh backbone and carries no pair plane onto it.