---
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.

<br>
```{r, echo=FALSE, out.width="100%", fig.align="center"}
knitr::include_graphics("figures/20250925_graphical_abstract_rChEA3_v1.png")
```
<br>

# 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