Skip to contents

Get Top Entries or Genes

Source: R/10_dataops.R
av_get_top.Rd

A smart ranking function that returns the top entries by score, optionally grouped by gene or other columns.

Usage

av_get_top(
  obj,
  n = 10,
  by = NULL,
  group_by = NULL,
  method = c("max", "mean", "count_hits"),
  threshold = 0.5
)

Arguments

obj

An AlphaVarSet object.

n

Integer, number of top entries/groups to return (default 10).

by

Column name to rank by. Defaults to the active score column from get_sc(obj). Uses absolute values.

group_by

Optional column name to aggregate by before ranking. If provided, returns the object filtered to entries belonging to the top n groups (ranked by method via av_summarize). If NULL, returns the top n individual entries.

method

Aggregation method when group_by is specified. One of "max", "mean", "count_hits" (default "max"). Resolved against av_summarize columns: max → max_abs_score, mean → mean_score (balanced across output_type if present), count_hits → n_sig_tracks.

threshold

Quantile-score threshold (0-1) for the "count_hits" method. Default 0.5 (permissive: any track above median rarity counts as a hit). Only meaningful when the active score is a quantile-style score in the 0-1 range; for raw_score the absolute scale makes this threshold uninterpretable. Passed to av_summarize(q_threshold = ...).

Value

  • If group_by = NULL: An AlphaVarSet object filtered to the top n entries by score.

  • If group_by is set: An AlphaVarSet object filtered to entries belonging to the top n groups in that column.

Details

This function supports the dynamic exploration workflow by allowing users to quickly focus on the most interesting entries or genes.

When group_by is set, ranking is delegated to av_summarize with balance_by = "output_type" (when present and not itself the grouping column) to correct for modality-track imbalance. The data is then filtered to the variants belonging to the top n groups.

Examples

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

top_tracks <- av_get_top(obj, n = 20)
top_tracks$data[, c("output_type", "biosample_name", obj$meta$active_score)]
#> # A tibble: 20 × 3
#>    output_type  biosample_name                                    quantile_score
#>    <fct>        <fct>                                                      <dbl>
#>  1 DNASE        hematopoietic multipotent progenitor cell                  0.997
#>  2 CAGE         plasmacytoid dendritic cell                                0.995
#>  3 CAGE         myelocyte                                                  0.994
#>  4 CHIP_HISTONE CD14-positive monocyte                                     0.994
#>  5 ATAC         memory B cell                                              0.994
#>  6 CAGE         eosinophil                                                 0.993
#>  7 ATAC         B cell                                                     0.993
#>  8 DNASE        suppressor macrophage                                      0.992
#>  9 ATAC         naive thymus-derived CD4-positive, alpha-beta T …          0.992
#> 10 ATAC         lower lobe of left lung                                    0.992
#> 11 DNASE        inflammatory macrophage                                    0.991
#> 12 DNASE        NB4                                                        0.990
#> 13 CHIP_HISTONE SU-DHL-6                                                   0.990
#> 14 ATAC         GM18505                                                    0.988
#> 15 ATAC         GM18868                                                    0.986
#> 16 CAGE         immature conventional dendritic cell                       0.986
#> 17 ATAC         upper lobe of right lung                                   0.986
#> 18 ATAC         GM19395                                                    0.985
#> 19 CAGE         Langerhans cell                                            0.985
#> 20 ATAC         GM21423                                                    0.984

top_modalities <- av_get_top(obj, n = 3, group_by = "output_type", method = "max")
unique(top_modalities$data$output_type)
#> [1] CAGE         CHIP_HISTONE DNASE       
#> 11 Levels: ATAC CAGE CHIP_HISTONE CHIP_TF CONTACT_MAPS DNASE PROCAP ... SPLICE_SITE_USAGE

# Ranking by hit count picks different modalities than the single peak track.
most_hits <- av_get_top(obj, n = 3, group_by = "output_type",
                        method = "count_hits", threshold = 0.9)
unique(most_hits$data$output_type)
#> [1] ATAC         CAGE         CHIP_HISTONE
#> 11 Levels: ATAC CAGE CHIP_HISTONE CHIP_TF CONTACT_MAPS DNASE PROCAP ... SPLICE_SITE_USAGE