Skip to contents

Lift genomic coordinates from one genome assembly to another.

Source: R/easylift.R
easylift.Rd

This function takes a GRanges object with genomic coordinates in one genome assembly and lifts them to target genome assembly using a chain file.

Usage

easylift(x, to, chain, bfc)

Arguments

x

A GRanges object with genomic coordinates in the original assembly.

to

The target genome assembly (e.g., "hg38").

chain

The path to the chain file containing the liftover mapping. Can be provided in gzipped or non-gzipped format. If omitted, the function will look in the default BiocFileCache for a properly named chain file.

bfc

A BiocFileCache object (optional), if not provided (most typically) the default location will be used.

Value

A GRanges object with lifted genomic coordinates.

See also

liftOver function from the rtracklayer package, which is the basis for easylift.

Examples

# Lift over the coordinates of the first 10 genes in the hg19 assembly
# to the hg38 assembly
library(easylift)
gr <- GRanges(
  seqname = Rle(c("chr1", "chr2"), c(100000, 100000)),
  ranges = IRanges(start = 1, end = 200000)
)
# Here, "hg19" is the source genome
genome(gr) <- "hg19"

# Here, we use the `system.file()` function because the chain file is in the
# package (however if you need to point to any other file on your machine,
# just do 'chain <- "path/to/your/hg19ToHg38.over.chain.gz"'):
chain <- system.file("extdata", "hg19ToHg38.over.chain.gz", package = "easylift")

# Here, "hg38" is the target genome
easylift(gr, "hg38", chain)
#> GRanges object with 300000 ranges and 0 metadata columns:
#>            seqnames        ranges strand
#>               <Rle>     <IRanges>  <Rle>
#>        [1]     chr1  10001-177376      *
#>        [2]    chr19 242824-242864      *
#>        [3]     chr1  10001-177376      *
#>        [4]    chr19 242824-242864      *
#>        [5]     chr1  10001-177376      *
#>        ...      ...           ...    ...
#>   [299996]     chr2  10001-200000      *
#>   [299997]     chr2  10001-200000      *
#>   [299998]     chr2  10001-200000      *
#>   [299999]     chr2  10001-200000      *
#>   [300000]     chr2  10001-200000      *
#>   -------
#>   seqinfo: 25 sequences (1 circular) from hg38 genome

# \donttest{
# To use `BiocFileCache` for the chain file, add it to the cache as follows:
chain_file <- "/path/to/your/hg19ToHg38.over.chain.gz"
bfc <- BiocFileCache()

# Add chain file to cache if already not available
if (nrow(bfcquery(bfc, basename(chain_file))) == 0)
   bfcadd(bfc, chain_file)
#> Error in bfcadd(bfc, chain_file): all(rtype == "web" | file.exists(fpath)) is not TRUE

# Then, use it in `easylift` like this:

easylift(gr, "hg38")
#> Error in .get_chain_from_BiocFileCache(unique_genomes, to, bfc): Chain file not specified and filename with hg19ToHg38.over.chain pattern not found in BiocFileCache default location.
# or
gr |> easylift("hg38")
#> Error in .get_chain_from_BiocFileCache(unique_genomes, to, bfc): Chain file not specified and filename with hg19ToHg38.over.chain pattern not found in BiocFileCache default location.
# }