Package 'rChEA3'

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

results	A named list of data frames (the output of queryChEA3()).
n	Number of rows to show per table (default: 10).
columns	Optional character vector of column names to display (keeps intersection with what's present in each data frame).

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

results	A named list of data frames (e.g., the return of queryChEA3()), where each element corresponds to a ChEA3 collection (e.g., "Integrated–meanRank", "ENCODE–ChIP-seq", etc.). A single data frame is also accepted and will be written to one sheet.
output_dir	A string specifying the output directory. This parameter is required and has no default.
output_file	Base file name (without extension). Default: "rChEA3_results".
with_date	Logical; if TRUE, prepend today's date (ISO, YYYY-MM-DD) to the file name. Default: TRUE.
verbose	Logical; if TRUE, print the saved path. Default: TRUE.

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,
  url = "https://maayanlab.cloud/chea3/api/enrich/"
)

Arguments

genes	Character vector of HGNC gene symbols.
query_name	Optional query name (default: "rChEA3_query").
verbose	Logical; if TRUE, print a grouped summary of available result collections (default: TRUE).
url	Character; full URL of the ChEA3 enrichment endpoint. Defaults to the public API at "https://maayanlab.cloud/chea3/api/enrich/". Override this to point at a local or self-hosted ChEA3 instance (see https://github.com/MaayanLab/chea3). The URL must include the full enrich/ path.

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"]])

    # Querying a local ChEA3 server
    # results <- queryChEA3(
    #     c("SMAD9","FOXO1","MYC"),
    #     url = "http://localhost:8080/chea3/api/enrich/"
    # )

---

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

viz	A visualization object typically created by visualizeRank(), but can also be a ggplot2 plot or any other plot object printable with print().
output_dir	A string specifying the output directory. This parameter is required and has no default.
output_file	A string specifying the base filename (without extension). Defaults to "viz_rChEA3".
format	Output format. One of "pdf", "png", or "svg". Defaults to "pdf".
with_date	Logical (default TRUE). Whether to prepend the current date (from today) to the filename.
width	Width of the output file in inches. Default is 8.
height	Height of the output file in inches. Default is 5.
resolution	Resolution in DPI (only used for PNG). Default is 300.
verbose	Logical. If TRUE, print a message with the saved path. Default TRUE.

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

df_result	A ChEA3 result data frame. Must contain at least columns: TF (transcription factor symbol), Rank (integer rank). Optionally: FDR, ⁠FET p-value⁠, Score.
y_metric	Character; which metric to use on the y-axis. One of: "auto" (default): use FDR if present, otherwise FET p-value, otherwise Score. "FDR": use FDR (requires FDR column). "FET p-value": use Fisher’s exact test p-value (requires ⁠FET p-value⁠ column). "Score": use Score (used in integrated meanRank/topRank).
fdr_threshold	Numeric; FDR cutoff for significance (default 0.05). Used only if y_metric = "FDR".
p_threshold	Numeric; p-value cutoff for significance (default 0.05). Used only if y_metric = "FET p-value".
query_name	Character; name of the input gene set, shown in the subtitle (default myGeneList)
title_plot	Character; main plot title (default ⁠rChEA3 results (transcription factor enrichment analysis)⁠)
top_n	Integer; number of TFs to display (default 10). The subtitle reports the total number of significant TFs, while only the top_n by rank are plotted.
fill_color	Character; fill color of the bars (default "#7AAACE").

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")

---