Skip to contents

ercantools

Overview

ercantools is an R package providing a suite of visualization and statistical analysis functions for ChIP-seq differential binding data. It is designed to work directly with DiffBind output and focuses on dosage compensation analysis in C. elegans, comparing binding patterns on the X chromosome versus autosomes.

The package bundles functions for violin plots, MA/MD plots, distribution plots, chromosome-level t-test scatter plots, and genomic peak overlap utilities, all designed to produce publication-ready figures with minimal setup.

Installation

Prerequisites

ercantools depends on two Bioconductor packages. Install them before installing the package:

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

BiocManager::install(c("GenomicRanges", "IRanges", "S4Vectors"))

Install from GitHub 

# install.packages("devtools")
devtools::install_github("ercanlab/ercantools")

Install the development branch 

devtools::install_github("ercanlab/ercantools", ref = "develop")

Quick start 

library(ercantools)

# Load the built-in example dataset (mimics DiffBind output)
data(example_peaks)
head(example_peaks)

# Compare log2FC between chrX and autosomes
violin_log2FC(
  object          = example_peaks,
  title           = "log2FC: chrX vs autosomes",
  chr_of_interest = "chrX",
  ylim            = c(-3, 3)
)

Features

  • Violin + box plots: compare log2 fold-change or normalized binding counts between chromosomes.
  • MA / MD plots: visualize log2 fold-change against average concentration(normalized binding counts) with significance coloring.
  • Distribution plots: density and histogram plots of normalized binding counts per condition, faceted by chromosome.
  • T-test scatter plots: chromosome-level Welch t-tests displayed as connected scatter plots to identify which chromosomes change significantly between conditions.
  • Peak overlap utilities: GenomicRanges-based overlap detection using midpoint windows, plus UpSet plots for multi-category intersection visualization.
  • C. elegans defaults: built-in chromosome ordering (chrI–V, chrX) with fully configurable parameters for other organisms.
  • Example dataset: 2,000 synthetic peaks mimicking real DiffBind output for C. elegans dosage compensation experiments.

Documentation

Full documentation is available at the pkgdown website:

https://ercanlab.github.io/ercantools/

Vignettes

Vignette Description
Violin plots Comparing binding distributions between chromosomes
Diagnostic plots MD plots, distributions, and t-test scatter plots

Function reference

Access the documentation for any function directly in R:

?violin_log2FC
?plot_md
?find_overlap_peaks

Or browse the full reference at: https://ercanlab.github.io/ercantools/reference/

Usage examples

1. Violin plot — all chromosomes (log2FC) 

violin_log2FC_all_chr(
  object          = example_peaks,
  title           = "log2FC per chromosome",
  chr_of_interest = "chrX",
  ylim            = c(-3, 3),
  output_pdf      = "violin_all_chr.pdf"
)

2. Violin plot — normalized counts, two conditions 

violin_counts(
  object           = example_peaks,
  title            = "Normalized counts: chrX vs autosomes",
  conc_condition   = "Conc_degron",
  condition_name   = "degron",
  conc_baseline    = "Conc_notag",
  baseline_name    = "notag",
  ylim             = c(0, 16),
  label.y_plot     = c(13, 14, 15, 16)
)

3. MA / MD plot 

plot_md(
  object     = example_peaks,
  x_var      = "Conc",
  y_var      = "Fold",
  fdr_var    = "FDR",
  cutoff_y   = 1,
  cutoff_FDR = 0.05,
  title      = "MD plot — degron vs notag"
)

4. T-test scatter — which chromosomes change? 

res <- ttest_scatter(
  object   = example_peaks,
  title    = "FC t-test per chromosome",
  fc_col   = "Fold"
)
res$plot
head(res$results)

5. Peak overlap detection 

peaks_x <- example_peaks[example_peaks$seqnames == "chrX", ]
peaks_a <- example_peaks[example_peaks$seqnames != "chrX", ]

overlap <- find_overlap_peaks(peaks_x, peaks_a, bp_distance = 200)
cat("Overlap:", overlap$df2_percentage, "\n")

Contributing

Contributions are welcome! Please follow these steps:

Reporting issues

Open an issue at https://github.com/ercanlab/ercantools/issues and include:

  • A minimal reproducible example (use example_peaks if possible)
  • Your R version (R.version.string)
  • Your ercantools version (packageVersion("ercantools"))

Pull requests

  1. Fork the repository and create a new branch from main:

    git checkout -b feature/your-feature-name

  2. Make your changes and add tests if applicable.

  3. Run the full check locally before submitting:

    devtools::document()
devtools::check()

  4. Open a pull request with a clear description of the changes.

Code style

  • Follow the tidyverse style guide
  • Use snake_case for function and variable names
  • Document all exported functions with roxygen2 tags
  • Maximum 80 characters per line
  • Use ggplot2:: prefixes (not library(ggplot2)) inside functions

Running tests 

devtools::test()

Citation

If you use ercantools in your research, please cite:

@misc{garbozo2025ercantools,
  author  = {Garbozo, Daniel and Ercan, Sevinc},
  title   = {{ercantools}: Visualization and Analysis Tools for
             {ChIP}-seq Differential Binding Data},
  year    = {2025},
  url     = {https://github.com/ercanlab/ercantools},
  note    = {R package version 0.1.0}
}

License

MIT © Daniel Garbozo — see LICENSE for details.

Acknowledgments

  • Ercan Lab — New York University, for the biological context and experimental data that motivated this package. —

Roadmap

Planned features for future versions:

  • plot_pca() — PCA based on normalized binding counts
  • plot_heatmap() — binding signal heatmap across conditions
  • plot_igv_track() — IGV-style genome browser track plots
  • plot_cluster() — peak clustering visualization
  • Support for additional organisms beyond C. elegans