rChEA3: An R client for ChEA3 transcription factor enrichment API
In rChEA3: R Client for the 'ChEA3' Transcription Factor Enrichment API

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

```{css, echo=FALSE} pre code { font-size: 0.85em; line-height: 1.5; }

# Introduction

rChEA3 is an R client for the [ChEA3](https://maayanlab.cloud/chea3/) transcription factor enrichment API.

While ChEA3 is only available online as a web server, rChEA3 provides access to this tool directly in R, streamlining transcription factor enrichment into your workflow. Submit gene lists, retrieve TF rankings from multiple evidence sources (ChIP-seq, co-expression, literature), and integrate results into your R/Bioconductor analysis pipeline.

The package includes convenient functions to query the API, retrieve results across collections, prepare outputs for downstream analysis, and generate publication-ready figures.

<br>
```r
knitr::include_graphics("figures/20250925_graphical_abstract_rChEA3_v1.png")

Example workflow

This section demonstrates a typical workflow with rChEA3, from submitting a gene list to retrieving transcription factor enrichment results. The examples illustrate how to interact with the ChEA3 API, explore the different collections, and visualize results in a clear, publication-ready format.

We start by loading the package:

library(rChEA3)

1. Submit a gene list

Provide a vector of gene symbols as input. The gene list should consist of HGNC-approved gene symbols, as ChEA3 only accepts these standardized gene identifiers.

genes <- c("TP53", "ESR1", "MYC", "NIPBL", "BRCA1")
results <- queryChEA3(genes)

Note: For detailed information about the different ChEA3 collections and their underlying methodology, see Keenan et al., 2019.

2. Inspect top results

The function displayTopN() allows a quick inspection of the results by showing the top transcription factors from each collection. By default, the top 10 transcription factors are displayed without applying thresholds.

displayTopN(results)

3. Extract the result for one particular collection

Each ChEA3 collection can be accessed by name. For example, to retrieve the integrated ranking:

meanRank_results <- results[["Integrated--meanRank"]]
head(meanRank_results)

4. Generate the visualization

visualizeRank(meanRank_results)

Session info

sessionInfo()

Citation

If you use this package, please cite:

Keenan, A.B., Torre, D., Lachmann, A., Leong, A.K., Wojciechowicz, M.L., Utti, V., Jagodnik, K.M., Kropiwnicki, E., Wang, Z., & Ma'ayan, A. (2019). ChEA3: transcription factor enrichment analysis by orthogonal omics integration. Nucleic Acids Research, 47(W1), W212–W224. doi:10.1093/nar/gkz446