Package 'VISTA'

Description

Builds a DESeq2::DESeqDataSet from the raw counts retained in a VISTA object, so an analysis can be continued or re-run with DESeq2 directly.

Usage

as_deseq_dataset(x, design = NULL)

Arguments

Details

This is deliberately explicit rather than making DESeq2::DESeqDataSet(v, design) work implicitly: the inherited SummarizedExperiment method would pick up whichever assay comes first, which is norm_counts, and fail because those values are not integers.

Counts are rounded to integers, as DESeq2 requires.

Value

A DESeqDataSet.

Examples

v <- example_vista()
if (requireNamespace("DESeq2", quietly = TRUE)) {
  dds <- as_deseq_dataset(v)
  class(dds)
}

Description

Convert a pre-existing SummarizedExperiment into a valid VISTA object.

Usage

as_vista(
  se,
  assay_name = "norm_counts",
  group_column,
  comparisons = list(),
  deg_summary = list(),
  cutoffs = list(),
  group_palette = "Dark 3",
  raw_counts = NULL,
  validate = TRUE
)

Arguments

Value

A VISTA object.

Examples

mat <- matrix(rnorm(60), nrow = 10)
rownames(mat) <- paste0("gene", seq_len(nrow(mat)))
colnames(mat) <- paste0("sample", seq_len(ncol(mat)))
se <- SummarizedExperiment::SummarizedExperiment(
  assays = list(norm_counts = mat),
  colData = S4Vectors::DataFrame(
    cond = rep(c("A", "B"), each = 3),
    row.names = colnames(mat)
  ),
  rowData = S4Vectors::DataFrame(
    gene_id = rownames(mat),
    row.names = rownames(mat)
  )
)
v <- as_vista(se, group_column = "cond")
v

Description

Run VISTA and independent DESeq2, edgeR, and limma pipelines with the same filtering, design, contrast definitions, and DEG thresholds, then compare the retained genes, normalized matrices, every numeric column the engine reports, DEG calls, and critical plot inputs.

Usage

benchmark_vista_equivalence(
  counts,
  sample_info,
  column_geneid,
  group_column,
  group_numerator,
  group_denominator,
  methods = c("deseq2", "edger", "limma"),
  min_counts = 10,
  min_replicates = 1,
  log2fc_cutoff = 1,
  pval_cutoff = 0.05,
  p_value_type = "padj",
  covariates = NULL,
  design_formula = NULL,
  tolerance = 1e-08,
  return_plots = FALSE,
  edger_test = c("LRT", "QL")
)

Arguments

Details

The reference pipelines are written independently of the code they check. They call only base R, stats and the engines' own functions – never VISTA's internal helpers – and re-implement VISTA's documented contract from scratch:

• Samples are matched to count columns by a sample_names column, else by non-default rownames, else by the first of sample_name, sample, sample_id, Run, run, Sample and SampleName whose values name count columns (the rule documented for sample_info in create_vista()).

• Filtering treats missing counts as zero and keeps genes whose total reaches min_counts and that reach min_counts in at least min_replicates samples. For DESeq2, non-integer counts (estimated counts from tximport or RSEM) are then rounded, as DESeq2 requires.

• Tests are DESeq2's Wald test via results(), edgeR's glmLRT() or, with edger_test = "QL", glmQLFit() and glmQLFTest(), and limma's eBayes() after voom().

• Design is ~ covariates + group for DESeq2 and the same terms without an intercept for edgeR and limma-voom, or design_formula when supplied.

• Contrasts for edgeR and limma are the difference between the design rows of two samples that differ only in group, so they do not depend on how design columns are named or which level is the reference.

• DEG calls are Up when log2FC >= log2fc_cutoff and the selected p-value <= pval_cutoff, Down symmetrically, and Other otherwise, including when the engine reports no p-value.

VISTA's DE tables and normalized counts are read through its exported accessors (comparisons(), norm_counts()). The MA, PCA and DEG-count checks read the data get_ma_plot(), get_pca_plot() and the DEG-count plots draw; the volcano check rebuilds its inputs from the stored table. Rows are matched by gene identifier, not position, and the set of comparisons must agree as well. A defect in sample matching, design construction, contrast signs, DEG calling or row alignment therefore shows up as a mismatch instead of being reproduced on both sides. The two sides share only the engines and the contract above: the benchmark checks that VISTA runs DESeq2, edgeR and limma faithfully, not that those packages are correct.

Value

A list with fields valid, comparison_summary, visual_summary, and methods. comparison_summary has one row per method and comparison recording whether the retained gene set, normalized counts, every numeric column the engine reports (columns_compared), regulation calls and DEG sets agree, with the largest absolute difference for the main columns. A ⁠*_within_tolerance⁠ field is NA when the engine does not report that column (edgeR reports logCPM, not baseMean). Each element of methods contains the VISTA object, the reference results, structural validation output, self-consistency checks, and optional plot objects.

Examples

v <- example_vista()
si <- as.data.frame(sample_info(v))
data("count_data", package = "VISTA")
count_subset <- count_data[seq_len(500), c("gene_id", si$sample_names), drop = FALSE]

bm <- benchmark_vista_equivalence(
  counts = count_subset,
  sample_info = si,
  column_geneid = "gene_id",
  group_column = "cond_long",
  group_numerator = "treatment1",
  group_denominator = "control",
  methods = "limma",
  min_counts = 5,
  min_replicates = 1
)

bm$comparison_summary


data("count_data", package = "VISTA")
data("sample_metadata", package = "VISTA")

target_groups <- c("control", "treatment1")
sample_subset <- sample_metadata[sample_metadata$cond_long %in% target_groups, ]
count_subset <- count_data[seq_len(150), c("gene_id", sample_subset$sample_names)]

bm <- benchmark_vista_equivalence(
  counts = count_subset,
  sample_info = sample_subset,
  column_geneid = "gene_id",
  group_column = "cond_long",
  group_numerator = "treatment1",
  group_denominator = "control",
  methods = c("deseq2", "edger"),
  min_counts = 5,
  min_replicates = 1
)

bm$comparison_summary
bm$visual_summary

Description

A count matrix derived from the Bioconductor airway dataset and formatted for VISTA examples. The first column stores Ensembl gene IDs; the remaining columns are sample-level counts.

Usage

data(count_data)

Format

A tibble with 63,677 rows and 9 columns.

gene_id

Character column storing Ensembl gene identifiers.

SRR1039508

Numeric count values for airway sample SRR1039508.

SRR1039509

Numeric count values for airway sample SRR1039509.

SRR1039512

Numeric count values for airway sample SRR1039512.

SRR1039513

Numeric count values for airway sample SRR1039513.

SRR1039516

Numeric count values for airway sample SRR1039516.

SRR1039517

Numeric count values for airway sample SRR1039517.

SRR1039520

Numeric count values for airway sample SRR1039520.

SRR1039521

Numeric count values for airway sample SRR1039521.

Source

Derived from the airway Bioconductor dataset.

Description

Returns the filtered raw count matrix stored alongside the normalized counts. Objects built before VISTA 1.2.0, or with create_vista(keep_raw_counts = FALSE), do not carry one.

Usage

## S4 method for signature 'VISTA'
counts(object, ...)

Arguments

Details

Normalized counts are not invertible, so BiocGenerics::updateObject() cannot back-fill this assay for an older object; it has to be rebuilt with create_vista().

Value

A numeric matrix of raw counts with genes in rows and samples in columns.

Examples

v <- example_vista()
counts(v)[seq_len(3), seq_len(3)]

Description

This wrapper performs differential expression (DE) analysis (DESeq2, edgeR, limma, or both) and returns a fully initialized VISTA object. The object stores expression matrices and annotations in the SummarizedExperiment core, while all DE outputs and configuration live in metadata(vista):

• $de_results: named SimpleList of per-contrast DE tables

• $de_summary: named SimpleList of summary tables

• $de_cutoffs: list of thresholds/method options

• $group: list with column, palette, colors

Usage

create_vista(
  counts,
  sample_info,
  column_geneid,
  group_column,
  group_numerator,
  group_denominator,
  method = c("deseq2", "edger", "limma", "both"),
  min_counts = 10,
  min_replicates = 1,
  log2fc_cutoff = 1,
  pval_cutoff = 0.05,
  p_value_type = "padj",
  covariates = NULL,
  design_formula = NULL,
  consensus_mode = c("intersection", "union"),
  consensus_log2fc = c("mean", "deseq2", "edger"),
  result_source = NULL,
  group_palette = "Dark 2",
  comparison_palette = "Dark 3",
  keep_raw_counts = TRUE,
  validate = TRUE,
  edger_test = c("LRT", "QL")
)

Arguments

Details

Contrast names follow "numerator_VS_denominator". Each DE table must have rownames identical to the final norm_counts rownames. When method = "both", method-specific and consensus DE tables are stored in metadata(v)$de_results_by_method and metadata(v)$de_summary_by_method, and the active source is tracked in metadata(v)$de_active_source.

In the consensus table, log2fc follows consensus_log2fc, while pvalue and padj carry the less-significant of the two backends (a gene a backend did not test counts as p = 1) so the columns remain continuous and usable for volcano/MA plots and ranking. With consensus_mode = "union", genes called by a single backend take that backend's estimate and p-values instead, so every called gene's columns agree with its call. The merged padj is a conservative ranking score, not an FDR-adjusted p-value of the consensus, and regulation is the call: in simulations the intersection lowered, but did not control, the false discovery rate of the single backends, and the union raised it. Per-backend values are always preserved alongside them in log2fc_deseq2, log2fc_edger, pvalue_deseq2, pvalue_edger, padj_deseq2, and padj_edger, and the support column records which backends called each gene ("both", "deseq2_only", "edger_only", "discordant", or "none").

Value

A VISTA object:

• assays(v): norm_counts (matrix)

• colData(v): sample_info (DataFrame)

• rowData(v): row_data (DataFrame)

• metadata(v): de_results, de_summary, de_cutoffs, group, comparison, provenance

See Also

as_vista, VISTA-class, qualitative_hcl

Examples

# Load example data
data("count_data", package = "VISTA")
data("sample_metadata", package = "VISTA")

# Create VISTA object with DESeq2 (default method)
vista <- create_vista(
  counts = count_data[seq_len(100), ],
  sample_info = sample_metadata[seq_len(6), ],
  column_geneid = "gene_id",
  group_column = "cond_long",
  group_numerator = "treatment1",
  group_denominator = "control",
  log2fc_cutoff = 0.6,
  pval_cutoff = 0.05
)

# Examine the VISTA object
vista

# Access comparisons
names(comparisons(vista))

# View DEG summary
deg_summary(vista)

# View cutoffs used
cutoffs(vista)

# Multiple comparisons example

vista_multi <- create_vista(
  counts = count_data,
  sample_info = sample_metadata,
  column_geneid = "gene_id",
  group_column = "cell",
  group_numerator = c("N052611", "N080611"),
  group_denominator = c("N61311", "N61311"),
  method = "edger",
  log2fc_cutoff = 1.0,
  pval_cutoff = 0.01
)

Description

derive_vista_metadata() creates a starter sample_info table from count sample names. It is intended for projects where users have count columns but do not yet have a separate metadata sheet. The derived table can be edited, passed through read_vista_metadata(), and then aligned with match_vista_inputs().

Usage

derive_vista_metadata(
  counts,
  column_geneid = NULL,
  sample_names = NULL,
  parser = c("auto", "split", "regex", "none"),
  split = "_",
  fields = NULL,
  pattern = NULL,
  sample_column = "sample_names",
  repair_sample_names = c("auto", "none"),
  return_type = c("data.frame", "template"),
  verbose = TRUE
)

Arguments

Value

A data frame containing sample_names plus any parsed metadata columns.

Examples

data("count_data", package = "VISTA")
data("sample_metadata", package = "VISTA")

counts_in <- count_data[seq_len(8), c("gene_id", sample_metadata$sample_names[seq_len(6)]), drop = FALSE]
meta <- derive_vista_metadata(
  counts_in,
  column_geneid = "gene_id",
  parser = "regex",
  pattern = "SRR(\\d+)",
  fields = "run_id"
)
head(meta)

Description

This function performs ORA on a set of genes from a VISTA object. Gene identifiers stored as “ENSG00000187634:SAMD11” will be split at the colon and the appropriate part extracted based on from_type. Genes are then optionally converted via orgdb to match the identifier type required by the MSigDB gene sets.

Usage

enrichMsigDB(
  x,
  gene_list,
  from_type = "SYMBOL",
  orgdb,
  msigdb_category = "H",
  msigdb_subcategory = NULL,
  species = "Mus musculus",
  background = NULL,
  col_genetype = "GENETYPE",
  feature_type = "protein-coding",
  ...
)

Arguments

Value

A list containing a single enrichResult object named "enrich".

Examples

v <- example_vista()
genes <- head(as.character(row_data(v)$gene_id), 20)
if (requireNamespace('msigdbr', quietly = TRUE)) {
  out <- try(enrichMsigDB(v, gene_list = genes, from_type = 'ENSEMBL', msigdb_category = 'H'), silent = TRUE)
  if (!inherits(out, 'try-error')) out
}

Description

Creates a lightweight VISTA object from built-in package datasets (count_data and sample_metadata) for use in examples and tutorials. The default call returns a precomputed object to keep examples and package checks fast. Non-default argument combinations fall back to rebuilding the object from the packaged example inputs.

Usage

example_vista(n_genes = 150, n_per_group = 3, method = "deseq2")

Arguments

Value

A VISTA object.

Examples

v <- example_vista()
v

Description

Generates a standardized folder with selected VISTA plots, tabular outputs, and a manifest describing all saved files.

Usage

export_vista_assets(
  x,
  out_dir = "vista_assets",
  sample_comparison = NULL,
  display_id = NULL,
  include_plots = c("pca", "mds", "corr_heatmap", "deg_bar", "volcano", "ma",
    "expression_heatmap"),
  include_data = c("comparison", "norm_counts", "sample_info", "row_data", "deg_summary",
    "cutoffs"),
  plot_format = "png",
  width = 8,
  height = 6,
  heatmap_height = 10,
  units = "in",
  dpi = 300,
  top_n_labels = 50,
  heatmap_n_genes = 60,
  write_excel = FALSE,
  overwrite = TRUE
)

Arguments

Value

Invisibly, a list with out_dir, sample_comparison, manifest, plot_files, and data_files.

Examples

v <- example_vista()
out_dir <- file.path(tempdir(), "vista_assets_example")
res <- export_vista_assets(
  v,
  out_dir = out_dir,
  include_plots = "pca",
  include_data = "comparison"
)
names(res)

Description

Retrieve stored cell fraction estimates

Usage

get_cell_fractions(x)

Arguments

Value

A data.frame of cell fraction estimates with samples in rows.

Examples

v <- example_vista()
if (requireNamespace('xCell2', quietly = TRUE)) {
  vx <- try(run_cell_deconvolution(v, method = 'xCell2'), silent = TRUE)
  if (!inherits(vx, 'try-error')) head(get_cell_fractions(vx))
}

Description

Plot cell-type composition as stacked bars

Usage

get_celltype_barplot(
  x,
  group_column = NULL,
  sample_names = NULL,
  base_size = 12,
  cell_types = NULL,
  top_n = NULL,
  collapse_other = TRUE,
  normalize = c("sample", "none"),
  facet_by = c("group", "none")
)

Arguments

Value

A ggplot object.

Examples

mat <- matrix(rpois(20, lambda = 20), nrow = 5)
rownames(mat) <- paste0("gene", seq_len(5))
colnames(mat) <- paste0("sample", seq_len(4))
se <- SummarizedExperiment::SummarizedExperiment(
  assays = list(norm_counts = mat),
  colData = S4Vectors::DataFrame(
    cond = c("A", "A", "B", "B"),
    row.names = colnames(mat)
  ),
  rowData = S4Vectors::DataFrame(
    gene_id = rownames(mat),
    row.names = rownames(mat)
  )
)
v <- as_vista(se, group_column = "cond")
md <- S4Vectors::metadata(v)
md$cell_fractions <- data.frame(
  fibroblast = c(0.2, 0.3, 0.4, 0.5),
  epithelial = c(0.8, 0.7, 0.6, 0.5),
  row.names = colnames(mat)
)
S4Vectors::metadata(v) <- md
get_celltype_barplot(v, group_column = "cond")

Description

Plot group-level deconvolution scores as dot plot

Usage

get_celltype_group_dotplot(
  x,
  group_column = NULL,
  cell_types = NULL,
  top_n = 12,
  summary_fun = c("mean", "median"),
  errorbar = c("se", "sd", "none"),
  add_points = TRUE,
  point_size = 2.5,
  base_size = 12,
  error = NULL
)

Arguments

Value

A ggplot object.

Examples

mat <- matrix(rpois(20, lambda = 20), nrow = 5)
rownames(mat) <- paste0("gene", seq_len(5))
colnames(mat) <- paste0("sample", seq_len(4))
se <- SummarizedExperiment::SummarizedExperiment(
  assays = list(norm_counts = mat),
  colData = S4Vectors::DataFrame(
    cond = c("A", "A", "B", "B"),
    row.names = colnames(mat)
  ),
  rowData = S4Vectors::DataFrame(
    gene_id = rownames(mat),
    row.names = rownames(mat)
  )
)
v <- as_vista(se, group_column = "cond")
md <- S4Vectors::metadata(v)
md$cell_fractions <- data.frame(
  fibroblast = c(0.2, 0.3, 0.4, 0.5),
  epithelial = c(0.8, 0.7, 0.6, 0.5),
  row.names = colnames(mat)
)
S4Vectors::metadata(v) <- md
get_celltype_group_dotplot(v, group_column = "cond")

Description

Plot cell-type deconvolution heatmap

Usage

get_celltype_heatmap(
  x,
  group_column = NULL,
  sample_names = NULL,
  cell_types = NULL,
  top_n = 20,
  transform = c("none", "zscore", "log1p"),
  cluster_rows = TRUE,
  cluster_columns = TRUE,
  label = FALSE,
  base_size = 11,
  return_type = c("plot", "data", "both")
)

Arguments

Value

A ggplot object, matrix, or list depending on return_type.

Examples

mat <- matrix(rpois(20, lambda = 20), nrow = 5)
rownames(mat) <- paste0("gene", seq_len(5))
colnames(mat) <- paste0("sample", seq_len(4))
se <- SummarizedExperiment::SummarizedExperiment(
  assays = list(norm_counts = mat),
  colData = S4Vectors::DataFrame(
    cond = c("A", "A", "B", "B"),
    row.names = colnames(mat)
  ),
  rowData = S4Vectors::DataFrame(
    gene_id = rownames(mat),
    row.names = rownames(mat)
  )
)
v <- as_vista(se, group_column = "cond")
md <- S4Vectors::metadata(v)
md$cell_fractions <- data.frame(
  fibroblast = c(0.2, 0.3, 0.4, 0.5),
  epithelial = c(0.8, 0.7, 0.6, 0.5),
  row.names = colnames(mat)
)
S4Vectors::metadata(v) <- md
get_celltype_heatmap(v, group_column = "cond")

Description

Plots sample-sample correlation matrix derived from normalized counts with optional clustering and annotations.

Usage

get_corr_heatmap(
  x,
  sample_group = NULL,
  group_column = NULL,
  genes = NULL,
  corr_method = "pearson",
  triangle = c("full", "lower", "upper"),
  order_by = c("correlation", "group", "input", "none"),
  show_diagonal = TRUE,
  label = TRUE,
  show_corr_values = NULL,
  label_color = "black",
  col_corr_values = NULL,
  label_size = 4,
  limits = NULL,
  base_size = 12,
  viridis_option = "viridis",
  viridis_direction = 1,
  viridis_begin = 0,
  viridis_end = 1,
  cluster_by = NULL
)

Arguments

Value

A ggplot2 object showing the sample-by-sample correlation heatmap.

Examples

v <- example_vista()
p <- get_corr_heatmap(v)
print(p)

Description

Plot alluvial diagram showing gene regulation transitions across comparisons

Usage

get_deg_alluvial(x, sample_comparisons, show_other = FALSE)

Arguments

Value

A ggplot object.

Examples

data("count_data", package = "VISTA")
data("sample_metadata", package = "VISTA")
si <- as.data.frame(sample_metadata[seq_len(8), ], stringsAsFactors = FALSE)
trt_idx <- which(si$cond_long == "treatment1")
si$cond_long[trt_idx] <- rep(c("treatment1", "treatment2"), length.out = length(trt_idx))
si$groups <- si$cond_long
v <- create_vista(
  counts = count_data[seq_len(120), c("gene_id", si$sample_names)],
  sample_info = si,
  column_geneid = "gene_id",
  group_column = "cond_long",
  group_numerator = c("treatment1", "treatment2"),
  group_denominator = c("control", "control"),
  min_counts = 5,
  min_replicates = 1
)
if (requireNamespace('ggalluvial', quietly = TRUE)) {
  p <- get_deg_alluvial(v, sample_comparisons = names(comparisons(v)))
  print(p)
}

Description

Barplot of DEG counts (Up/Down) across comparisons

Usage

get_deg_count_barplot(
  x,
  sample_comparisons = NULL,
  label = TRUE,
  base_size = 12,
  colors = c(Up = "red4", Down = "blue4"),
  facet_by = c("none", "regulation", "comparison"),
  facet_scales = "fixed"
)

Arguments

Value

A ggplot2 object with one bar per regulation class.

Examples

v <- example_vista()
p <- get_deg_count_barplot(v)
print(p)

Description

Donut chart of DEG counts (Up/Down) across comparisons

Usage

get_deg_count_donutplot(
  x,
  sample_comparisons = NULL,
  label_type = c("both", "count", "percent", "none"),
  label_digits = 1,
  base_size = 12,
  colors = c(Up = "red4", Down = "blue4"),
  show_other = FALSE,
  other_color = "grey70",
  text_color = "black",
  facet_by = c("comparison", "none"),
  ncol = NULL,
  label = NULL
)

Arguments

Value

A ggplot2 object drawing DEG counts as a donut chart.

Examples

v <- example_vista()
p <- get_deg_count_donutplot(v)
print(p)

Description

Pie chart of DEG counts (Up/Down) across comparisons

Usage

get_deg_count_pieplot(
  x,
  sample_comparisons = NULL,
  label_type = c("both", "count", "percent", "none"),
  label_digits = 1,
  base_size = 12,
  colors = c(Up = "red4", Down = "blue4"),
  show_other = FALSE,
  other_color = "grey70",
  text_color = "black",
  facet_by = c("comparison", "none"),
  ncol = NULL,
  label = NULL
)

Arguments

Value

A ggplot2 object drawing DEG counts as a pie chart.

Examples

v <- example_vista()
p <- get_deg_count_pieplot(v)
print(p)

Description

Visualizes overlaps between DEG sets for two to four comparisons.

Usage

get_deg_venn_diagram(
  x,
  sample_comparisons,
  regulation = "Up",
  palette = "Set 2",
  auto_scale = FALSE,
  show_percentage = TRUE,
  ...
)

Arguments

Value

A ggplot2 object showing the overlap of DEG sets across comparisons.

Examples

v <- example_vista()
comps <- names(comparisons(v))
if (length(comps) >= 2) {
  p <- get_deg_venn_diagram(v, sample_comparisons = comps[seq_len(2)])
  print(p)
}

Description

Draws a chord diagram linking genes to the enriched pathways they belong to. Chords can be coloured by fold-change, regulation direction, or source pathway.

Usage

get_enrichment_chord(
  x,
  vista = NULL,
  sample_comparison = NULL,
  pathways = NULL,
  top_n = 8,
  pathway_column = c("Description", "ID"),
  gene_column = c("auto", "geneID", "core_enrichment"),
  gene_sep = "/",
  min_pathways = 1,
  max_genes = 50,
  gene_order_by = c("none", "foldchange", "abs_foldchange"),
  gene_id_column = NULL,
  display_id = NULL,
  color_by = c("foldchange", "regulation", "pathway"),
  up_color = "#D73027",
  down_color = "#1A9850",
  other_color = "grey70",
  pathway_colors = NULL,
  transparency = 0.4,
  gap_degree = 2,
  label_cex = 0.7,
  title = NULL,
  return_type = c("data", "plot", "both")
)

Arguments

Details

The plot reveals hub genes (those driving multiple enriched terms) and pathway redundancy (terms sharing many genes). This complements get_enrichment_plot() (which shows significance) and get_pathway_heatmap() (which shows expression patterns).

Value

With return_type = "data" (the default), invisibly a list with:

gene_data

Tibble of genes with pathway membership and (optionally) fold-change values.

hub_genes

Character vector of genes appearing in two or more pathways.

The chord diagram is drawn as a side effect.

Examples

v <- example_vista()
msig <- get_msigdb_enrichment(
  v,
  sample_comparison = names(comparisons(v))[1],
  regulation = "Both",
  msigdb_category = "H",
  from_type = "ENSEMBL"
)
get_enrichment_chord(msig, top_n = 5)


data("count_data", package = "VISTA")
data("sample_metadata", package = "VISTA")

vista <- create_vista(
  counts = count_data[seq_len(200), ],
  sample_info = sample_metadata[seq_len(6), ],
  column_geneid = "gene_id",
  group_column = "cond_long",
  group_numerator = "treatment1",
  group_denominator = "control"
)

msig <- get_msigdb_enrichment(
  vista,
  sample_comparison = names(comparisons(vista))[1],
  regulation = "Up", from_type = "ENSEMBL"
)

# Simple: pathway-coloured chords
get_enrichment_chord(msig)

# With fold-change colouring
get_enrichment_chord(
  msig, vista = vista,
  sample_comparison = names(comparisons(vista))[1],
  color_by = "foldchange"
)

# Hub genes only (shared across 2+ pathways)
pw_long <- get_pathway_genes(msig, return_type = "long")
if (any(table(pw_long$gene) >= 2)) {
  get_enrichment_chord(msig, min_pathways = 2)
}

Description

Generates a dot plot of enrichment results for enrichResult, gseaResult, or compareClusterResult objects (including those returned by enrichMsigDB()). Points are sized by gene/set count and coloured by -log10(FDR). For compareCluster results, the plot is faceted by cluster with top terms selected per cluster.

Usage

get_enrichment_plot(x, top_n = 10, title = NULL)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
v <- example_vista()
com <- names(comparisons(v))[1]
if (requireNamespace('msigdbr', quietly = TRUE)) {
  ms <- try(get_msigdb_enrichment(v, sample_comparison = com, regulation = 'Up', from_type = 'ENSEMBL'), silent = TRUE)
  if (!inherits(ms, 'try-error') && !is.null(ms$enrich)) print(get_enrichment_plot(ms$enrich))
}

## End(Not run)

Description

Displays selected genes as grouped summary bars or individual sample-level bars. By default, expression is summarized per group with mean ± SD bars. With by = "sample", each sample is drawn separately.

Usage

get_expression_barplot(
  x,
  genes,
  sample_group = NULL,
  group_column = NULL,
  log_transform = TRUE,
  stats_group = FALSE,
  facet_scale = "free_y",
  facet_scales = facet_scale,
  facet_nrow = NULL,
  facet_ncol = NULL,
  p.label = "p.signif",
  stat_comparisons = NULL,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  by = c("group", "sample"),
  sample_order = c("input", "group", "expression"),
  fill_by = NULL,
  facet_by = c("auto", "gene", "none"),
  max_genes = 25,
  comparisons = NULL
)

Arguments

Value

A ggplot2 object.

Examples

# Create VISTA object
data("count_data", package = "VISTA")
data("sample_metadata", package = "VISTA")

vista <- create_vista(
  counts = count_data[seq_len(200), ],
  sample_info = sample_metadata[seq_len(6), ],
  column_geneid = "gene_id",
  group_column = "cond_long",
  group_numerator = "treatment1",
  group_denominator = "control"
)

# Plot expression for select genes
genes <- rownames(vista)[seq_len(3)]
get_expression_barplot(vista, genes = genes)

# With statistics
get_expression_barplot(vista, genes = genes, stats_group = TRUE)

# Without log transformation
get_expression_barplot(vista, genes = genes, log_transform = FALSE)

Description

Displays per-sample or per-group distributions for selected genes using normalized counts. The x-axis unit is controlled by by, and faceting is controlled explicitly by facet_by.

Usage

get_expression_boxplot(
  x,
  genes = NULL,
  sample_group = NULL,
  group_column = NULL,
  log_transform = TRUE,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  facet_scales = "free_y",
  facet_nrow = NULL,
  facet_ncol = NULL,
  stats_group = FALSE,
  p.label = "p.signif",
  stat_comparisons = NULL,
  pool_genes = FALSE,
  by = "group",
  facet_by = "auto",
  fill_by = NULL,
  sample_order = c("input", "group", "expression"),
  comparisons = NULL
)

Arguments

Value

A ggplot2 object with one box per group (or per sample).

Examples

v <- example_vista()
genes <- head(rownames(v), 3)
p <- get_expression_boxplot(v, genes = genes)
print(p)

Description

Convenience wrapper around get_chromosome_plot() for expression-based colouring (optional group mean, rowData columns, or assay columns).

Usage

get_expression_chromosome_plot(
  x,
  txdb,
  keytype = "GENEID",
  id_column = NULL,
  genes = NULL,
  sample_group = NULL,
  group_column = NULL,
  value_column = NULL,
  value_from = c("rowdata", "assay"),
  value_assay = "norm_counts",
  facet_value_columns = FALSE,
  side_by_side_groups = FALSE,
  paginate = TRUE,
  panels_per_page = 24,
  summarise_replicates = FALSE,
  summarise_method = c("mean", "median"),
  group_value = NULL,
  label_n = 20,
  label_genes = c("top", "all", "none"),
  display_id = NULL,
  line_length = 0.02,
  line_width = 0.6,
  filter_chrom = NULL,
  log_transform = TRUE,
  value_label = "log2(mean expr)"
)

Arguments

Details

• If multiple value_columns are supplied, one plot is produced per column with its own colour legend titled by that column. Chromosomes are laid out top-down in a single column: for each chromosome, plots for all value_columns appear sequentially. Legends for each column are shown only on the first occurrence (at the bottom) to avoid overlap. Requires patchwork; otherwise a list of plots is returned.

• Set side_by_side_groups = TRUE to place selected groups/samples in separate columns for each chromosome (same-row comparison).

• paginate = TRUE automatically splits large panel collections into a list of patchwork pages, which prevents "viewport too small" rendering errors in IDE plot panes.

• For value_from = "assay", colours follow the VISTA ecosystem: group colours are used when summarise_replicates = TRUE, while sample colours are derived from group colours when plotting individual replicates.

• For value_from = "assay" with value_column = NULL, all selected assay columns are used (samples after sample_group filtering, or groups after replicate summarisation).

• Labels are kept consistent across value_columns: if genes is provided it is used for all panels; otherwise the top label_n (by absolute value in the first value_column) are used for all panels.

• When value_from = "assay", the specified assay column is copied into rowData on the fly so it can be used for colouring.

• When group_value is provided (and no value_column), colouring is based on log2 mean expression for that group (assay norm_counts), using a data-driven colour scale. Ignored when value_column is supplied.

Value

A ggplot2 object or a list of ggplot2 objects when multiple value_columns are provided and patchwork is unavailable.

Examples

v <- example_vista()
p <- try(get_expression_chromosome_plot(v), silent = TRUE)
if (!inherits(p, 'try-error')) print(p)

Description

Shows expression distributions pooled across the selected genes, coloured by group (or sample), with optional faceting by group or sample.

Usage

get_expression_density(
  x,
  genes = NULL,
  sample_group = NULL,
  group_column = NULL,
  log_transform = TRUE,
  facet_scales = "free",
  facet_nrow = NULL,
  facet_ncol = NULL,
  alpha = 0.4,
  adjust = 1,
  color_by = c("group", "sample"),
  facet_by = c("none", "group", "sample"),
  sample_order = c("input", "group", "expression"),
  palette = NULL,
  colors = NULL
)

Arguments

Value

A ggplot2 object.

Examples

v <- example_vista()
genes <- head(rownames(v), 3)
p <- get_expression_density(v, genes = genes)
print(p)

Description

Summarizes expression for selected genes/groups via ComplexHeatmap with optional transformations and annotations. With only a VISTA object, the function will plot the top variable genes across all samples.

Usage

get_expression_heatmap(
  x,
  genes = NULL,
  top_n = 50,
  sample_group = NULL,
  group_column = NULL,
  value_transform = c("zscore", "log2", "raw"),
  summarise_replicates = TRUE,
  summarise_method = c("mean", "median"),
  convert_rowmeans = FALSE,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  repair_genes = FALSE,
  show_row_names = NULL,
  label_size = 10,
  label_specific_rows = NULL,
  label_specific_rows_gp = grid::gpar(fontsize = 5),
  show_column_names = TRUE,
  cluster_rows = TRUE,
  show_row_dend = TRUE,
  cluster_columns = TRUE,
  kmeans_k = NULL,
  annotate_columns = FALSE,
  cluster_by = NULL,
  column_anno_palette = "Dark 3",
  column_anno_colors = NULL,
  color_default = TRUE,
  col = NULL,
  heatmap_name = NULL,
  show_heatmap_legend = TRUE,
  return_type = c("plot", "data", "both"),
  ...
)

Arguments

Value

A ComplexHeatmap::Heatmap object, a tibble of k-means cluster assignments, or a list of both, depending on return_type.

A ComplexHeatmap object, a cluster data frame, or a list containing both depending on return_type.

Examples

v <- example_vista()
genes <- head(rownames(v), 20)
if (requireNamespace('ComplexHeatmap', quietly = TRUE) &&
    requireNamespace('circlize', quietly = TRUE)) {
  hm <- get_expression_heatmap(
    v,
    genes = genes,
    sample_group = unique(as.character(sample_info(v)$cond_long)),
    return_type = 'heatmap'
  )
  ComplexHeatmap::draw(hm)
}
v <- example_vista()
if (requireNamespace("ComplexHeatmap", quietly = TRUE) &&
    requireNamespace("circlize", quietly = TRUE)) {
  hm <- get_expression_heatmap(v, return_type = "plot")
  ComplexHeatmap::draw(hm)
}

Description

Shows per-group (or per-sample) expression distributions pooled across the selected genes using ridge (joy) plots. Genes are pooled; no faceting to keep shapes comparable.

Usage

get_expression_joyplot(
  x,
  genes = NULL,
  sample_group = NULL,
  group_column = NULL,
  log_transform = TRUE,
  alpha = 0.7,
  scale = 1.2,
  y_by = c("group", "sample"),
  color_by = c("group", "sample"),
  sample_order = c("input", "group", "expression"),
  palette = NULL,
  colors = NULL
)

Arguments

Value

A ggplot2 object.

Examples

v <- example_vista()
genes <- head(rownames(v), 3)
p <- get_expression_joyplot(v, genes = genes)
print(p)

Description

Plots normalized expression for selected genes across samples or summarized groups with optional transformations and group faceting.

Usage

get_expression_lineplot(
  x,
  genes = NULL,
  sample_group = NULL,
  group_column = NULL,
  log_transform = TRUE,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  facet_scales = "free_y",
  facet_nrow = NULL,
  facet_ncol = NULL,
  stats_group = FALSE,
  p.label = "p.signif",
  stat_comparisons = NULL,
  pool_genes = FALSE,
  by = c("sample", "group"),
  facet_by = c("auto", "group", "gene", "none"),
  fill_by = NULL,
  sample_order = c("input", "group", "expression"),
  value_transform = NULL,
  palette = NULL,
  colors = NULL,
  line_width = 1,
  point_size = 2,
  base_size = 12,
  comparisons = NULL
)

Arguments

Value

A ggplot2 object connecting expression values across groups or samples.

Examples

v <- example_vista()
genes <- head(rownames(v), 3)
p <- get_expression_lineplot(v, genes = genes)
print(p)

Description

Displays selected genes as stem-and-dot (lollipop) plots. By default, expression is summarized per group (mean across replicates). With by = "sample", the plot shows individual samples.

Usage

get_expression_lollipop(
  x,
  genes,
  sample_group = NULL,
  group_column = NULL,
  by = c("group", "sample"),
  sample_order = c("input", "group", "expression"),
  facet_by = c("auto", "gene", "none"),
  log_transform = TRUE,
  facet_scale = "free_y",
  facet_nrow = NULL,
  facet_ncol = NULL,
  point_size = 6,
  linewidth = 1.2,
  label = TRUE,
  label_digits = 1,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  facet_scales = facet_scale,
  max_genes = 15,
  line_size = NULL
)

Arguments

Value

A ggplot2 object drawing expression as lollipops.

A ggplot2 object.

Examples

v <- example_vista()
genes <- head(rownames(v), 5)
p <- get_expression_lollipop(v, genes = genes)
print(p)
data("count_data", package = "VISTA")
data("sample_metadata", package = "VISTA")

vista <- create_vista(
  counts = count_data[seq_len(200), ],
  sample_info = sample_metadata[seq_len(6), ],
  column_geneid = "gene_id",
  group_column = "cond_long",
  group_numerator = "treatment1",
  group_denominator = "control"
)

genes <- rownames(vista)[seq_len(3)]
get_expression_lollipop(vista, genes = genes)
get_expression_lollipop(vista, genes = genes[seq_len(2)], by = "sample")

Description

Returns the specified assay (default "norm_counts") with optional gene/sample subsetting, replicate summarization by group, and simple transformations.

Usage

get_expression_matrix(
  x,
  assay_name = "norm_counts",
  genes = NULL,
  sample_names = NULL,
  group_column = NULL,
  summarise = FALSE,
  transform = c("none", "log2", "zscore")
)

Arguments

Value

A numeric matrix with genes in rows and samples (or groups) in columns.

Examples

v <- example_vista()
m <- get_expression_matrix(v)
dim(m)

Description

Uses ggrain::geom_rain() to combine a half-violin, boxplot, and jittered points per sample/group to show distribution, summary, and individual values.

Usage

get_expression_raincloud(
  x,
  genes = NULL,
  sample_group = NULL,
  group_column = NULL,
  by = "group",
  value_transform = c("log2", "zscore", "none"),
  summarise = FALSE,
  facet_by = c("auto", "gene", "none"),
  fill_by = NULL,
  facet_nrow = NULL,
  facet_ncol = NULL,
  sample_order = c("input", "group", "expression"),
  rain_side = c("r", "l", "f", "f1x1", "f2x2"),
  id.long.var = NULL,
  alpha = 0.5,
  point_size = 1.5,
  p.label = "p.signif",
  stats_group = FALSE,
  stats_method = "t.test",
  label = FALSE,
  label_column = "gene",
  label_size = 3,
  label_max_overlaps = 50,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL
)

Arguments

Details

id.long.var controls which repeated unit is connected by lines in ggrain::geom_rain().

Recommended usage for expression raincloud plots:

• id.long.var = NULL (default): best for clean distribution summaries.

• id.long.var = "gene": best when plotting a small number of genes and showing gene-level trajectories across x levels.

• id.long.var = "<subject_id_column>": best for paired/repeated-measure designs when a subject ID exists in sample_info.

• id.long.var = "sample" or the grouping variable is usually less informative and can over-connect points.

• Point labels (label = TRUE) work best with facet_by = "none" or a small number of genes.

For identifier display consistency with other VISTA plotting functions, set display_id (for example, "SYMBOL"). When provided, genes can be given in that ID space, and default point labels use the mapped display IDs.

Value

A ggplot2 object.

Examples

v <- example_vista()
genes <- head(rownames(v), 5)
p <- get_expression_raincloud(v, genes = genes, summarise = TRUE)
print(p)

Description

Plots gene-level expression for two selected samples or group means, colours points by local density (viridis), labels the most divergent genes, and reports Pearson/Spearman correlation.

Usage

get_expression_scatter(
  x,
  sample_x,
  sample_y,
  by = c("sample", "group"),
  group_column = NULL,
  genes = NULL,
  log_transform = TRUE,
  label_n = 20,
  label_size = 3,
  method = c("pearson", "spearman"),
  display_id = NULL
)

Arguments

Value

A ggplot2 object.

Examples

v <- example_vista()
si <- as.data.frame(sample_info(v))
genes <- head(rownames(v), 50)
p <- get_expression_scatter(
  v,
  sample_x = si$sample_names[1],
  sample_y = si$sample_names[2],
  genes = genes
)
print(p)

Description

Mirrors the main user-facing arguments of get_expression_boxplot() so the two geoms can be swapped with minimal code changes. Violin plots currently keep group-based semantics (by = "group") because a violin requires replicate-level distributions within groups rather than one value per sample.

Usage

get_expression_violinplot(
  x,
  genes = NULL,
  sample_group = NULL,
  group_column = NULL,
  log_transform = TRUE,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  facet_scales = "free_y",
  facet_nrow = NULL,
  facet_ncol = NULL,
  stats_group = FALSE,
  p.label = "p.signif",
  stat_comparisons = NULL,
  pool_genes = FALSE,
  by = "group",
  facet_by = c("auto", "gene", "none"),
  fill_by = NULL,
  sample_order = c("input", "group", "expression"),
  value_transform = NULL,
  summarise = FALSE,
  comparisons = NULL
)

Arguments

Value

A ggplot2 object.

Examples

v <- example_vista()
genes <- head(rownames(v), 4)
p <- get_expression_violinplot(v, genes = genes)
print(p)

Description

Plots log2 fold changes for selected genes across one or more comparisons. facet_by controls per-gene or per-comparison layout explicitly.

Usage

get_foldchange_barplot(
  x,
  genes,
  sample_comparisons = NULL,
  coord_flip = FALSE,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  sort_by = c("input", "log2fc", "abs_log2fc"),
  facet_scales = "free_y",
  facet_nrow = NULL,
  facet_ncol = NULL,
  facet_by = c("auto", "gene", "comparison", "none")
)

Arguments

Value

A ggplot2 object with one bar per gene showing log2 fold change.

A ggplot2 object.

Examples

v <- example_vista()
comp <- names(comparisons(v))[1]
genes <- head(as.character(comparisons(v)[[comp]]$gene_id), 10)
p <- get_foldchange_barplot(v, sample_comparison = comp, genes = genes)
print(p)
data("count_data", package = "VISTA")
data("sample_metadata", package = "VISTA")

vista <- create_vista(
  counts = count_data[seq_len(200), ],
  sample_info = sample_metadata[seq_len(6), ],
  column_geneid = "gene_id",
  group_column = "cond_long",
  group_numerator = "treatment1",
  group_denominator = "control"
)

genes <- rownames(vista)[seq_len(3)]
get_foldchange_barplot(vista, genes = genes)
get_foldchange_barplot(vista, genes = genes, facet_by = "gene")

Description

Builds boxplots of log2 fold changes for selected genes and comparisons, optionally adding statistics.

Usage

get_foldchange_boxplot(
  x,
  genes = NULL,
  sample_comparisons = NULL,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  facet_scales = "free_x",
  facet_nrow = NULL,
  facet_ncol = NULL,
  facet_by = c("auto", "comparison", "none"),
  p.label = "p.signif",
  stats_group = FALSE,
  stats_method = "t.test"
)

Arguments

Value

A ggplot2 object summarising log2 fold-change distributions.

Examples

v <- example_vista()
comp <- names(comparisons(v))[1]
genes <- head(as.character(comparisons(v)[[comp]]$gene_id), 10)
p <- get_foldchange_boxplot(v, sample_comparison = comp, genes = genes)
print(p)

Description

Convenience wrapper around get_chromosome_plot() for fold-change colouring. When multiple comparisons are supplied, panels are facetted by comparison with log2FC clipped to +/-2.

Usage

get_foldchange_chromosome_plot(
  x,
  txdb,
  keytype = "GENEID",
  id_column = NULL,
  genes = NULL,
  sample_comparison = NULL,
  value_column = NULL,
  label_n = 20,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  line_length = 0.02,
  line_width = 0.6,
  filter_chrom = NULL
)

Arguments

Value

A ggplot2 object.

Examples

v <- example_vista()
p <- try(get_foldchange_chromosome_plot(v, sample_comparison = names(comparisons(v))[1]), silent = TRUE)
if (!inherits(p, 'try-error')) print(p)

Description

Visualizes log2 fold-change matrices across comparisons with ComplexHeatmap, supporting clustering and annotations. With only a VISTA object, the function will plot the top DE genes across the stored comparisons.

Usage

get_foldchange_heatmap(
  x,
  sample_comparisons = NULL,
  genes = NULL,
  top_n = 10,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  repair_genes = FALSE,
  show_row_names = NULL,
  label_size = 10,
  label_specific_rows = NULL,
  label_specific_rows_gp = grid::gpar(fontsize = 5),
  show_column_names = TRUE,
  cluster_rows = TRUE,
  show_row_dend = TRUE,
  cluster_columns = TRUE,
  kmeans_k = NULL,
  annotate_columns = FALSE,
  column_anno_palette = "Set2",
  column_anno_colors = NULL,
  color_default = TRUE,
  col = NULL,
  heatmap_name = NULL,
  show_heatmap_legend = TRUE,
  return_type = c("plot", "data", "both"),
  ...
)