Skip to contents

Create a VISTA Object with Internal DE Analysis

Source: R/rnaseq_related.R
create_vista.Rd

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
)

Arguments

counts

Raw counts (matrix/data.frame) with a gene-id column and sample columns.

sample_info

Data frame with sample metadata. Must contain sample_names (or have rownames equal to sample columns in counts) and the group_column.

column_geneid

Column name in counts that contains gene identifiers.

group_column

Column in sample_info used to group samples.

group_numerator

Character vector of numerator groups for pairwise comparisons.

group_denominator

Character vector of denominator groups (same length/order as numerator).

method

"deseq2", "edger", "limma", or "both".

min_counts

Minimum per-sample count a gene must reach to count as detected in that sample; also applied as a minimum row total in an initial pre-filter (default: 10).

min_replicates

Minimum number of samples in which a gene must reach min_counts to enter the model. Counted across the whole experiment, not within each group (default: 1).

log2fc_cutoff

Absolute LFC threshold for DEG calling (default: 1).

pval_cutoff

p-value (raw or adjusted) threshold (default: 0.05).

p_value_type

Which p-value column to use ("padj" or "pvalue"). Default: "padj".

covariates

Optional character vector of additional sample_info columns to adjust for. These are included as additive terms in the DE design.

design_formula

Optional model formula (or formula string) overriding automatic construction from group_column + covariates. Must include group_column.

consensus_mode

When method = "both", how to define consensus calls: "intersection" (both methods significant in same direction) or "union" (either method significant; discordant directions excluded).

consensus_log2fc

When method = "both", how to populate consensus log2fc: "mean", "deseq2", or "edger".

result_source

Active DE source used in metadata(v)$de_results. For method = "both", one of "consensus", "deseq2", "edger". For single-method runs, this must match method.

group_palette

Qualitative palette name for colorspace::qualitative_hcl(). One of c("Pastel 1","Dark 2","Dark 3","Set 2","Set 3","Warm","Cold","Harmonic","Dynamic"). Default: "Dark 2".

comparison_palette

Qualitative palette name used to assign colors per comparison (stored in metadata(v)$comparison$colors). Defaults to "Dark 3".

keep_raw_counts

Logical; if TRUE (default), the filtered raw count matrix is retained as a second assay named "counts", reachable with counts(v) and required by as_deseq_dataset(). This roughly doubles the assay footprint; set FALSE to omit it.

validate

Logical; if TRUE (default), run full validate_vista() checks before returning the object.

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

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 (with single-backend calls taking the contributing backend's estimate), while pvalue and padj carry the less-significant of the two backends so the columns remain continuous and usable for volcano/MA plots and ranking. 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").

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
)
#> estimating size factors
#> estimating dispersions
#> gene-wise dispersion estimates
#> mean-dispersion relationship
#> final dispersion estimates
#> fitting model and testing

# Examine the VISTA object
vista
#> class: VISTA 
#> dim: 85 6 
#> metadata(12): de_results de_summary ... design comparison
#> assays(2): norm_counts counts
#> rownames(85): ENSG00000000003 ENSG00000000419 ... ENSG00000005469
#>   ENSG00000005471
#> rowData names(1): baseMean
#> colnames(6): SRR1039508 SRR1039509 ... SRR1039516 SRR1039517
#> colData names(14): SampleName cell ... sizeFactor sample_names
#> -------- VISTA --------
#> group column: cond_long (control, treatment1)
#> comparisons: treatment1_VS_control
#> DE source: deseq2
#> cutoffs: |log2FC| >= 0.6, padj <= 0.05
#> raw counts: available via counts()
#> schema: 1.1.0

# Access comparisons
names(comparisons(vista))
#> [1] "treatment1_VS_control"

# View DEG summary
deg_summary(vista)
#> $treatment1_VS_control
#>   regulation  n
#> 1       Down  1
#> 2      Other 82
#> 3         Up  2
#> 

# View cutoffs used
cutoffs(vista)
#> $log2fc
#> [1] 0.6
#> 
#> $pval
#> [1] 0.05
#> 
#> $p_value_type
#> [1] "padj"
#> 
#> $method
#> [1] "deseq2"
#> 
#> $min_counts
#> [1] 10
#> 
#> $min_replicates
#> [1] 1
#> 
#> $covariates
#> character(0)
#> 
#> $design_formula
#> NULL
#> 
#> $consensus_mode
#> NULL
#> 
#> $consensus_log2fc
#> NULL
#> 
#> $active_source
#> [1] "deseq2"
#> 

# Multiple comparisons example
# \donttest{
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
)
#> calcNormFactors has been renamed to normLibSizes
# }