Skip to contents

Prioritize Variants by Transparent Multi-Criteria Ranking

Source: R/08_evidence.R
av_prioritize.Rd

Ranks variants without collapsing incommensurable signals into a single synthetic score. Each variant is placed on several independently defensible axes (strength, specificity, evidence breadth), then summarized two ways: a Pareto non-dominated flag (weight-free) and a mean percentile rank (transparent equal weighting). Priority is not an intrinsic property of the data; it depends on the chosen criteria, which are made explicit here rather than hidden inside a learned model or a multiplicative constant.

Usage

av_prioritize(
  obj,
  criteria = c("strength", "specificity", "breadth"),
  specificity_across = "biosample_name",
  balance_by = "output_type",
  write = TRUE
)

Arguments

obj

An object of class AlphaVarSet.

criteria

Character vector, any of "strength", "specificity", "breadth", "direction". Selects the axes entering priority_rank and the Pareto front. Default excludes "direction", which is NA when raw_score is absent and spans only 0.5-1.0.

specificity_across

Character. Variable Tau is measured across when "specificity" is requested (default "biosample_name").

balance_by

Character or NULL. Passed to av_element_summary to collapse track imbalance before aggregation (default "output_type").

write

Logical. If TRUE (default) the ranked table is stored in obj$stats$prioritization[["variant_id"]] and the updated AlphaVarSet is returned. If FALSE the ranked tibble is returned directly (a detached view).

Value

With write = TRUE, the updated AlphaVarSet; the table at obj$stats$prioritization[["variant_id"]] carries variant_id, the selected raw criteria, one pct_rank_* per criterion, priority_rank (mean percentile across criteria, 0-1, sorted descending), and is_pareto (logical, non-dominated on the selected criteria). With write = FALSE, that tibble is returned directly.

Details

Criteria are harvested from av_element_summary with element = "variant_id", so no statistic is recomputed by hand: strength = max_abs_score, breadth = n_sig_tracks, specificity = spec_tau (Tau across specificity_across), direction = direction_consistency. All are oriented so higher is better.

priority_rank averages per-criterion percentile ranks with na.rm = TRUE, so a variant missing Tau is still ranked on the criteria it has. The Pareto flag imputes a missing criterion to that criterion's minimum (worst case) so an absent signal cannot make a variant appear non-dominated.

See also

av_element_summary

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_prioritize(obj)
#> Warning: av_calc_specificity: dropped 4/2676 rows with NA in quantile_score, biosample_name, or variant_id.
obj$stats$prioritization[["variant_id"]]
#> # A tibble: 2 × 9
#>   variant_id        max_abs_score spec_tau n_sig_tracks pct_rank_strength
#>   <chr>                     <dbl>    <dbl>        <int>             <dbl>
#> 1 chr2:60490908:T>C         0.997    0.277           93                 1
#> 2 chr2:60490908:T>G         0.990    0.364           13                 0
#> # ℹ 4 more variables: pct_rank_specificity <dbl>, pct_rank_breadth <dbl>,
#> #   priority_rank <dbl>, is_pareto <lgl>