Package 'VISTA'

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",
  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 direct DESeq2, edgeR, and limma pipelines with matched preprocessing, contrast definitions, and DEG thresholds, then compare the resulting tables, DEG calls, normalized matrices, 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
)

Arguments

Value

A list with fields valid, comparison_summary, visual_summary, and methods. Each element of methods contains the VISTA object, direct backend 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

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",
  validate = TRUE
)

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.

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"),
  error = c("se", "sd", "none"),
  add_points = TRUE,
  point_size = 2.5,
  base_size = 12
)

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", "matrix", "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"),
  cluster_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
)

Arguments

Value

An object returned by this function.

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

An object returned by this function.

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

Arguments

Value

An object returned by this function.

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

Arguments

Value

An object returned by this function.

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

An object returned by this function.

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
)

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

Invisibly returns 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",
  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")
)

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",
  comparisons = NULL,
  pool_genes = FALSE,
  by = "group",
  facet_by = "auto",
  fill_by = NULL,
  sample_order = c("input", "group", "expression")
)

Arguments

Value

An object returned by this function.

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("heatmap", "clusters", "both"),
  ...
)

Arguments

Value

An object returned by this function.

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 = "heatmap")
  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",
  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
)

Arguments

Value

An object returned by this function.

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,
  line_size = 1.2,
  label = TRUE,
  label_digits = 1,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL
)

Arguments

Value

An object returned by this function.

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

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

An object returned by this function.

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

An object returned by this function.

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",
  color_default = TRUE,
  col = NULL,
  heatmap_name = NULL,
  show_heatmap_legend = TRUE,
  return_type = c("heatmap", "clusters", "both"),
  ...
)

Arguments

Value

An object returned by this function.

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

Examples

v <- example_vista()
comp <- names(comparisons(v))[1]
genes <- unique(stats::na.omit(as.character(comparisons(v)[[comp]]$gene_id)))[seq_len(20)]
if (requireNamespace('ComplexHeatmap', quietly = TRUE) &&
    requireNamespace('circlize', quietly = TRUE)) {
  hm <- get_foldchange_heatmap(
    v,
    sample_comparisons = comp,
    genes = genes,
    return_type = 'heatmap'
  )
  ComplexHeatmap::draw(hm)
}
v <- example_vista()
if (requireNamespace("ComplexHeatmap", quietly = TRUE) &&
    requireNamespace("circlize", quietly = TRUE)) {
  hm <- get_foldchange_heatmap(v, return_type = "heatmap")
  ComplexHeatmap::draw(hm)
}

Description

Plots log2 fold-change trajectories for selected genes across multiple comparisons, optionally clustering genes.

Usage

get_foldchange_lineplot(
  x,
  sample_comparisons,
  genes = NULL,
  display_id = NULL,
  display_from = NULL,
  display_orgdb = NULL,
  km = NULL,
  facet_by = c("none", "cluster"),
  facet_scales = "fixed",
  facet_nrow = NULL,
  facet_ncol = NULL,
  alpha = 0.5,
  palette = NULL,
  show_summary = TRUE,
  summary_color = NULL,
  summary_linewidth = 1,
  summary_fun = c("median", "mean"),
  base_size = 14
)

Arguments