Get Intersection of Top Elements Across N Groups

Identifies the global intersection (items present in the top N of ALL groups) and unique elements per group.

Usage

av_get_intersection(
  obj,
  group_by,
  compare_by,
  n = 50,
  abs_score = TRUE,
  aggregation_method = c("max", "median", "mean"),
  balance_by = "output_type"
)

Arguments

obj

An AlphaVarSet object.

group_by

Column name defining the groups (e.g., "tissue"). Supports 2 or more groups.

compare_by

Column name for the items to compare (e.g., "gene_name").

n

Number of top items to consider per group (default 50).

abs_score

Logical. If TRUE (default), rank by absolute score.

aggregation_method

Character. How to aggregate scores per item within each group before ranking. One of "max" (default, single highest impact), "median" (robust central tendency), or "mean" (average impact).

balance_by

Column name whose elements are equalized before computing "mean" or "median", correcting modality-track imbalance (e.g. CHIP_HISTONE contributing far more tracks than CAGE) via a two-step weighted mean. Default "output_type". Ignored for aggregation_method = "max" (a single-track statistic) and auto-skipped when the column is absent or equals group_by / compare_by. Set NULL to disable.

Value

A named list with:

shared

Character vector. Items in the top N of ALL groups (global intersection).

unique_per_group

Named list. Items unique to each group's top N.

top_per_group

Named list. Full top N list for each group.

groups

Character vector. The group names (sorted).

For backwards compatibility with 2 groups, also includes unique_A, unique_B, top_A, top_B.

Details

"max" reports the single strongest track per item and is never balanced; smoothing would attenuate the peak. "mean" and "median" report the typical signal, where modality imbalance must be corrected, so balance_by applies the same two-step weighted mean used by av_summarize.

Examples

example_file <- system.file("extdata", "bcl11a_rs1427407_example.csv",
                            package = "AlphaVaR")
obj <- av_import_csv(example_file)
#> Reading bcl11a_rs1427407_example.csv ...

# Which biosamples respond to both alternate alleles at this position?
top_shared <- av_get_intersection(obj, group_by = "variant_id",
                                  compare_by = "biosample_name", n = 20)
top_shared$groups
#> [1] "chr2:60490908:T>C" "chr2:60490908:T>G"
top_shared$shared
#> [1] eosinophil
#> 620 Levels: A172 A375 A549 A673 ACC112 AG04449 AG04450 AG08396 ... zone of skin
lengths(top_shared$unique_per_group)
#> chr2:60490908:T>C chr2:60490908:T>G 
#>                19                19 

balanced <- av_get_intersection(obj, group_by = "variant_id",
                                compare_by = "biosample_name", n = 50,
                                aggregation_method = "mean",
                                balance_by = "output_type")
balanced$shared
#> [1] GM21367                               GM21786                              
#> [3] GM19463                               blood                                
#> [5] GM18517                               CD14-positive, CD16-positive monocyte
#> [7] gallbladder                           non-pigmented ciliary epithelial cell
#> 620 Levels: A172 A375 A549 A673 ACC112 AG04449 AG04450 AG08396 ... zone of skin