Contents

1 Getting Started

1.1 Installation

if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("easylift")

1.2 Documentation

To view documentation:

browseVignettes("easylift")

1.3 Import

library("easylift")
#> Loading required package: GenomicRanges
#> Loading required package: stats4
#> Loading required package: BiocGenerics
#> 
#> Attaching package: 'BiocGenerics'
#> The following objects are masked from 'package:stats':
#> 
#>     IQR, mad, sd, var, xtabs
#> The following objects are masked from 'package:base':
#> 
#>     Filter, Find, Map, Position, Reduce, anyDuplicated, aperm, append,
#>     as.data.frame, basename, cbind, colnames, dirname, do.call,
#>     duplicated, eval, evalq, get, grep, grepl, intersect, is.unsorted,
#>     lapply, mapply, match, mget, order, paste, pmax, pmax.int, pmin,
#>     pmin.int, rank, rbind, rownames, sapply, setdiff, sort, table,
#>     tapply, union, unique, unsplit, which.max, which.min
#> Loading required package: S4Vectors
#> 
#> Attaching package: 'S4Vectors'
#> The following object is masked from 'package:utils':
#> 
#>     findMatches
#> The following objects are masked from 'package:base':
#> 
#>     I, expand.grid, unname
#> Loading required package: IRanges
#> Loading required package: GenomeInfoDb
#> Loading required package: BiocFileCache
#> Loading required package: dbplyr

1.4 Arguments

Create a GRanges object, assign a genome to it, and specify chain file

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")

gr
#> GRanges object with 200000 ranges and 0 metadata columns:
#>            seqnames    ranges strand
#>               <Rle> <IRanges>  <Rle>
#>        [1]     chr1  1-200000      *
#>        [2]     chr1  1-200000      *
#>        [3]     chr1  1-200000      *
#>        [4]     chr1  1-200000      *
#>        [5]     chr1  1-200000      *
#>        ...      ...       ...    ...
#>   [199996]     chr2  1-200000      *
#>   [199997]     chr2  1-200000      *
#>   [199998]     chr2  1-200000      *
#>   [199999]     chr2  1-200000      *
#>   [200000]     chr2  1-200000      *
#>   -------
#>   seqinfo: 2 sequences from hg19 genome; no seqlengths

1.5 Run

Call easylift with GRanges object, target genome and the chain file.

# 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

1.6 Run with BiocFileCache

To use BiocFileCache for the chain file, add it to the cache:

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)

Then, use it in easylift:

easylift(gr, "hg38") 
# or
gr |> easylift("hg38")

2 Citation

To cite package easylift in publications use:

Al Nahid A, Pagès H, Love M (2023). easylift: An R package to perform genomic liftover. R package version 1.0.0, https://github.com/nahid18/easylift.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {easylift: An R package to perform genomic liftover},
    author = {Abdullah Al Nahid, Hervé Pagès, Michael Love},
    year = {2023},
    note = {R package version 1.0.0},
    url = {https://github.com/nahid18/easylift},
  }

Please note that the easylift was only made possible thanks to many other R and bioinformatics software authors, which are cited either in the vignettes and/or the paper(s) describing this package.

3 Code of Conduct

Please note that the easylift project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

4 Session information

sessionInfo()
#> R version 4.3.1 (2023-06-16)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Ubuntu 22.04.3 LTS
#> 
#> Matrix products: default
#> BLAS:   /home/biocbuild/bbs-3.18-bioc/R/lib/libRblas.so 
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_GB              LC_COLLATE=C              
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: America/New_York
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats4    stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#> [1] easylift_1.0.0       BiocFileCache_2.10.0 dbplyr_2.3.4        
#> [4] GenomicRanges_1.54.0 GenomeInfoDb_1.38.0  IRanges_2.36.0      
#> [7] S4Vectors_0.40.0     BiocGenerics_0.48.0  BiocStyle_2.30.0    
#> 
#> loaded via a namespace (and not attached):
#>  [1] SummarizedExperiment_1.32.0 rjson_0.2.21               
#>  [3] xfun_0.40                   bslib_0.5.1                
#>  [5] lattice_0.22-5              Biobase_2.62.0             
#>  [7] vctrs_0.6.4                 tools_4.3.1                
#>  [9] bitops_1.0-7                generics_0.1.3             
#> [11] parallel_4.3.1              curl_5.1.0                 
#> [13] tibble_3.2.1                fansi_1.0.5                
#> [15] RSQLite_2.3.1               blob_1.2.4                 
#> [17] pkgconfig_2.0.3             R.oo_1.25.0                
#> [19] Matrix_1.6-1.1              lifecycle_1.0.3            
#> [21] GenomeInfoDbData_1.2.11     compiler_4.3.1             
#> [23] Rsamtools_2.18.0            Biostrings_2.70.0          
#> [25] codetools_0.2-19            htmltools_0.5.6.1          
#> [27] sass_0.4.7                  RCurl_1.98-1.12            
#> [29] yaml_2.3.7                  pillar_1.9.0               
#> [31] crayon_1.5.2                jquerylib_0.1.4            
#> [33] R.utils_2.12.2              BiocParallel_1.36.0        
#> [35] DelayedArray_0.28.0         cachem_1.0.8               
#> [37] abind_1.4-5                 tidyselect_1.2.0           
#> [39] digest_0.6.33               dplyr_1.1.3                
#> [41] restfulr_0.0.15             bookdown_0.36              
#> [43] grid_4.3.1                  fastmap_1.1.1              
#> [45] SparseArray_1.2.0           cli_3.6.1                  
#> [47] magrittr_2.0.3              S4Arrays_1.2.0             
#> [49] XML_3.99-0.14               utf8_1.2.4                 
#> [51] filelock_1.0.2              bit64_4.0.5                
#> [53] rmarkdown_2.25              XVector_0.42.0             
#> [55] httr_1.4.7                  matrixStats_1.0.0          
#> [57] bit_4.0.5                   R.methodsS3_1.8.2          
#> [59] memoise_2.0.1               evaluate_0.22              
#> [61] knitr_1.44                  BiocIO_1.12.0              
#> [63] rtracklayer_1.62.0          rlang_1.1.1                
#> [65] glue_1.6.2                  DBI_1.1.3                  
#> [67] BiocManager_1.30.22         jsonlite_1.8.7             
#> [69] R6_2.5.1                    MatrixGenerics_1.14.0      
#> [71] GenomicAlignments_1.38.0    zlibbioc_1.48.0