Skip to contents

Tag filtered variants as a named cohort

Source: R/10_dataops.R
av_tag_cohort.Rd

Assigns a cohort label to rows of an AlphaVarSet object based on a filtered subset. The label is written to a new categorical column (custom_cohort by default) which can then be used in av_compare_groups() for differential analysis.

Usage

av_tag_cohort(
  obj,
  filtered_obj,
  cohort_name,
  col_name = "custom_cohort",
  bg_label = "Unassigned",
  scope = c("rows", "variants")
)

Arguments

obj

An AlphaVarSet. The full (unfiltered) base dataset.

filtered_obj

An AlphaVarSet. A filtered subset of obj, typically produced by av_subset() or av_get_top().

cohort_name

Character. Name for the cohort (e.g., "Brain_ATAC"). Will be trimmed of whitespace. Must be non-empty.

col_name

Character. Name of the cohort column. Default "custom_cohort".

bg_label

Character. Label for untagged rows. Default "Unassigned".

scope

Character. One of "rows" or "variants".

Value

An updated AlphaVarSet with the cohort column added/updated. The number of overwritten rows (rows that already had a non-background label) is stored as attr(result, "cohort_overwrite_count"). Only obj$stats$comparisons is cleared, since the new column only affects group-comparison results. Score-based stats (pleiotropy, evidence, summary) survive and remain valid.

Details

In long-format data (one row per variant-modality combination), two scoping modes are available:

  • "rows": Only the exact rows present in filtered_obj are tagged (matched via composite key: variant_id + modality + any shared character/factor columns).

  • "variants": All rows whose variant_id appears in filtered_obj$data are tagged, including modalities not present in the filtered subset.

Examples

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

ctcf <- av_subset(obj, output_type == "CHIP_TF", transcription_factor == "CTCF",
                  .description = "CTCF ChIP tracks")

# scope = "rows" tags only the CTCF tracks; scope = "variants" would tag every
# track of the two alleles, which here is the whole dataset.
obj <- av_tag_cohort(obj, ctcf, "CTCF_sites", scope = "rows")
table(obj$data$custom_cohort)
#> 
#> CTCF_sites Unassigned 
#>         36       2640 
attr(obj, "cohort_overwrite_count")
#> [1] 0

obj <- av_compare_target(obj, target_col = "custom_cohort",
                         target_value = "CTCF_sites")
obj$stats$comparisons[["custom_cohort=CTCF_sites"]]$results_tidy
#> # A tibble: 1 × 12
#>   group      n_group n_rest median_group median_rest median_diff p_val p_adj
#>   <chr>        <int>  <int>        <dbl>       <dbl>       <dbl> <dbl> <dbl>
#> 1 CTCF_sites      36   2640        0.483       0.494     -0.0115 0.457 0.457
#> # ℹ 4 more variables: effect_size <dbl>, effect_type <chr>, method <chr>,
#> #   significance_stars <chr>