Title:	R Client for the 'ChEA3' Transcription Factor Enrichment API
Version:	0.2.0
Description:	Interface to the 'ChEA3' transcription factor enrichment API. 'ChEA3' integrates evidence from ChIP-seq, co-expression, and literature resources to prioritize transcription factors regulating a given set of genes. This package provides convenient R functions to query the API, retrieve ranked results across collections (including integrated scores), and standardize output for downstream analysis in R/Bioconductor workflows. See https://maayanlab.cloud/chea3/ or Keenan (2019) <doi:10.1093/nar/gkz446> for further details.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
URL:	https://github.com/ckntav/rChEA3, https://ckntav.github.io/rChEA3/
BugReports:	https://github.com/ckntav/rChEA3/issues
Imports:	cli, crayon, dplyr, ggplot2, httr, jsonlite, lubridate, rlang, tidyselect, writexl
Depends:	R (≥ 4.1.0)
LazyData:	true
Suggests:	knitr, readxl, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-10-09 02:20:14 UTC; chris
Author:	Christophe Tav [aut, cre]
Maintainer:	Christophe Tav <christophe.tav@gmail.com>
Repository:	CRAN
Date/Publication:	2025-10-15 19:10:02 UTC

A549 Downregulated Genes (Dex)

Description

Example gene set of downregulated (repressed) genes in A549 cells after dexamethasone treatment. To keep the dataset small and suitable for examples and tests, only the first 15 downregulated gene symbols are included here.

Usage

a549_dex_downreg

Format

A character vector of length 15, containing HGNC gene symbols.

Details

The full list of differentially expressed genes (activated and repressed) is provided as Supplementary Table S3 in Tav et al. (2023). The raw Excel file can be downloaded directly from Frontiers in Genetics: https://www.frontiersin.org/api/v4/articles/1237092/file/Table_3.XLSX/1237092_supplementary-materials_tables_3_xlsx/1.

In this package, we subset the data to only the first 15 repressed genes, which are stored in the object a549_dex_downreg.

Source

Supplementary Table S3 from Tav et al. (2023).

References

Tav C, Fournier É, Fournier M, Khadangi F, Baguette A, Côté MC, Silveira MAD, Bérubé-Simard F-A, Bourque G, Droit A, Bilodeau S (2023). "Glucocorticoid stimulation induces regionalized gene responses within topologically associating domains." Frontiers in Genetics. doi:10.3389/fgene.2023.1237092

Examples

# Load dataset
data(a549_dex_downreg)
a549_dex_downreg

Print the top-n rows for each ChEA3 collection

Description

Print the top-n rows for each ChEA3 collection

Usage

displayTopN(
  results,
  n = 10,
  columns = c("Rank", "TF", "Scaled Rank", "Set_name", "Intersect", "Score",
    "FET p-value", "FDR", "Odds Ratio")
)

Arguments

Value

(Invisibly) a named list of data frames, each truncated to the first n rows (and columns if provided).

Examples

    genes <- c("TP53", "MYC", "STAT3", "FOXO1", "BRCA1")
    results <- queryChEA3(genes, verbose = FALSE)

    # Display top 10 TFs from each collection
    displayTopN(results)

    # Display only top 5 with specific columns
    displayTopN(results, n = 5, columns = c("Rank", "TF", "Score", "FDR"))

Export rChEA3 Results to Excel

Description

Write a rChEA3 results object (named list of data frames, one per collection) to an Excel workbook, with one sheet per collection.

Usage

exportResults(
  results,
  output_dir,
  output_file = "rChEA3_results",
  with_date = TRUE,
  verbose = TRUE
)

Arguments

Value

(Invisibly) the full path to the saved .xlsx file.

Examples

    data(a549_dex_downreg)
    results <- queryChEA3(genes = a549_dex_downreg, query_name = "test_a549_dex_downreg")
    exportResults(results,
    output_dir = tempdir(),
    output_file = "rChEA3_results_a549_dex_downreg.xlsx")

Query ChEA3 API for TF enrichment

Description

#' Sends a gene list to the ChEA3 web service to identify enriched transcription factors using multiple evidence sources. The gene list should consist of HGNC-approved gene symbols.

Usage

queryChEA3(genes, query_name = "rChEA3_query", verbose = TRUE)

Arguments

Value

A named list of data frames. Each element corresponds to a ChEA3 collection and contains an enrichment table with transcription factors and their statistics. The expected names are: c("Integrated–meanRank", "Integrated–topRank", "GTEx–Coexpression", "ARCHS4–Coexpression", "ENCODE–ChIP-seq", "ReMap–ChIP-seq", "Literature–ChIP-seq", "Enrichr–Queries").

Examples

    results <- queryChEA3(c("SMAD9","FOXO1","MYC","STAT1","STAT3","SMAD3"))
    names(results)
    head(results[["Integrated--meanRank"]])

Save a Visualization to File (PDF, PNG, or SVG)

Description

This function saves a visualization object to a file in the specified format and directory. It supports visualizations generated by chea3_visualizeRank(), ggplot2, or any other plot object that can be rendered using print() inside a graphics device. Optionally, the current date (stored in the today variable) can be prepended to the filename.

Usage

saveViz(
  viz,
  output_dir,
  output_file = "figure_rChEA3",
  format = "pdf",
  with_date = TRUE,
  width = 8,
  height = 5,
  resolution = 300,
  verbose = TRUE
)

Arguments

Value

The visualization is saved to a file on disk. Invisibly returns the full path to the saved file.

Examples

    genes <- c("TP53", "MYC", "STAT3")
    results <- queryChEA3(genes, verbose = FALSE)
    meanRank_res <- results[["Integrated--meanRank"]]

    # Create visualization
    viz <- visualizeRank(meanRank_res)

    # Save as PDF
    saveViz(viz, output_dir = tempdir(), output_file = "chea3_results")

    # Save as PNG with custom dimensions
    saveViz(viz, output_dir = tempdir(), output_file = "chea3_results",
            format = "png", width = 10, height = 6)

Today's Date at Package Load Time

Description

This variable stores the current date (in "yyyymmdd" format) at the time the package is loaded. It is useful for reproducible filenames (e.g., in saveViz()), and is automatically set when the package is attached.

Usage

today

Format

A character string (e.g., "20250908").

Examples

# Print the date stored at package load
library(rChEA3)
today

# Use it in a filename
paste0(today, "_rCHEA3_plot_meanRank.pdf")

Visualize top transcription factors (TFs) from ChEA3 results

Description

Create a bar plot of the most significant transcription factors from a ChEA3 result table. The y-axis can be based on FDR, ⁠FET p-value⁠, or Score (for integrated results). Bars are ordered by rank (Rank = 1 at the top).

Usage

visualizeRank(
  df_result,
  y_metric = c("auto", "FDR", "FET p-value", "Score"),
  fdr_threshold = 0.05,
  p_threshold = 0.05,
  query_name = "myGeneList",
  title_plot = "rChEA3 results (transcription factor enrichment analysis)",
  top_n = 10,
  fill_color = "#7AAACE"
)

Arguments

Details

The plot subtitle automatically reports the number of significant TFs (after filtering by fdr_threshold or p_threshold when applicable), while top_n controls how many of those TFs are displayed. For integrated collections (⁠Mean Rank⁠ and ⁠Top Rank⁠), the subtitle shows a descriptive label instead of individual library names.

Value

A ggplot object.

Examples

# Example with integrated meanRank results
genes <- c("STAT3", "RELA", "MYC", "FOXO1", "TP53")
results <- queryChEA3(genes, verbose = FALSE)
meanRank_res <- results[["Integrated--meanRank"]]
visualizeRank(meanRank_res, y_metric = "Score", top_n = 15)

# Example with ChIP-seq results (FET p-value-based)
chip_res <- results[["ENCODE--ChIP-seq"]]
visualizeRank(chip_res, y_metric = "FET p-value")