---
title: |
    annoLinker Vignette: Annotating genomic regions 
    through chromatin interaction links
author: "Jianhong Ou"
date: "`r BiocStyle::doc_date()`"
package: "`r BiocStyle::pkg_ver('annoLinker')`"
abstract: >
  Annotating genomic regions through chromatin interaction networks.
  Genomic peaks are efficiently annotated by leveraging DNA interaction data to
  construct interaction graphs with igraph.
  Each peak overlapping a node within a connected component is annotated with 
  all genes associated with that component, enabling robust propagation of
  functional associations across the chromatin interaction network.
vignette: >
  %\VignetteIndexEntry{annoLinker Vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output:
  BiocStyle::html_document:
    toc: true
    toc_float: true
    toc_depth: 4
    fig_caption: true
---

```{r setup, echo=FALSE, results="hide", warning=FALSE}
knitr::opts_chunk$set(warning = FALSE, message = FALSE)
```

## Introduction

Functional annotation of genomic regions is a key step in understanding
regulatory mechanisms underlying gene expression and phenotype variation.
Traditional annotation methods typically rely on the linear proximity of
genomic features, such as linking peaks to the nearest gene, which can
overlook the complex three-dimensional organization of the genome.
Recent advances in chromatin conformation capture technologies
(e.g., Hi-C, ChIA-PET, PLAC-seq, HiCAR) have revealed that regulatory elements
often interact with distant genomic loci through chromatin loops,
bringing enhancers, promoters, and other elements into physical contact.

`annoLinker` is designed to bridge this gap by annotating genomic regions
through chromatin interaction links. Rather than relying solely on
linear genomic distance, `annoLinker` integrates chromatin contact information
to establish biologically meaningful connections between regulatory regions
and their potential target genes. This approach complements traditional 
annotation methods by enabling the functional assignment of distal elements
such as enhancers and silencers.

The package provides a streamlined workflow to link user-defined genomic regions
with genomic interactions (loops), annotate the associated genes, and visualize
the resulting interaction networks. By leveraging interaction data, `annoLinker`
enables users to explore functional relationships that are invisible in linear
genome coordinates and to generate more comprehensive biological interpretations
from genomic assays such as ATAC-seq, ChIP-seq, or Methyl-seq.

## Installation

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

BiocManager::install("annoLinker")
```

## Quick start

The input to `annoLinker` consists of three components: the genomic regions of
interest to be annotated, the annotation data, and the chromatin interaction
information. Both the peak list and annotation data should be provided as
`GRanges` objects, while genomic interactions can be supplied as either
`GInteractions` or `Pairs` objects.

By default, `annoLinker` annotates peaks that fall within the *promoter region*,
defined as 5 kb upstream to 5 kb downstream of the annotated features.
Users can optionally modify this definition to annotate regions within the
*gene body* or *downstream* segments instead.

The output is returned as an `annoLinkerResult` object, which can be easily
converted into a `GRanges` or `data.frame` for downstream analysis and
visualization.

```{r loadlibrary,warning = FALSE,message=FALSE}
library(annoLinker)
library(rtracklayer)
library(TxDb.Drerio.UCSC.danRer10.refGene)
library(org.Dr.eg.db)
```
```{r quickstart}
txdb <- TxDb.Drerio.UCSC.danRer10.refGene
org <- org.Dr.eg.db
extPath <- system.file("extdata", package = "annoLinker")
## load peaks
peaks <- rtracklayer::import(file.path(extPath, "peaks.bed"))
## load interactions
interactions <- rtracklayer::import(file.path(extPath, "interaction.bedpe"))
## load annotation data
annoData <- genes(txdb)
anno <- annoLinker(peaks, annoData, interactions, verbose = TRUE)
class(anno)
head(anno, n = 2)
anno_peaks(anno)[c(1, 2)]
head(as(anno, "GRanges"), n = 2)
```

The `plotEvidence()` function allows users to visualize the annotation evidence
chain, illustrating how genomic regions are linked through chromatin
interactions. Users can plot the annotation evidence as either a
*network graph* or a *genomic track* integrated with gene annotation
information.

```{r datavisualization}
## plot the evidence for the first annotation
plotEvidence(anno,
    event = 1,
    output = "htmlWidget"
)
plotEvidence(anno,
    event = 1,
    output = "trackPlot",
    txdb = TxDb.Drerio.UCSC.danRer10.refGene,
    org = org.Dr.eg.db
)
```


## SessionInfo

```{r sessioninfo, echo=FALSE}
sessionInfo()
```