---
title: "Perform Genomic Liftover"
abstract: >
  An R/Bioconductor library to perform genomic liftover between different genome assemblies with `GRanges` and `chain` file. Source Code: https://github.com/nahid18/easylift
author:
- name: Abdullah Al Nahid
  affiliation: 
  - "Department of Biochemistry and Molecular Biology, Shahjalal University of Science and Technology, Sylhet, Bangladesh"
- name: Hervé Pagès
  affiliation: 
  - "Fred Hutchinson Cancer Research Center, Seattle, WA, USA"
- name: Michael I. Love
  affiliation: 
  - "Biostatistics Department, University of North Carolina-Chapel Hill, Chapel Hill, NC, USA"
  - "Genetics Department, University of North Carolina-Chapel Hill, Chapel Hill, NC, USA"
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Perform Genomic Liftover}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r style, echo = FALSE, results = 'asis'}
  BiocStyle::markdown()
```
  
```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Getting Started

## Installation

```{r install, eval=FALSE}
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("easylift")
```

## Documentation
To view documentation:
```{r doc, eval = FALSE}
browseVignettes("easylift")
```

## Import

```{r setup}
library("easylift")
```

## Arguments

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

```{r example}
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
```

## Run

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

```{r run}
# Here, "hg38" is the target genome
easylift(gr, "hg38", chain)
```

## Run with BiocFileCache

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

```{r bioCache, eval=FALSE}
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`:
```{r bioCache2, eval=FALSE}
easylift(gr, "hg38") 
# or
gr |> easylift("hg38")
```

# 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.

# Code of Conduct

Please note that the `easylift` project is released with a [Contributor Code of Conduct](http://bioconductor.org/about/code-of-conduct/). By contributing to this project, you agree to abide by its terms.

# Session information

```{r}
sessionInfo()
```