Skip to contents

Per-Element Statistical Summary Across One Variable

Source: R/09_element_summary.R
av_element_summary.Rd

Assembles, for one chosen variable (element), a single table with one row per element of that variable and every statistic the data can support for it: descriptive aggregation, Fisher one-vs-rest enrichment, Wilcoxon one-vs-rest distributional shift, and optionally Tau specificity. It is the generic form of the retired av_gene_impact_summary and the retired enrichment-shift table: any full-rank variable (biosample_name, output_type, gene_name, variant_id, ...) can be the element.

Usage

av_element_summary(
  obj,
  element,
  balance_by = NULL,
  per = "variant_id",
  specificity_across = NULL,
  tests = c("enrichment", "shift"),
  threshold = NULL,
  fdr_cutoff = 0.05,
  log2or_floor = 1,
  r_floor = 0.1,
  min_n = 5L,
  q_threshold = .AV_Q_DEFAULT
)

Arguments

obj

An AlphaVarSet object.

element

Character. The variable (metadata column) whose elements become the rows.

balance_by

Character or NULL. Passed to av_summarize and av_calc_shift to collapse track imbalance to one value per per unit before aggregation/testing. Must differ from element and per.

per

Character. The per unit for balance_by (default "variant_id"); ignored when balance_by is NULL.

specificity_across

Character or NULL. The variable to measure Tau concentration across (e.g. "output_type" when element = "biosample_name"). Required when "specificity" is in tests; must differ from element.

tests

Character vector, any of "enrichment", "shift", "specificity". Selects which stat blocks to compute. The descriptive block is always computed. Default c("enrichment", "shift").

threshold

Numeric or NULL. Absolute-score hit threshold for Fisher's test. NULL (default) inherits the score-aware default of av_calc_enrichment (0.95 for quantile_score, 0.5 with a warning for raw_score).

fdr_cutoff

Numeric. BH-adjusted p-value cutoff for the significance flags (default 0.05).

log2or_floor

Numeric. Effect-size floor for fisher_sig: an element is flagged only if abs(fisher_log2OR) >= log2or_floor. Default 1.0 (a two-fold odds change), the conventional minimum meaningful enrichment.

r_floor

Numeric. Effect-size floor for wilcox_sig: rank-biserial abs(wilcox_r) >= r_floor. Default 0.1, Cohen's "small" boundary.

min_n

Integer. Minimum n per arm for the shift test (default 5).

q_threshold

Numeric (0-1). Quantile threshold for n_sig_tracks and for n_active (default 0.95, top-5 percent rarity).

Value

A tibble, one row per element of element, sorted by max_abs_score descending. The first column is named after element. Blocks (present per tests):

descriptive (always)

max_abs_score, mean_score, median_score, n_tracks, n_variants, n_tissues, n_sig_tracks, direction_sign, direction_consistency.

enrichment

fisher_n_hits, fisher_log2OR, fisher_or, fisher_p_raw, fisher_q, fisher_sig.

shift

wilcox_median_diff, wilcox_r, wilcox_q, wilcox_sig.

specificity

spec_tau, spec_n_active, spec_top_element.

The descriptive block is the join spine, so elements dropped by a test (NA score, or n < min_n) keep their row with NA in that block.

Details

Read-only: each block is harvested from the relevant av_calc_* / av_summarize call (via return_only or a discarded temporary copy) and the caller's obj$stats is never written.

Magnitude (the descriptive block) and "stands out vs the rest" (the enrichment/shift blocks) are orthogonal: a high max_abs_score does not imply significance. The *_sig flags are effect-size gated, not p-value alone, because at thousands of tracks every q-value collapses toward zero. spec_top_element only hints where an element's signal concentrates; it is not a tested conditional contrast (use av_compare_groups for that).

The Fisher block (fisher_*) is always track-level; only the Wilcoxon block (wilcox_*) honours balance_by. When balance_by is set the two q-columns rest on different sample bases, so compare across blocks via the effect-size columns (fisher_log2OR, wilcox_r), not the q-values.

Examples

example_file <- system.file("extdata", "bcl11a_rs1427407_example.csv",
                            package = "AlphaVaR")
obj <- av_import_csv(example_file)
#> Reading bcl11a_rs1427407_example.csv ...
av_element_summary(obj, element = "output_type",
                     tests = c("enrichment", "shift"))
#> Warning: 1 element(s) dropped (n < 5 in one arm): SPLICE_SITES
#> # A tibble: 11 × 20
#>    output_type       max_abs_score mean_score median_score n_tracks n_variants
#>    <chr>                     <dbl>      <dbl>        <dbl>    <int>      <int>
#>  1 DNASE                     0.997      0.299        0.406      320          2
#>  2 CAGE                      0.995      0.347        0.541      320          2
#>  3 CHIP_HISTONE              0.994      0.369        0.578      320          2
#>  4 ATAC                      0.994      0.701        0.814      320          2
#>  5 CHIP_TF                   0.970      0.385        0.431      328          2
#>  6 SPLICE_SITE_USAGE         0.954      0.393        0.336      320          2
#>  7 RNA_SEQ                   0.948      0.222        0.206      320          2
#>  8 PROCAP                    0.926      0.345        0.436       48          2
#>  9 CONTACT_MAPS              0.924      0.518        0.535       56          2
#> 10 SPLICE_JUNCTIONS          0.852      0.302        0.277      320          2
#> 11 SPLICE_SITES              0.569      0.374        0.436        4          2
#> # ℹ 14 more variables: n_tissues <int>, n_sig_tracks <int>,
#> #   direction_sign <int>, direction_consistency <dbl>, fisher_n_hits <int>,
#> #   fisher_log2OR <dbl>, fisher_or <dbl>, fisher_p_raw <dbl>, fisher_q <dbl>,
#> #   fisher_sig <lgl>, wilcox_median_diff <dbl>, wilcox_r <dbl>, wilcox_q <dbl>,
#> #   wilcox_sig <lgl>