top.alex.waterfall.plots: Generate Waterfall Plots for Top Significant Genes

View source: R/top.alex.waterfall.plots.R

top.alex.waterfall.plotsR Documentation

Generate Waterfall Plots for Top Significant Genes

Description

Generates waterfall plots for genes with significant associations between lesion status and expression level, based on the Kruskal Wallis (KW) test results. Only genes with q-values below a user-specified threshold will be plotted.

Usage

top.alex.waterfall.plots(out.dir, alex.data, alex.kw.results, q, lsn.data)

Arguments

out.dir

A character string specifying the output directory where the waterfall plots for selected genes will be saved. Directory must exist or be created by the user prior to running the function.

alex.data

A list of three data tables returned by alex.prep.lsn.expr:

  • "row.mtch" matching expression and lesion rows by Ensembl gene ID.

  • "alex.expr" matrix of gene expression.

  • "alex.lsn" matrix of lesion status.

All matrices must have rows ordered by Ensembl gene ID and columns ordered by patient ID.

alex.kw.results

A data table of Kruskal Wallis test results, returned by the KW.hit.express function.

q

A numeric threshold indicating the maximum allowed KW q-value for a gene to be included in the waterfall plots.

lsn.data

Lesion data provided in GRIN-compatible format (as used in alex.prep.lsn.expr).

Details

For each gene in the alex.kw.results table with a q-value less than or equal to the user-specified q threshold, the function generates a waterfall plot displaying the relationship between lesion status and gene expression level. Each plot is saved as a separate PDF file in the out.dir folder.

Internally, this function relies on helper functions such as alex.waterfall.prep and alex.waterfall.plot to prepare and render the plots.

Value

No object is returned to the R environment. The function creates a set of PDF files (one per gene) in the specified out.dir directory. Each file contains a labeled waterfall plot illustrating gene expression across different lesion groups.

Author(s)

Abdelrahman Elsayed abdelrahman.elsayed@stjude.org, Stanley Pounds stanley.pounds@stjude.org

References

Cao, X., Elsayed, A. H., & Pounds, S. B. (2023). Statistical Methods Inspired by Challenges in Pediatric Cancer Multi-omics.

See Also

alex.prep.lsn.expr, KW.hit.express, alex.waterfall.prep, alex.waterfall.plot

Examples

data(expr_data)
data(lesion_data)
data(hg38_gene_annotation)

# 1) Prepare matched expression and lesion matrices:
alex.data <- alex.prep.lsn.expr(expr_data, lesion_data,
                                hg38_gene_annotation,
                                min.expr = 5, min.pts.lsn = 5)
# 2) Run Kruskal Wallis test:
alex.kw.results <- KW.hit.express(alex.data,
                                  hg38_gene_annotation,
                                  min.grp.size = 5)

# 3) Create temporary output folder and generate waterfall plots:
dir.create(resultsFolder <- file.path(tempdir(), "temp.out"))
waterfall.plts <- top.alex.waterfall.plots(out.dir = resultsFolder,
                                           alex.data = alex.data,
                                           alex.kw.results = alex.kw.results,
                                           q = 1e-15,
                                           lsn.data = lesion_data)

# Clean up:
unlink(resultsFolder, recursive = TRUE)

GRIN2 documentation built on June 17, 2025, 9:11 a.m.