---
title: "rChEA3: An R client for ChEA3 transcription factor enrichment API"
author: "Christophe Tav"
date: "`r format(Sys.Date(), '%B %Y')`"
output:
html_document:
toc: true
toc_depth: 3
number_sections: false
vignette: >
%\VignetteIndexEntry{rChEA3}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
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.
```{r, echo=FALSE, out.width="100%", fig.align="center"}
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:
```{r setup}
library(rChEA3)
```
## 1. Submit a gene list
Provide a vector of gene symbols as input. The gene list should consist of [HGNC](https://www.genenames.org)-approved gene symbols, as ChEA3 only accepts these standardized gene identifiers.
```{r submit}
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](https://doi.org/10.1093/nar/gkz446).
## 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.
```{r inspect}
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:
```{r extract}
meanRank_results <- results[["Integrated--meanRank"]]
head(meanRank_results)
```
## 4. Generate the visualization
```{r visualize}
visualizeRank(meanRank_results)
```
# Session info
```{r 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](https://doi.org/10.1093/nar/gkz446)
# Resources
- [ChEA3 Web Server](https://maayanlab.cloud/chea3/) - Interactive tool and detailed documentation
- [ChEA3 Publication](https://doi.org/10.1093/nar/gkz446) - Original research article
- [rChEA3 GitHub](https://github.com/ckntav/rChEA3) - Package source code and issues