For a chosen unit (per), quantifies how concentrated the
regulatory effect is across the elements of a chosen variable (across),
using the Tau specificity index (Yanai et al. 2005) and, optionally, a count
of active elements. The same question ("is the effect concentrated or
dispersed?") applies to any unit/variable pair: tissue specificity per
variant (per = "variant_id", across = "biosample_name"), tissue
specificity per modality (per = "output_type", across =
"biosample_name", useful when cross-modality pooling dilutes the signal),
modality specificity per variant, and so on.
Usage
av_calc_specificity(
obj,
across = "biosample_name",
per = "variant_id",
metric = c("tau", "n_active", "both"),
q_threshold = .AV_Q_DEFAULT
)Arguments
- obj
An object of class
AlphaVarSet.- across
Name of the variable to measure specificity across. Default
"biosample_name"(tissue specificity). Any column inobj$datais accepted.- per
Name of the unit column. Default
"variant_id"(specificity per variant). Other defensible choices include"output_type"(specificity per modality, e.g. tissue Tau within ATAC vs.\ within CHIP_HISTONE) and"scored_interval"(specificity per locus, for ISM-style scans). Must be different fromacross.- metric
One of
"tau"(default),"n_active", or"both". Selects which statistic(s) appear in the result table.- q_threshold
Numeric between 0 and 1. Magnitude an element must reach to count toward
n_active. Default0.95matches the top-5 percent rarity tail ofquantile_scoreused elsewhere in the package.
Value
The updated AlphaVarSet.
obj$stats$specificity[[across]] holds one row per element of
per, with the first column literally named after per and
columns specificity (Tau; present unless
metric = "n_active"), n_active (present unless
metric = "tau"), n_elements (distinct across elements
contributing), and top_element (highest-scoring across
element).
Details
Specificity is a descriptive (Type-B) question: for a given unit, is
its effect concentrated on a few elements of across or spread evenly?
Both per (unit) and across (target variable) are
first-class parameters. Ranking units against each other is a separate
operation handled by av_prioritize.
For each (per, across) pair the per-element magnitude is the maximum
absolute active score (non-negative by construction). Two statistics
summarize the resulting per-unit profile across elements:
- Tau (
metric = "tau") Yanai's specificity index in
[0, 1]: 0 = uniform across elements (broad), 1 = concentrated in a single element (element-specific).NAfor units with fewer than two elements or an all-zero profile.- n_active (
metric = "n_active") Count of elements whose magnitude reaches
q_threshold. Meaningful onquantile_score(a comparable rarity rank across modalities); onraw_scorethe threshold is ill-defined and a warning is emitted.
Results are written to obj$stats$specificity[[across]], one row per
unit, with the first column literally named after per.
Units for which only one across-element is present collapse to a
single element and yield NA by construction. Partial-rank variables
(transcription_factor, histone_mark, gene_name) are
populated only within their parent output_type, so call
av_subset first to avoid specificity computed over a biased,
mostly-NA subset.
Rows with NA in the active score, in across, or in per
are dropped before grouping; an rlang::warn() reports the row delta.
On raw_score a further warning notes that the per-element maximum mixes
modalities on incomparable magnitude scales; quantile_score is the
intended domain.
References
Yanai, I. et al. (2005). Genome-wide midrange transcription profiles reveal expression element relationships in human tissue specification. Bioinformatics 21(5), 650-659.
Examples
example_file <- system.file("extdata", "bcl11a_rs1427407_example.csv",
package = "AlphaVaR")
obj <- av_import_csv(example_file)
#> Reading bcl11a_rs1427407_example.csv ...
# Default: tissue specificity per variant
obj <- av_calc_specificity(obj)
#> Warning: av_calc_specificity: dropped 4/2676 rows with NA in quantile_score, biosample_name, or variant_id.
obj$stats$specificity[["biosample_name"]]
#> # A tibble: 2 × 4
#> variant_id specificity n_elements top_element
#> <chr> <dbl> <int> <chr>
#> 1 chr2:60490908:T>C 0.277 496 hematopoietic multipotent progenitor…
#> 2 chr2:60490908:T>G 0.364 511 SU-DHL-6
# Modality specificity per variant
obj <- av_calc_specificity(obj, across = "output_type", metric = "both")
obj$stats$specificity[["output_type"]]
#> # A tibble: 2 × 5
#> variant_id specificity n_active n_elements top_element
#> <chr> <dbl> <int> <int> <chr>
#> 1 chr2:60490908:T>C 0.0891 6 11 DNASE
#> 2 chr2:60490908:T>G 0.182 3 11 CHIP_HISTONE
# Tissue specificity per modality: exposes modality-specific tissue
# concentration that the per-variant pooled Tau may dilute
obj <- av_calc_specificity(obj, across = "biosample_name",
per = "output_type")
#> Warning: av_calc_specificity: dropped 4/2676 rows with NA in quantile_score, biosample_name, or output_type.
obj$stats$specificity[["biosample_name"]]
#> # A tibble: 10 × 4
#> output_type specificity n_elements top_element
#> <fct> <dbl> <int> <chr>
#> 1 ATAC 0.152 157 memory B cell
#> 2 CAGE 0.296 203 plasmacytoid dendritic cell
#> 3 CHIP_HISTONE 0.299 155 CD14-positive monocyte
#> 4 CHIP_TF 0.343 49 K562
#> 5 CONTACT_MAPS 0.311 12 GM12878
#> 6 DNASE 0.432 215 hematopoietic multipotent progenito…
#> 7 PROCAP 0.188 6 K562
#> 8 RNA_SEQ 0.525 180 testis
#> 9 SPLICE_JUNCTIONS 0.569 181 mononuclear cell
#> 10 SPLICE_SITE_USAGE 0.519 209 stomach