Skip to contents

Summarize an AlphaVarSet by Arbitrary Grouping

Source: R/06_summarize.R
av_summarize.Rd

Generic aggregation engine that computes a battery of summary statistics per group. Supports optional two-step weighted aggregation via balance_by to correct for track-imbalance (e.g., CHIP_HISTONE having 15× more tracks than CAGE).

Usage

av_summarize(
  obj,
  group_by,
  balance_by = NULL,
  lead_by = NULL,
  q_threshold = .AV_Q_DEFAULT
)

Arguments

obj

An object of class AlphaVarSet.

group_by

Character. Column name to group by (e.g. "variant_id", "output_type").

balance_by

Character or NULL. If provided, a two-step aggregation is performed: first within c(group_by, balance_by), then across group_by. This equalizes the weight of sparse vs. dense categories for mean_score and median_score. Metrics that must reflect the absolute raw data (max_abs_score, n_sig_tracks, lead_category) bypass this smoothing.

lead_by

Character or NULL. If provided, identifies the category (from this column) that produced the single track with the highest absolute score. Returned as lead_category (character).

q_threshold

Numeric (0-1). Quantile score threshold for counting significant tracks (n_sig_tracks). Default 0.95 (top-5 percent rarity). Applied to the quantile_score column.

Value

The updated AlphaVarSet object with results stored in obj$stats$summary[[group_by]] as a tibble.

Details

Computed metrics (Compute-All Policy):

max_abs_score

Maximum absolute value of the active score.

mean_score

Average of the active score (balanced if balance_by).

median_score

Median of the active score (balanced if balance_by).

n_tracks

Total number of rows (tracks) in the group.

n_variants

Number of distinct variant_id values in the group. For non-variant groupings (e.g., gene_name) this is the count of unique variants annotated to that group.

n_tissues

Number of unique tissues (biosample_name), or NA if column is absent.

n_sig_tracks

Count of tracks with abs(quantile_score) >= q_threshold. Always unbalanced (raw count).

direction_sign

Dominant sign of raw_score: +1L if positive scores outnumber negative, -1L if negative outnumber positive, NA_integer_ on tie or when no signed values exist. Also NA if raw_score is absent.

direction_consistency

Proportion of tracks sharing the dominant sign (0.5–1.0), or NA if raw_score is absent.

lead_category

(If lead_by provided) The category that produced the max absolute score track. Character.

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_summarize(obj, group_by = "variant_id", balance_by = "output_type")
obj$stats$summary[["variant_id"]]
#> # A tibble: 2 × 10
#>   variant_id        max_abs_score n_tracks n_variants n_tissues n_sig_tracks
#>   <chr>                     <dbl>    <int>      <int>     <int>        <int>
#> 1 chr2:60490908:T>C         0.997     1338          1       496           93
#> 2 chr2:60490908:T>G         0.990     1338          1       511           13
#> # ℹ 4 more variables: direction_sign <int>, direction_consistency <dbl>,
#> #   mean_score <dbl>, median_score <dbl>