| Title: | Selected Events Linked by Evolutionary Conditions in Cancer |
|---|---|
| Description: | Implements the 'SelectSim' methodology for identifying patterns of co-occurrence and mutual exclusivity between functional genomic alterations in cancer cohorts. The package processes mutation annotation data, constructs alteration matrices, estimates expected alteration-pair frequencies, and quantifies deviations associated with selective interactions. The methodology is described in Iyer et al. (2026) <doi:10.1038/s41588-026-02661-4>. |
| Authors: | Arvind Iyer [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-8247-700X>), Marco Mina [aut], Miljan Petrovic [aut, cph], Giovanni Ciriello [aut, cph] (ORCID: <https://orcid.org/0000-0003-2021-8683>) |
| Maintainer: | Arvind Iyer <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.6 |
| Built: | 2026-07-21 14:46:48 UTC |
| Source: | https://github.com/cran/SelectSim |
Sum a list of matrices element-wise
add(x)add(x)
x |
List of matrices of identical dimensions |
Single matrix that is the element-wise sum of all matrices in x
mats <- list(matrix(1:4, 2, 2), matrix(1:4, 2, 2)) add(mats)mats <- list(matrix(1:4, 2, 2), matrix(1:4, 2, 2)) add(mats)
Compute pairwise alteration statistics for an alteration landscape
al.pairwise.alteration.stats(al, als = NULL, do.blocks = FALSE)al.pairwise.alteration.stats(al, als = NULL, do.blocks = FALSE)
al |
SelectX object (list containing al, W, etc.) |
als |
Alteration landscape stats (from al.stats); computed internally if NULL |
do.blocks |
Whether to also compute block-level pairwise stats |
List with overlap and w_overlap matrices, plus optional sample.blocks entries.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) al.pairwise.alteration.stats(result$obj)data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) al.pairwise.alteration.stats(result$obj)
Compute alteration landscape statistics
al.stats(al)al.stats(al)
al |
SelectX object (list containing al, W, etc. as returned by selectX) |
ALS object with overall and per-block alteration statistics.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) stats <- al.stats(result$obj)data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) stats <- al.stats(result$obj)
Compute pairwise alteration coverage statistics
am.pairwise.alteration.coverage(overlap_M, M.stats, w_overlap_M)am.pairwise.alteration.coverage(overlap_M, M.stats, w_overlap_M)
overlap_M |
The pairwise overlap matrix |
M.stats |
The alteration matrix stats (from am.stats) |
w_overlap_M |
The weighted pairwise overlap matrix |
List with overlap and w_overlap sparse matrices.
am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) W <- matrix(1, nrow = 2, ncol = 3, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) ovlp <- am.pairwise.alteration.overlap(am) wovlp <- am.weight.pairwise.alteration.overlap(am, W) stats <- am.stats(am) am.pairwise.alteration.coverage(ovlp, stats, wovlp)am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) W <- matrix(1, nrow = 2, ncol = 3, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) ovlp <- am.pairwise.alteration.overlap(am) wovlp <- am.weight.pairwise.alteration.overlap(am, W) stats <- am.stats(am) am.pairwise.alteration.coverage(ovlp, stats, wovlp)
Compute pairwise alteration co-occurrence counts
am.pairwise.alteration.overlap(am)am.pairwise.alteration.overlap(am)
am |
Binary alteration matrix (features x samples) |
Square matrix of pairwise co-occurrence counts (features x features).
am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) am.pairwise.alteration.overlap(am)am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) am.pairwise.alteration.overlap(am)
Compute summary statistics for a binary alteration matrix
am.stats(am)am.stats(am)
am |
Binary alteration matrix (features x samples) |
AMS object with basic counts: n.samples, n.alterations, n.occurrences, per-sample and per-feature counts.
am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) am.stats(am)am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) am.stats(am)
Compute TMB-weighted pairwise alteration overlap
am.weight.pairwise.alteration.overlap(am, W)am.weight.pairwise.alteration.overlap(am, W)
am |
Binary alteration matrix (features x samples) |
W |
Weight matrix (features x samples) with per-sample TMB weights |
Weighted pairwise overlap matrix (features x features).
am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) W <- matrix(1, nrow = 2, ncol = 3, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) am.weight.pairwise.alteration.overlap(am, W)am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) W <- matrix(1, nrow = 2, ncol = 3, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) am.weight.pairwise.alteration.overlap(am, W)
Compute Yule Q coefficient for all gene pairs
binary.yule(overlap, mat)binary.yule(overlap, mat)
overlap |
The pairwise overlap matrix |
mat |
The binary GAM (features x samples) |
Matrix of Yule Q coefficients
am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) ovlp <- am.pairwise.alteration.overlap(am) binary.yule(ovlp, am)am <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) ovlp <- am.pairwise.alteration.overlap(am) binary.yule(ovlp, am)
Compute effect size between observed and expected overlap
effectSize(obs, exp)effectSize(obs, exp)
obs |
The observed overlap values |
exp |
The expected (null model mean) overlap values |
Effect size value(s)
effectSize(obs = 5, exp = 3) effectSize(obs = c(5, 2, 0), exp = c(3, 3, 1))effectSize(obs = 5, exp = 3) effectSize(obs = c(5, 2, 0), exp = c(3, 3, 1))
Compute empirical two-sided p-value for a gene pair
estimate_p_val(robs_co, obs.co, gene1, gene2)estimate_p_val(robs_co, obs.co, gene1, gene2)
robs_co |
List of null model overlap matrices (one per permutation) |
obs.co |
Observed pairwise overlap matrix |
gene1 |
Name of the first gene/alteration |
gene2 |
Name of the second gene/alteration |
Two-sided empirical p-value
set.seed(1) genes <- c("geneA", "geneB") robs_co <- lapply(seq_len(20), function(i) { m <- matrix(sample(0:5, 4, replace = TRUE), 2, 2, dimnames = list(genes, genes)) m }) obs_co <- matrix(c(5, 3, 3, 4), 2, 2, dimnames = list(genes, genes)) estimate_p_val(robs_co, obs_co, "geneA", "geneB")set.seed(1) genes <- c("geneA", "geneB") robs_co <- lapply(seq_len(20), function(i) { m <- matrix(sample(0:5, 4, replace = TRUE), 2, 2, dimnames = list(genes, genes)) m }) obs_co <- matrix(c(5, 3, 3, 4), 2, 2, dimnames = list(genes, genes)) estimate_p_val(robs_co, obs_co, "geneA", "geneB")
Compute p-values for all gene pairs in a results table
estimate_pairwise_p(obs, exp, results, nSim)estimate_pairwise_p(obs, exp, results, nSim)
obs |
Observed pairwise overlap matrix |
exp |
List of null model overlap matrices (one per permutation) |
results |
Results data frame with SFE_1 and SFE_2 columns |
nSim |
Number of permutations |
Vector of p-values, one per row in results.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE, estimate_pairwise = TRUE) head(result$result[, c("SFE_1","SFE_2","pairwise_p")])data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE, estimate_pairwise = TRUE) head(result$result[, c("SFE_1","SFE_2","pairwise_p")])
Estimate FDR by scanning observed vs null effect sizes
estimateFDR2(obs, exp, nSim, maxFDR = 0.25)estimateFDR2(obs, exp, nSim, maxFDR = 0.25)
obs |
Vector of observed effect sizes |
exp |
Vector of null model effect sizes (all permutations concatenated) |
nSim |
Number of permutations used to generate exp |
maxFDR |
FDR cutoff; scanning stops once FDR exceeds this value |
Vector of FDR values, one per element of obs.
set.seed(1) obs <- c(0.8, 0.5, 0.3, 0.1) exp <- runif(400) estimateFDR2(obs, exp, nSim = 100)set.seed(1) obs <- c(0.8, 0.5, 0.3, 0.1) exp <- runif(400) estimateFDR2(obs, exp, nSim = 100)
filter_maf_column() takes a maf file and filters a MAF dataframe by retaining only the rows with a column value included in the values list
filter_maf_column(maf, values, column, inclusive = TRUE, fixed = TRUE, ...)filter_maf_column(maf, values, column, inclusive = TRUE, fixed = TRUE, ...)
maf |
a maf as dataframe |
values |
a list containing the elements to filter |
column |
column in maf file to filter |
inclusive |
a boolean to include or exclude the data frame with values in list provided |
fixed |
a grep argument to specify if grep use the argument as string or not |
... |
Other options |
filtered_maf a filtered maf file
data(luad_maf, package = "SelectSim") filter_maf_column(luad_maf, values = "Missense_Mutation", column = "Variant_Classification")data(luad_maf, package = "SelectSim") filter_maf_column(luad_maf, values = "Missense_Mutation", column = "Variant_Classification")
Filter a MAF dataframe by a combination of column values
filter_maf_complex(maf, values, ...)filter_maf_complex(maf, values, ...)
maf |
A MAF dataframe |
values |
A dataframe of (column, value) pairs to match against |
... |
Additional arguments passed to merge |
Filtered MAF dataframe containing only rows matching the value combinations.
data(luad_maf, package = "SelectSim") combos <- data.frame(Hugo_Symbol = "TP53", Variant_Classification = "Missense_Mutation") filter_maf_complex(luad_maf, combos, by.x = c("Hugo_Symbol","Variant_Classification"), by.y = c("Hugo_Symbol","Variant_Classification"))data(luad_maf, package = "SelectSim") combos <- data.frame(Hugo_Symbol = "TP53", Variant_Classification = "Missense_Mutation") filter_maf_complex(luad_maf, combos, by.x = c("Hugo_Symbol","Variant_Classification"), by.y = c("Hugo_Symbol","Variant_Classification"))
Filter a MAF dataframe by gene name
filter_maf_gene.name(maf, genes, gene.col = "Hugo_Symbol", ...)filter_maf_gene.name(maf, genes, gene.col = "Hugo_Symbol", ...)
maf |
A MAF dataframe |
genes |
Vector of gene names to retain |
gene.col |
Column name containing gene symbols |
... |
Additional arguments passed to filter_maf_column |
Filtered MAF dataframe.
data(luad_maf, package = "SelectSim") filter_maf_gene.name(luad_maf, genes = c("TP53", "KRAS"))data(luad_maf, package = "SelectSim") filter_maf_gene.name(luad_maf, genes = c("TP53", "KRAS"))
filter_maf_ignore() takes a maf file and filters a MAF dataframe by retaining only the rows with a column value included in the values list
filter_maf_ignore(maf, schema = TCGA_maf_schema, ...)filter_maf_ignore(maf, schema = TCGA_maf_schema, ...)
maf |
a maf as dataframe |
schema |
a data-frame schema; see |
... |
Other options |
filtered_maf a filtered maf file
data(luad_maf, package = "SelectSim") filter_maf_ignore(luad_maf)data(luad_maf, package = "SelectSim") filter_maf_ignore(luad_maf)
filter_maf_missense() takes a maf file and filters a MAF dataframe by retaining only the rows with a column value included in the values list
filter_maf_missense(maf, schema = TCGA_maf_schema, ...)filter_maf_missense(maf, schema = TCGA_maf_schema, ...)
maf |
a maf as dataframe |
schema |
a data-frame schema; see |
... |
Other options |
filtered_maf a filtered maf file
data(luad_maf, package = "SelectSim") filter_maf_missense(luad_maf)data(luad_maf, package = "SelectSim") filter_maf_missense(luad_maf)
Filter a MAF dataframe by mutation type
filter_maf_mutation.type( maf, variants, variant.col = "Variant_Classification", ... )filter_maf_mutation.type( maf, variants, variant.col = "Variant_Classification", ... )
maf |
A MAF dataframe |
variants |
Vector of variant classification values to retain |
variant.col |
Column name containing variant classifications |
... |
Additional arguments passed to filter_maf_column |
Filtered MAF dataframe.
data(luad_maf, package = "SelectSim") filter_maf_mutation.type(luad_maf, variants = "Missense_Mutation")data(luad_maf, package = "SelectSim") filter_maf_mutation.type(luad_maf, variants = "Missense_Mutation")
Filter a MAF dataframe by specific gene-mutation combinations
filter_maf_mutations( maf, values, maf.col = c("Hugo_Symbol", "HGVSp_Short"), values.col = maf.col, ... )filter_maf_mutations( maf, values, maf.col = c("Hugo_Symbol", "HGVSp_Short"), values.col = maf.col, ... )
maf |
A MAF dataframe |
values |
Dataframe of allowed (gene, mutation) combinations |
maf.col |
Columns in maf to join on |
values.col |
Corresponding columns in values to join on |
... |
Additional arguments passed to filter_maf_complex |
Filtered MAF dataframe containing only rows matching the allowed combinations.
data(luad_maf, package = "SelectSim") allowed <- data.frame(Hugo_Symbol = c("TP53", "KRAS"), HGVSp_Short = c("p.R175H", "p.G12C")) filter_maf_mutations(luad_maf, allowed)data(luad_maf, package = "SelectSim") allowed <- data.frame(Hugo_Symbol = c("TP53", "KRAS"), HGVSp_Short = c("p.R175H", "p.G12C")) filter_maf_mutations(luad_maf, allowed)
Filter a MAF dataframe by sample ID
filter_maf_sample(maf, samples, sample.col = "Tumor_Sample_Barcode", ...)filter_maf_sample(maf, samples, sample.col = "Tumor_Sample_Barcode", ...)
maf |
A MAF dataframe |
samples |
Vector of sample IDs to retain |
sample.col |
Column name containing sample IDs |
... |
Additional arguments passed to filter_maf_column |
Filtered MAF dataframe.
data(luad_maf, package = "SelectSim") ids <- unique(luad_maf$Tumor_Sample_Barcode)[1:5] filter_maf_sample(luad_maf, samples = ids)data(luad_maf, package = "SelectSim") ids <- unique(luad_maf$Tumor_Sample_Barcode)[1:5] filter_maf_sample(luad_maf, samples = ids)
filter_maf_schema() takes a maf file and filters a MAF dataframe by retaining only the rows with a column value included in the values list
filter_maf_schema(maf, schema = TCGA_maf_schema, column, values, ...)filter_maf_schema(maf, schema = TCGA_maf_schema, column, values, ...)
maf |
a maf as dataframe |
schema |
a data-frame schema; see |
column |
column in maf file to filter |
values |
a list containing the elements to file |
... |
Other options |
filtered_maf a filtered maf file
data(luad_maf, package = "SelectSim") filter_maf_schema(luad_maf, TCGA_maf_schema, column = "mutation.type", values = TCGA_maf_schema$mutation.type$truncating)data(luad_maf, package = "SelectSim") filter_maf_schema(luad_maf, TCGA_maf_schema, column = "mutation.type", values = TCGA_maf_schema$mutation.type$truncating)
filter_maf_truncating() takes a maf file and filters a MAF dataframe by retaining only the rows with a column value included in the values list
filter_maf_truncating(maf, schema = TCGA_maf_schema, ...)filter_maf_truncating(maf, schema = TCGA_maf_schema, ...)
maf |
a maf as dataframe |
schema |
a data-frame schema; see |
... |
Other options |
filtered_maf a filtered maf file
data(luad_maf, package = "SelectSim") filter_maf_truncating(luad_maf)data(luad_maf, package = "SelectSim") filter_maf_truncating(luad_maf)
Generate S matrix
generateS(gam, sample.weights, upperBound = 1)generateS(gam, sample.weights, upperBound = 1)
gam |
the gam with genes*samples |
sample.weights |
the samples weights |
upperBound |
clip the values greater than 1 to keep it bounded between 0 to 1 |
S the S matrix
gam <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) generateS(gam, sample.weights = c(s1 = 1, s2 = 1, s3 = 1))gam <- matrix(c(0,1,1,0,1,1), nrow = 2, dimnames = list(c("geneA","geneB"), c("s1","s2","s3"))) generateS(gam, sample.weights = c(s1 = 1, s2 = 1, s3 = 1))
Computes a sample weight matrix that accounts for sample-class covariates
(blocks). Within each block the reference TMB is the block median; the
overall reference used by generateW_mean_tmb is the mean of those
block medians.
generateW_block(al, lambda, tau)generateW_block(al, lambda, tau)
al |
Alteration landscape object (from |
lambda |
Numeric penalty factor for the weight computation. |
tau |
Numeric fold-change threshold below which no penalty is applied. |
List with W_block (per-block weight matrices), W (full
concatenated weight matrix), W_median (per-block median TMBs), and
mean_TMB (mean of block medians).
data(luad_run_data, package = "SelectSim") al <- new.AL.general(luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10) generateW_block(al, lambda = 0.3, tau = 1)data(luad_run_data, package = "SelectSim") al <- new.AL.general(luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10) generateW_block(al, lambda = 0.3, tau = 1)
Computes a per-sample weight matrix based on the ratio of each sample's TMB to
the expected (mean) TMB. Samples with higher-than-expected TMB receive lower
weights via a penalty lambda, controlled by the fold-change threshold
tau.
generateW_mean_tmb( tmb, mean_tmb, ngenes, lambda = 0.3, tau = 1, discrete = TRUE )generateW_mean_tmb( tmb, mean_tmb, ngenes, lambda = 0.3, tau = 1, discrete = TRUE )
tmb |
Numeric vector of per-sample TMB values. |
mean_tmb |
Numeric scalar; the reference (expected) TMB used to compute fold changes. |
ngenes |
Integer; number of genes (rows) in the output weight matrix. |
lambda |
Numeric; weight penalty factor. Higher values penalise high-TMB samples more strongly (default 0.3). |
tau |
Numeric; fold-change threshold below which no penalty is applied (default 1). |
discrete |
Logical; if |
Numeric matrix of sample weights (ngenes x length(tmb)).
tmb <- c(s1 = 10, s2 = 50, s3 = 20) mean_tmb <- 25 generateW_mean_tmb(tmb, mean_tmb, ngenes = 3)tmb <- c(s1 = 10, s2 = 50, s3 = 20) mean_tmb <- 25 generateW_mean_tmb(tmb, mean_tmb, ngenes = 3)
GENIE_maf_schema: schema for GENIE maf file to process the mutations
GENIE_maf_schemaGENIE_maf_schema
A list defining the expected GENIE MAF column schema.
str(GENIE_maf_schema)str(GENIE_maf_schema)
Get sample/alteration blocks
get.blocks(al)get.blocks(al)
al |
The alteration landscape |
Classification of samples and alterations in blocks.
data(luad_run_data, package = "SelectSim") al <- new.AL.general(luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10) get.blocks(al)data(luad_run_data, package = "SelectSim") al <- new.AL.general(luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10) get.blocks(al)
Build the full interaction results table from selectX outputs
interaction.table( al, als, obs, wobs, r.obs = NULL, r.wobs = NULL, null, maxFDR = 0.2, n.cores = 1, estimate_pairwise = FALSE, n.permut = 1000 )interaction.table( al, als, obs, wobs, r.obs = NULL, r.wobs = NULL, null, maxFDR = 0.2, n.cores = 1, estimate_pairwise = FALSE, n.permut = 1000 )
al |
Alteration landscape object (al$am, etc.) |
als |
Alteration landscape stats (from al.stats) |
obs |
Observed pairwise overlap matrix |
wobs |
Weighted observed pairwise overlap matrix |
r.obs |
List of null model overlap matrices |
r.wobs |
List of null model weighted overlap matrices |
null |
Null model list (simulated binary matrices) |
maxFDR |
FDR cutoff for calling significant results |
n.cores |
Number of cores |
estimate_pairwise |
Whether to compute per-pair empirical p-values |
n.permut |
Number of permutations |
Data frame with one row per gene pair and columns for overlap, effect sizes, FDR, and interaction type.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) head(result$result)data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) head(result$result)
MAF file of LUAD from TCGA
data(luad_maf)data(luad_maf)
A data frame
A data frame containing TCGA LUAD mutation data.
data(luad_maf) dim(luad_maf) head(luad_maf)data(luad_maf) dim(luad_maf) head(luad_maf)
Result of LUAD generated by SelectSim with SelectSim run done at min.freq=10.
data(luad_result)data(luad_result)
A data frame
A data frame containing SelectSim results for the LUAD cohort.
data(luad_result) dim(luad_result) head(luad_result)data(luad_result) dim(luad_result) head(luad_result)
Preprocessed TCGA LUAD data ready to pass directly to selectX().
data(luad_run_data)data(luad_run_data)
A named list with four elements:
A named list containing:
A named list of binary alteration matrices (genes x samples),
one per alteration type (e.g., missense, truncating).
A named list of data frames, one per alteration type, each
with columns sample (character) and mutation (integer
TMB count).
Named character vector of sample-type annotations (length = number of samples). Names are sample IDs.
Named character vector of alteration-type annotations (length = number of genes). Names are gene symbols.
A named list containing preprocessed LUAD input data for
selectX().
data(luad_run_data) names(luad_run_data) str(luad_run_data, max.level = 1)data(luad_run_data) names(luad_run_data) str(luad_run_data, max.level = 1)
maf2gam() takes a maf file and converts into gam
maf2gam( maf, sample.col = "Tumor_Sample_Barcode", gene.col = "Hugo_Symbol", value.var = "HGVSp_Short", samples = NULL, genes = NULL, fun.aggregate = length, binarize = TRUE, fill = NA )maf2gam( maf, sample.col = "Tumor_Sample_Barcode", gene.col = "Hugo_Symbol", value.var = "HGVSp_Short", samples = NULL, genes = NULL, fun.aggregate = length, binarize = TRUE, fill = NA )
maf |
A MAF dataframe |
sample.col |
Column name for sample IDs |
gene.col |
Column name for gene symbols |
value.var |
Column used as the value to aggregate |
samples |
Vector of sample IDs to include; NULL keeps all samples present in the MAF |
genes |
Vector of gene names to include; NULL keeps all genes present in the MAF |
fun.aggregate |
Aggregation function applied per (sample, gene) cell |
binarize |
If TRUE, convert aggregated counts to binary presence/absence |
fill |
Value used for missing (sample, gene) combinations |
Numeric matrix (samples x genes) representing the gene alteration matrix.
data(luad_maf, package = "SelectSim") small_maf <- luad_maf[ luad_maf$Tumor_Sample_Barcode %in% unique(luad_maf$Tumor_Sample_Barcode)[1:5], ] gam <- maf2gam(small_maf) dim(gam)data(luad_maf, package = "SelectSim") small_maf <- luad_maf[ luad_maf$Tumor_Sample_Barcode %in% unique(luad_maf$Tumor_Sample_Barcode)[1:5], ] gam <- maf2gam(small_maf) dim(gam)
Mutation list object
mutation_typemutation_type
A list containing the supported mutation-type classifications.
str(mutation_type)str(mutation_type)
Builds an Alteration Landscape object from a list of genome alteration matrices and their corresponding tumor mutation burdens.
new.AL.general( am, feat.covariates = NULL, sample.covariates = NULL, min.freq, verbose = FALSE )new.AL.general( am, feat.covariates = NULL, sample.covariates = NULL, min.freq, verbose = FALSE )
am |
A named list with two required elements: |
feat.covariates |
Named character vector of alteration-type annotations, one
entry per feature (gene). Names must match rownames of the matrices in |
sample.covariates |
Named character vector of sample-type annotations, one
entry per sample. Names must match colnames of the matrices in |
min.freq |
Minimum number of samples a gene must be mutated in (strictly
greater than) to be retained. Features with |
verbose |
Logical; print progress messages. |
An Alteration Landscape (AL) object (list of class "AL") containing
the filtered alteration matrices, TMB vectors, and covariate assignments.
data(luad_run_data, package = "SelectSim") al <- new.AL.general( am = luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10 )data(luad_run_data, package = "SelectSim") al <- new.AL.general( am = luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10 )
Initialize an Alteration Landscape Stats (ALS) container
new.ALS(al)new.ALS(al)
al |
The alteration landscape object (checked for NULL) |
Empty ALS list object.
new.ALS(list())new.ALS(list())
Initialize an Alteration Matrix Stats (AMS) container
new.AMS(am)new.AMS(am)
am |
The alteration matrix (checked for NULL) |
Empty AMS list object.
new.AMS(matrix(0, 2, 2))new.AMS(matrix(0, 2, 2))
Generating the null_simulation matrix
null_model_parallel(al, temp_mat, W, n.cores = 1, n.permut, seed = 42)null_model_parallel(al, temp_mat, W, n.cores = 1, n.permut, seed = 42)
al |
Alteration landscape object |
temp_mat |
template matrices |
W |
weight matrix |
n.cores |
Number of cores |
n.permut |
Number of simulations |
seed |
Random seed |
List of simulated binary matrices (one per permutation)
data(luad_run_data, package = "SelectSim") al <- new.AL.general(luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10) temp_obj <- template.obj.gen(al) W <- generateW_block(al, lambda = 0.3, tau = 1) sims <- null_model_parallel(al, temp_obj$temp_mat, W$W, n.cores = 1, n.permut = 10) length(sims)data(luad_run_data, package = "SelectSim") al <- new.AL.general(luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10) temp_obj <- template.obj.gen(al) W <- generateW_block(al, lambda = 0.3, tau = 1) sims <- null_model_parallel(al, temp_obj$temp_mat, W$W, n.cores = 1, n.permut = 10) length(sims)
Plots each gene pair as a point with observed weighted co-mutation on the y-axis and expected (null model mean) on the x-axis. Significant co-mutations (CO) and mutual exclusivities (ME) are coloured; non-significant pairs are grey.
obs_exp_scatter(result, title)obs_exp_scatter(result, title)
result |
Result table from |
title |
Plot title. |
A ggplot2 object.
data(luad_result, package = "SelectSim") obs_exp_scatter(result = luad_result, title = "TCGA LUAD")data(luad_result, package = "SelectSim") obs_exp_scatter(result = luad_result, title = "TCGA LUAD")
cancer genes list
data(oncokb_genes)data(oncokb_genes)
A list
An object containing cancer-associated genes annotated by OncoKB.
data(oncokb_genes) length(oncokb_genes) head(oncokb_genes)data(oncokb_genes) length(oncokb_genes) head(oncokb_genes)
cancer genes list consider for truncating mutations
data(oncokb_truncating_genes)data(oncokb_truncating_genes)
A list
An object containing genes considered for truncating-mutation analyses.
data(oncokb_truncating_genes) length(oncokb_truncating_genes) head(oncokb_truncating_genes)data(oncokb_truncating_genes) length(oncokb_truncating_genes) head(oncokb_truncating_genes)
Returns the vector of weighted co-mutation values from all null-model permutations for a specific pair of genes.
overlap_pair_extract(gene1, gene2, obj)overlap_pair_extract(gene1, gene2, obj)
gene1 |
Name of the first gene/alteration. |
gene2 |
Name of the second gene/alteration. |
obj |
SelectX object (list returned by |
Numeric vector of length obj$nSim with the null-model
weighted overlap values for the pair.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) genes <- rownames(result$obj$al$am$full)[1:2] overlap_pair_extract(genes[1], genes[2], result$obj)data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) genes <- rownames(result$obj$al$am$full)[1:2] overlap_pair_extract(genes[1], genes[2], result$obj)
Compute null overlap matrix
r.am.pairwise.alteration.overlap(null, n.permut, n.cores = 1)r.am.pairwise.alteration.overlap(null, n.permut, n.cores = 1)
null |
The null model (list of simulated binary matrices) |
n.permut |
Accepted for API compatibility; currently unused internally. |
n.cores |
Accepted for API compatibility; currently unused internally. |
Overlap matrix summed across all permutations.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) r.am.pairwise.alteration.overlap(result$obj$null, n.permut = result$obj$nSim)data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) r.am.pairwise.alteration.overlap(result$obj$null, n.permut = result$obj$nSim)
Compute effect sizes for null model permutations
r.effectSize(null_overlap, mean_mat, n.permut = 1000, n.cores = 1)r.effectSize(null_overlap, mean_mat, n.permut = 1000, n.cores = 1)
null_overlap |
List of null model overlap matrices (one per permutation) |
mean_mat |
Mean overlap matrix across all permutations |
n.permut |
Number of permutations |
n.cores |
Number of cores (currently unused; sequential only) |
List of effect size vectors, one per permutation.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) null_ov <- r.am.pairwise.alteration.overlap(result$obj$null, n.permut = result$obj$nSim) mean_mat <- Reduce("+", null_ov) / result$obj$nSim r.effectSize(null_ov, mean_mat, n.permut = result$obj$nSim)data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) null_ov <- r.am.pairwise.alteration.overlap(result$obj$null, n.permut = result$obj$nSim) mean_mat <- Reduce("+", null_ov) / result$obj$nSim r.effectSize(null_ov, mean_mat, n.permut = result$obj$nSim)
Flags simulations whose mean per-gene and per-sample deviation from the observed counts falls in the top 10%, indicating numerical instability. These are removed before computing effect sizes to prevent them from inflating the null distribution.
retrieveOutliers(obj, nSim = 1000)retrieveOutliers(obj, nSim = 1000)
obj |
SelectX object (list with al and null fields) |
nSim |
Number of simulations in the null model |
Logical vector; TRUE for each null matrix flagged as an outlier.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) outliers <- retrieveOutliers(result$obj, nSim = result$obj$nSim) sum(outliers)data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) outliers <- retrieveOutliers(result$obj, nSim = result$obj$nSim) sum(outliers)
For each significant evolutionary dependency in result_df, plots the
null-model weighted-overlap distribution as a ridge, with vertical lines
marking the observed overlap (red) and mean background (blue).
ridge_plot_ed(result_df, obj)ridge_plot_ed(result_df, obj)
result_df |
Subset of the result table from |
obj |
SelectX object ( |
A ggplot2 ridge-plot object.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) sig_pairs <- head(result$result[result$result$FDR, ], 3) if (nrow(sig_pairs) > 0) ridge_plot_ed(sig_pairs, result$obj)data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) sig_pairs <- head(result$result[result$result$FDR, ], 3) if (nrow(sig_pairs) > 0) ridge_plot_ed(sig_pairs, result$obj)
For each gene pair in result_df, overlays the null-model weighted-overlap
distributions from two separate selectX runs, allowing visual comparison
of evolutionary dependencies across cohorts or conditions.
ridge_plot_ed_compare(result_df, obj1, obj2, name1, name2)ridge_plot_ed_compare(result_df, obj1, obj2, name1, name2)
result_df |
A data frame of gene pairs to display, with columns
|
obj1 |
SelectX object for dataset 1 ( |
obj2 |
SelectX object for dataset 2 ( |
name1 |
Display label for dataset 1. |
name2 |
Display label for dataset 2. |
A ggplot2 ridge-plot object.
data(luad_run_data, package = "SelectSim") r1 <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) r2 <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) common <- head(r1$result, 3) common$dataset1_w_overlap <- common$w_overlap common$dataset2_w_overlap <- common$w_overlap ridge_plot_ed_compare(common, r1$obj, r2$obj, "Run1", "Run2")data(luad_run_data, package = "SelectSim") r1 <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) r2 <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) common <- head(r1$result, 3) common$dataset1_w_overlap <- common$w_overlap common$dataset2_w_overlap <- common$w_overlap ridge_plot_ed_compare(common, r1$obj, r2$obj, "Run1", "Run2")
selectX() takes a list object which consist of genome alteration matrix and tumor mutation burden.
selectX( M, sample.class, alteration.class, n.cores = 1, min.freq = 10, n.permut = 1000, lambda = 0.3, tau = 1, save.object = FALSE, folder = "./", verbose = TRUE, estimate_pairwise = FALSE, maxFDR = 0.25, seed = 42 )selectX( M, sample.class, alteration.class, n.cores = 1, min.freq = 10, n.permut = 1000, lambda = 0.3, tau = 1, save.object = FALSE, folder = "./", verbose = TRUE, estimate_pairwise = FALSE, maxFDR = 0.25, seed = 42 )
M |
a list data object which consist of gams and tmbs. |
sample.class |
sample covariates as named list. |
alteration.class |
alteration covariates as named list. |
n.cores |
no of cores. |
min.freq |
number of samples for features to be at least mutated in. |
n.permut |
number of simulations. |
lambda |
lambda parameter. |
tau |
tau (fold change) parameter. |
save.object |
store the SelectX object. |
folder |
folder path to store the results. |
verbose |
print the time and each steps. |
estimate_pairwise |
Compute pairwise p-value |
maxFDR |
FDR value |
seed |
a random seed |
result a SelectSim object with background model and other info along with result table
data(luad_run_data, package = "SelectSim") result <- selectX( M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE ) head(result$result)data(luad_run_data, package = "SelectSim") result <- selectX( M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE ) head(result$result)
stat_maf_column() takes a maf file and filters a MAF dataframe by retaining only the rows with a column value included in the values list
stat_maf_column(maf, column, ...)stat_maf_column(maf, column, ...)
maf |
a maf as dataframe |
column |
a data-frame schema; see |
... |
Other options |
filtered_maf a filtered maf file
data(luad_maf, package = "SelectSim") stat_maf_column(luad_maf, column = "Variant_Classification")data(luad_maf, package = "SelectSim") stat_maf_column(luad_maf, column = "Variant_Classification")
Count mutations per gene in a MAF file
stat_maf_gene(maf, column = "Hugo_Symbol", ...)stat_maf_gene(maf, column = "Hugo_Symbol", ...)
maf |
A MAF dataframe |
column |
Column name containing gene symbols |
... |
Additional arguments passed to stat_maf_column |
Table of mutation counts per gene.
data(luad_maf, package = "SelectSim") head(stat_maf_gene(luad_maf))data(luad_maf, package = "SelectSim") head(stat_maf_gene(luad_maf))
Count mutations per sample in a MAF file
stat_maf_sample(maf, column = "Tumor_Sample_Barcode", ...)stat_maf_sample(maf, column = "Tumor_Sample_Barcode", ...)
maf |
A MAF dataframe |
column |
Column name containing sample IDs |
... |
Additional arguments passed to stat_maf_column |
Table of mutation counts per sample.
data(luad_maf, package = "SelectSim") head(stat_maf_sample(luad_maf))data(luad_maf, package = "SelectSim") head(stat_maf_sample(luad_maf))
TCGA_maf_schema: schema for TCGA maf file to process the mutations
TCGA_maf_schemaTCGA_maf_schema
A list defining the expected TCGA MAF column schema.
str(TCGA_maf_schema)str(TCGA_maf_schema)
Computes the expected mutation probability matrices (one per GAM type, per
sample block) used as the simulation background in null_model_parallel.
template.obj.gen(al)template.obj.gen(al)
al |
Alteration landscape object |
A list with template.obj (per-block S matrices) and
temp_mat (full concatenated template matrices, one per GAM type).
data(luad_run_data, package = "SelectSim") al <- new.AL.general(luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10) template.obj.gen(al)data(luad_run_data, package = "SelectSim") al <- new.AL.general(luad_run_data$M, feat.covariates = luad_run_data$alteration.class, sample.covariates = luad_run_data$sample.class, min.freq = 10) template.obj.gen(al)
A clean ggplot2 theme for publication-quality plots
theme_Publication(base_size = 14, base_family = "sans")theme_Publication(base_size = 14, base_family = "sans")
base_size |
size of fonts |
base_family |
type of font |
A ggplot2 theme object.
library(ggplot2) ggplot(data.frame(x = 1:3, y = 1:3), aes(x, y)) + geom_point() + theme_Publication()library(ggplot2) ggplot(data.frame(x = 1:3, y = 1:3), aes(x, y)) + geom_point() + theme_Publication()
A dataframe cancer genes with missense mutation annotations
data(variant_catalogue)data(variant_catalogue)
A data frame
A data frame containing cancer-gene and variant annotations.
data(variant_catalogue) dim(variant_catalogue) head(variant_catalogue)data(variant_catalogue) dim(variant_catalogue) head(variant_catalogue)
Compute null weighted overlap matrix
w.r.am.pairwise.alteration.overlap(null, W, n.permut, n.cores = 1)w.r.am.pairwise.alteration.overlap(null, W, n.permut, n.cores = 1)
null |
The null model (list of simulated binary matrices) |
W |
The weight matrix (features x samples) |
n.permut |
Accepted for API compatibility; currently unused internally. |
n.cores |
Accepted for API compatibility; currently unused internally. |
Weighted overlap matrix summed across all permutations.
data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) w.r.am.pairwise.alteration.overlap(result$obj$null, W = result$obj$W$W, n.permut = result$obj$nSim)data(luad_run_data, package = "SelectSim") result <- selectX(M = luad_run_data$M, sample.class = luad_run_data$sample.class, alteration.class = luad_run_data$alteration.class, n.cores = 1, min.freq = 10, n.permut = 10, verbose = FALSE) w.r.am.pairwise.alteration.overlap(result$obj$null, W = result$obj$W$W, n.permut = result$obj$nSim)