Calculate Fisher Enrichment Statistics — av_calc

Performs Fisher's Exact Test on per-group hit rates against the rest of the dataset. A "hit" is a variant whose absolute active score meets or exceeds threshold. Uses the active score column set via av_set_active_score(). Results are stored at obj$stats$comparisons[["enrichment"]].

Usage

av_calc_enrichment(
  obj,
  group_by = "output_type",
  threshold,
  return_only = FALSE,
  key = "enrichment"
)

Arguments

obj: An object of class AlphaVarSet.
group_by: The column to group by (default "output_type").
threshold: Score threshold for a hit (abs(score) >= threshold). If omitted, a score-aware default applies: 0.95 for quantile_score (top-5 percent rarity, the package-wide convention), or 0.5 with a warning for raw_score and other unbounded scores, where no fixed default is defensible. An explicit value is always honored.
return_only: Logical. If TRUE, returns the fisher_tidy tibble directly without mutating obj$stats. Use this when an integration function needs enrichment results as input without polluting the caller's stored stats (default FALSE).
key: Name of the slot in obj$stats$comparisons the result is written to (default "enrichment"). One object holds one Fisher result per key, so an enrichment over a second column (e.g. group_by = "biosample_name") needs its own key to coexist with the default one instead of overwriting it. Plot and table functions address the slot through the same argument.

Value

If return_only = FALSE (default), the updated AlphaVarSet object with results stored in obj$stats$comparisons[[key]] as a list containing:

method: Character. "Fisher Exact (BH)".
global_p: NA_real_ (not applicable for per-group Fisher tests).
fisher_tidy: A tibble with columns group, n_obs, n_hits, or, log2OR, p_raw, p_adj, neg_log10_fdr.
params: List with threshold, group_by, score_col.

If return_only = TRUE, returns the fisher_tidy tibble alone.

Details

Distribution-based group comparisons (Wilcoxon, Kruskal-Wallis) live in av_compare_groups.

Examples

example_file <- system.file("extdata", "bcl11a_rs1427407_example.csv", package = "AlphaVaR")
obj <- av_import_csv(example_file)
#> Reading bcl11a_rs1427407_example.csv ...
obj <- av_calc_enrichment(obj, group_by = "output_type", threshold = 0.5)
obj$stats$comparisons[["enrichment"]]$fisher_tidy
#> # A tibble: 11 × 8
#>    group             n_obs n_hits    or  log2OR    p_raw    p_adj neg_log10_fdr
#>    <fct>             <int>  <int> <dbl>   <dbl>    <dbl>    <dbl>         <dbl>
#>  1 SPLICE_JUNCTIONS    320     44 0.134 -2.90   3.03e-46 3.33e-45        44.5  
#>  2 ATAC                320    254 4.61   2.21   2.14e-31 1.18e-30        29.9  
#>  3 SPLICE_SITE_USAGE   320     86 0.331 -1.59   1.87e-18 6.87e-18        17.2  
#>  4 CHIP_HISTONE        320    230 2.94   1.56   8.64e-18 2.38e-17        16.6  
#>  5 RNA_SEQ             320     91 0.361 -1.47   3.93e-16 8.64e-16        15.1  
#>  6 CAGE                320    226 2.75   1.46   5.86e-16 1.07e-15        15.0  
#>  7 DNASE               320    174 1.25   0.319  6.50e- 2 1.02e- 1         0.991
#>  8 CONTACT_MAPS         56     34 1.59   0.670  1.05e- 1 1.44e- 1         0.841
#>  9 PROCAP               48     26 1.21   0.274  5.62e- 1 6.87e- 1         0.163
#> 10 CHIP_TF             328    158 0.941 -0.0884 6.37e- 1 7.01e- 1         0.154
#> 11 SPLICE_SITES          4      2 1.02   0.0281 1   e+ 0 1   e+ 0         0    

# A second enrichment over another column needs its own key.
obj <- av_calc_enrichment(obj, group_by = "biosample_name", threshold = 0.5,
                          key = "enrichment_by_biosample")
#> Warning: Dropped 4 of 2676 rows with NA in 'biosample_name' or 'quantile_score'.
names(obj$stats$comparisons)
#> [1] "enrichment"              "enrichment_by_biosample"