# epiRomics: a multi-omics R package to identify and visualize enhancers

[![R-CMD-check](https://github.com/Huising-Lab/epiRomics/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/Huising-Lab/epiRomics/actions/workflows/R-CMD-check.yaml) [![BiocCheck](https://github.com/Huising-Lab/epiRomics/actions/workflows/BiocCheck.yaml/badge.svg)](https://github.com/Huising-Lab/epiRomics/actions/workflows/BiocCheck.yaml) [![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)](tests/) [![License: Artistic-2.0](https://img.shields.io/badge/License-Artistic--2.0-blue.svg)](https://opensource.org/licenses/Artistic-2.0) [![Altmetric](https://img.shields.io/badge/Altmetric-10.1101%2F2021.08.19.456732-blue.svg)](https://www.altmetric.com/details/112068712)
  
An R package designed to integrate and visualize various levels of epigenomic information, including but not limited to: ChIP, Histone, ATAC, and RNA sequencing. epiRomics is also designed for regulatory network analysis in order to identify enhancer and enhanceosome regions from these data. 

Please contact <ammawla@ucdavis.edu> for suggestions, feedback, or bug reporting.

## Interactive Showcase of Package

Explore epiRomics results interactively through our companion Shiny web applications:


### Shiny epiRomics Mouse Alpha, Beta, and Delta Cells Browser


**[Shiny epiRomics Mouse Islet Enhanceosome Browser](https://www.huisinglab.com/epiRomics_2021/index.html)** — Interactive browser exploring mouse pancreatic islet enhancers and enhanceosome analysis results from our 2023 BMC Genomics publication.

***Paper:*** Alex M. Mawla, Talitha van der Meulen, Mark O. Huising. (2023). Chromatin accessibility differences between alpha, beta, and delta cells identifies common and cell type-specific enhancers. *BMC Genomics*. [10.1186/s12864-023-09293-6](https://link.springer.com/article/10.1186/s12864-023-09293-6)

### Shiny epiRomics Human Alpha and Beta Cells

**[Shiny epiRomics Human Islet Enhanceosome Browser](https://huisinglab.shinyapps.io/Server_epiRomics_Shiny_Human/)** — Interactive browser exploring human pancreatic islet enhancer and enhanceosome analysis results used to create the example data and vignette for the epiRomics Package.

***Package:*** Alex M. Mawla & Mark O. Huising. (2021). epiRomics: a multi-omics R package to identify and visualize enhancers. *bioRxiv* 2021.08.19.456732. [10.1101/2021.08.19.456732](https://www.biorxiv.org/content/10.1101/2021.08.19.456732v2)



## Features

- **Multi-omics Integration**: Seamlessly integrate ChIP-seq, ATAC-seq, RNA-seq, and histone modification data
- **Enhancer Identification**: Identify putative enhancer regions using histone mark combinations
- **Enhanceosome Analysis**: Detect enhanceosome regions through co-transcription factor analysis
- **Memory-Efficient Processing**: Built-in BigWig caching for large-scale data analysis
- **Comprehensive Visualization**: Generate publication-ready genomic tracks and plots
- **Robust Error Handling**: Comprehensive parameter validation and error messages

## Installation

### Prerequisites

epiRomics requires R version 4.5.0 or higher and several Bioconductor packages. Make sure you have the latest version of R and Bioconductor installed.

### Install from Bioconductor (recommended)

```r
if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install("epiRomics")

library(epiRomics)

# Optional: download the full example dataset (~1.3 GB, one-time,
# cached via BiocFileCache). The package also ships a small toy
# subset in `inst/extdata/toy/` that runs all examples without any
# download.
epiRomics::cache_data()
```

### Install from GitHub (development / not recommended for regular users)

> **Note:** The Bioconductor release channel is the supported install
> path. GitHub installation is intended for developers tracking the
> `main` branch between releases and is not advised for regular users.

```r
if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install("Huising-Lab/epiRomics")
```

## Quick Start

```r
# Load the package
library(epiRomics)

# Build epiRomics database
database <- build_database(
  db_file = "path/to/your/data.csv",
  txdb_organism = "TxDb.Hsapiens.UCSC.hg38.knownGene",
  genome = "hg38",
  organism = "org.Hs.eg.db"
)

# Identify putative enhancers
enhancers <- find_enhancers_by_comarks(
  database = database,
  histone_mark_1 = "h3k4me1",
  histone_mark_2 = "h3k27ac"
)

# Identify enhanceosomes
enhanceosomes <- find_enhanceosomes(
  putative_enhancers = enhancers,
  database = database
)

# Visualize results
plot_tracks(
  enhanceosomes,
  index = 1,
  database = database,
  track_connection = your_track_data
)
```

## Documentation

- **pkgdown site** (live): <https://huising-lab.github.io/epiRomics/> — full reference manual, both vignettes, and changelog rendered as a browsable website. This is the best entry point while the Bioconductor landing page is still pending.
- **Bioconductor landing page**: <https://bioconductor.org/packages/epiRomics/> (available after the package is accepted into a Bioconductor release).
- **Vignettes** (after install): `browseVignettes("epiRomics")`
  - *Getting Started with epiRomics* — lightweight walkthrough using the bundled toy dataset
  - *Full Analysis with epiRomics* — complete human pancreatic islet analysis (uses `cache_data()`)
- **Reference manual** (after install): `help(package = "epiRomics", help_type = "html")`

## Example Data

Example data is downloaded on demand via `cache_data()` (~1.3 GB, cached locally after first download). The dataset focuses on delineating putative human pancreatic islet enhancers between alpha and beta cells and includes:

- Human pancreatic islet alpha and beta ATAC-seq data from GEO accession [GSE76268](https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE76268)
- ChIP-seq data for transcription factors Foxa2, MafB, Nkx2.2, Nkx6.1, and Pdx1
- Histone modification data (H3K27ac, H3K4me1,H3K27me3, H3K9me3, H3K4me3, H3K36me3, H2A.Z)
- FANTOM5 human enhancer database
- Human ultra-conserved non-coding elements (UCNEs)


## Citation

If you use epiRomics, please cite:

Alex M. Mawla, Talitha van der Meulen, Mark O. Huising. (2023). Chromatin accessibility differences between alpha, beta, and delta cells identifies common and cell type-specific enhancers. *BMC Genomics*. [10.1186/s12864-023-09293-6](https://link.springer.com/article/10.1186/s12864-023-09293-6)

Alex M. Mawla & Mark O. Huising. (2021). epiRomics: a multi-omics R package to identify and visualize enhancers. *bioRxiv* 2021.08.19.456732. [10.1101/2021.08.19.456732](https://www.biorxiv.org/content/10.1101/2021.08.19.456732v2)

## Contributing

We welcome contributions! Please feel free to submit issues, feature requests, or pull requests on our [GitHub repository](https://github.com/Huising-Lab/epiRomics).

## License

This package is licensed under the [Artistic License 2.0](https://opensource.org/licenses/Artistic-2.0). See the [LICENSE](LICENSE) file for details.

## Contact

For questions, suggestions, or bug reports, please contact:

- **Maintainer**: Alex M. Mawla <ammawla@ucdavis.edu>
- **GitHub Issues**: <https://github.com/Huising-Lab/epiRomics/issues>


## Troubleshooting

### Installation Issues

**Problem**: Package dependencies fail to install <br>
**Solution**: Make sure you have the latest version of R (≥ 4.5.0) and Bioconductor:

```r
# Update R packages
update.packages(ask = FALSE)

# Update Bioconductor
BiocManager::install(version = BiocManager::version())

# If installation fails, try installing core dependencies manually:
BiocManager::install(c("AnnotationDbi", "annotatr", "BiocGenerics",
                       "GenomeInfoDb", "GenomicFeatures", "GenomicRanges",
                       "IRanges", "org.Hs.eg.db", "rtracklayer",
                       "TxDb.Hsapiens.UCSC.hg38.knownGene", "data.table"))
```

**Problem**: Compilation errors on Linux <br>
**Solution**: Install required system dependencies:

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y libxml2-dev libcurl4-openssl-dev libssl-dev

# CentOS/RHEL  
sudo yum install libxml2-devel openssl-devel libcurl-devel
```
