select_variants: Select and filter variants
In Townsend-Lab-Yale/cancereffectsizeR: Calculate Cancer Effect Size

select_variants

R Documentation

Select and filter variants

Description

This function helps you find and view variant data from your CESAnalysis's MAF data and mutation annotation tables. By default, almost all coding substitutions (amino acid changes; AACs) and noncoding SNVs are returned. You can apply a series of filters to restrict output to certain genes or genomic regions or require a minimum variant frequency in MAF data. You can also specify some variants to include in output regardless of filters with variant_ids. Special behavior: If variant_ids is used by itself, then only those specified variants will be returned.

Usage

select_variants(
  cesa,
  genes = NULL,
  min_freq = 0,
  variant_ids = NULL,
  gr = NULL,
  variant_position_table = NULL,
  include_subvariants = F,
  padding = 0,
  collapse_lists = F,
  remove_secondary_aac = TRUE
)

Arguments

`cesa`	CESAnalysis with MAF data loaded and annotated (e.g., with `load_maf()`)
`genes`	Filter variants to specified genes.
`min_freq`	Filter out variants with MAF frequency below threshold (default 0). Note that variants that are not in the annotation tables will never be returned. Use `add_variants()` to include variants absent from MAF data in your CESAnalysis.
`variant_ids`	Vector of variant IDs to include in output regardless of filtering options. You can also use variant names like "KRAS G12C". If this argument is used by itself (without any filtering arguments), then only these specified variants will be returned.
`gr`	Filter out any variants not within input GRanges +/- `padding` bases.
`variant_position_table`	Filter out any variants that don't intersect the positions given in chr/start/end of this table (1-based closed coordinates). Typically, the table comes from a previous `select_variants` call and can be expanded with `padding`. (Gritty detail: Amino acid change SNVs get special handling. Only the precise positions in start, end, and center_nt_pos are used. This avoids intersecting extra variants between start/end, which on splice-site-spanning variants can be many thousands.)
`include_subvariants`	Some mutations "contain" other mutations. For example, in cancereffectsizeR's ces.refset.hg19, KRAS_Q61H contains two constituent SNVs that both cause the same amino acid change: 12:25380275_T>G and 12:25380275_T>A. When include_subvariants = F (the default), and genes = "KRAS", output will be returned for KRAS_Q61H but not for the two SNVs (although their IDs will appear in the Q61H output). Set to true, and all three variants will be included in output, assuming they don't get filtered out by other other options, like min_freq. If you set this to TRUE, you can't directly plug the output table into selection functions. However, you can pick a non-overlapping set of variant IDs from the output table and re-run `select_variants()` to put those variants into a new table for selection functions.
`padding`	add +/- this many bases to every range specified in `gr` or `variant_position_table` (stopping at chromosome ends, naturally).
`collapse_lists`	Some output columns may have multiple elements per variant row. For example, all_genes may include multiple genes. These variable-length vectors allow advanced filtering and manipulation, but the syntax can be tricky. Optionally, set collapse_lists = T to convert these columns to comma-delimited strings, which are sometimes easier to work with.
`remove_secondary_aac`	Default TRUE, except overridden (effectively FALSE) when include_subvariants = T. Due to overlapping coding region definitions in reference data (e.g., genes with multiple transcripts), a site can have more than one amino-acid-change annotation. To avoid returning the same genome-positional variants multiple times, the default is to return one AAC in these situations. Tiebreakers are essential splice site status, premature stop codon, MANE/MANE PLUS status if available (favoring canonical or medically relevant transcripts), non-silent status, MAF prevalence, gene/protein mutation count, and sorting order. If you set remove_secondary_aac to FALSE, you can't put the output variant table in selection calculation functions. An alternative is to set to FALSE, pick which (non-overlapping) variants you want, and then re-run select_variants() with those variants specified in `variant_ids`.

Details

Only variants that are present in the CESAnalysis's annotation tables can be returned, which by default are those present in the MAF data. To select variants absent from MAF data, you must first call add_variants() to add them to the CESAnalysis. Note that while intergenic SNVs have their nearest genes annotated in the SNV tables, these variants will not be captured by gene-based selection with this function, since they're not actually in any gene.

Definitions of some less self-explanatory columns:

variant_name: In a coding variant, gene and protein change on the (MANE) canonical transcripts, such as "BRAF V600E". For coding changes reported on other transcripts, the protein ID is included: "POLH W415C (ENSP00000361300.1)". With older reference data sets (ces.refset.hg19, versions of ces.refset.hg38 < 1.3, and any custom reference data set that doesn't have complete information on canonical transcripts), the variant name is a shortening of the variant_id.
start/end: Lowest/highest genomic positions overlapping variant.
variant_id: Unique IDs for variants given the associated genome assembly version and the transcript data.
ref/alt: Genomic reference and alternate alleles (for genomic variants; NA for AACs).
Gene: the affected gene in AACs; for SNVs, the overlapping gene (arbitrarily chosen when more than one overlap), or the nearest gene for intergenic/intronic SNVs.
strand: for AACs, 1 if the reference sequence strand is the coding strand; -1 otherwise.
essential_splice: Variant is 1,2 bp upstream or 1,2,5 bp downstream of an annotated splice position (edge case: if an SNV has multiple gene/transcript annotations, this doesn't say which one it's essential for).
intergenic: variant does not overlap any coding regions in the reference data
trinuc_mut: for SNVs, the reference trinucleotide context, in deconstructSigs notation
coding_seq: coding strand nucleotides in order of transcription
center_nt_pos: regardless of strand, start/end give positions of two out of three AAC nucleotides; this gives the position of the center nucleotide (maybe useful if the AAC spans a splice site)
constituent_snvs: all SNVs that can produce a given variant
multi_anno_site: T/F whether variant has multiple gene/transcript/AAC annotations
all_genes: all genes overlapping the variant in reference data
maf_prevalence: number of occurrences of the variant in MAF data
samples_covering: number of MAF samples with sequencing coverage at the variant site