Compare signatures from the SigRepo database

A SigRepo front end to OmicSignature::compare_omic_signatures(). It takes every argument that function takes, with the same defaults, and adds a way to assemble the two signature lists from the database.

Each list is built from up to three sources, kept in this order: database signature ids (signature_ids), database signature names (signature_names), and OmicSignature objects supplied directly (omic_signatures). The *2 arguments build the optional second list, the counterpart of sig_list2. With only the first list every signature is compared against every other one (a self-comparison, which needs at least two signatures). With both lists each signature in the first is compared against each in the second, giving rectangular result matrices with the first list as rows and the second as columns; one signature per side is enough. For method = "ks_rank", "ks_score" and "gsea" the second list is the ranking side and needs bi-directional signatures with a difexp table, exactly as for sig_list2.

Ids and names are resolved with searchSignature() and then fetched one at a time with getSignature(), so the outcome of every request is known. Ids or names that do not exist, and signatures the connected account is not allowed to see, are reported in a warning and left out, and the comparison goes ahead on whatever could be assembled for that list; only when that leaves the list empty is it an error instead. Names are matched case-insensitively, and a name shared by several users' signatures matches all of them. A signature requested by both id and name is included once. Fetched signatures are named by their signature_name; because names are only unique per user, fetched signatures that share a name are told apart as "name (id N)". Supplied objects keep their list names, or fall back to their metadata signature_name.

The rank-based methods rank each ranking signature's difexp table by p_value_col. Stored tables do not all name that column the same way, so a ranking signature whose table has no p_value_col is ranked by its pvalue column, the same raw p-values under another name. A table with neither is ranked by adj_p_col, and a warning names those signatures: adjustment keeps the order of the p-values, so KS results stay close to a raw p-value ranking, but GSEA scores can shift. This is done on copies; nothing is written to the database and supplied objects are not modified.

Everything else – cutoff validation, label pairing, the comparison itself and its warnings and errors – is OmicSignature::compare_omic_signatures()'s, unchanged. The value is that function's list, so it can be passed straight to OmicSignature::signature_similarity_heatmap().

Usage

compareSignatures(
  conn_handler = NULL,
  signature_ids = NULL,
  signature_names = NULL,
  omic_signatures = NULL,
  signature_ids2 = NULL,
  signature_names2 = NULL,
  omic_signatures2 = NULL,
  method = c("overlap", "ks_rank", "ks_score", "ks", "gsea"),
  background = NULL,
  score_cutoff = 0,
  adj_p_cutoff = 0.05,
  min_features = 5,
  max_feature = 500,
  label_pairing = NULL,
  label_pairing2 = NULL,
  feature_col = "feature_name",
  score_col = "score",
  adj_p_col = "adj_p",
  p_value_col = "p_value",
  group_col = "group_label",
  adjust = FALSE,
  p_adjust_method = "BH",
  alternative = "greater",
  gsea_score = "NES",
  minSize = 1,
  maxSize = Inf,
  nproc = 0,
  verbose = FALSE,
  ...
)

Arguments

conn_handler: An R object obtained from SigRepo::newConnHandler(). Required whenever signatures are requested by id or name.
signature_ids: Database signature ids for the first list.
signature_names: Database signature names for the first list.
omic_signatures: An OmicSignature object, a list of OmicSignature objects, or an OmicSignatureCollection for the first list.
signature_ids2: Database signature ids for the optional second list.
signature_names2: Database signature names for the optional second list.
omic_signatures2: An OmicSignature object, a list of OmicSignature objects, or an OmicSignatureCollection for the optional second list.
method: Comparison method: "overlap", "ks_rank", "ks_score" or "gsea"; "ks" is accepted as an alias for "ks_rank". The rank-based methods need difexp tables.
background: Optional background feature vector for overlap tests.
score_cutoff: Minimum absolute score to include in a signature.
adj_p_cutoff: Maximum adjusted p-value to include in a signature.
min_features: Minimum number of features retained per label-specific signature (at least 3).
max_feature: Maximum number of features retained per label-specific signature.
label_pairing: Optional named list giving the two group-label levels to compare for signatures in the first list. Names refer to the signature names used in the result: the list names of supplied objects (their metadata signature_name when unnamed), and the database signature_name of fetched ones, including the "name (id N)" form given to fetched signatures that share a name.
label_pairing2: The same for the second list.
feature_col: Column containing feature identifiers.
score_col: Column containing scores in signature and difexp tables.
adj_p_col: Column containing adjusted p-values in difexp tables.
p_value_col: Column containing raw p-values used to rank difexp tables. A ranking signature without it is ranked by a pvalue column instead, or failing that by adj_p_col, with a warning.
group_col: Column containing phenotype group labels.
adjust: Logical; adjust p-values within each returned comparison.
p_adjust_method: Multiple-testing correction method.
alternative: Alternative hypothesis for the Fisher and KS tests.
gsea_score: Column of the fgsea output returned as the score matrix.
minSize: Minimum pathway size passed to fgsea.
maxSize: Maximum pathway size passed to fgsea.
nproc: Number of fgsea workers.
verbose: Logical; whether to print diagnostic messages while resolving and fetching signatures. Defaults to FALSE.
...: Additional arguments passed on to fgsea for method = "gsea".

Value

The list returned by OmicSignature::compare_omic_signatures(): method, comparisons, label_order and background. For a two-list comparison label_order holds both sig_list1 and sig_list2.

Details

See ?OmicSignature::compare_omic_signatures for the full description of every comparison argument, of how uni-directional signatures are handled, and of the result.

Required and optional arguments

Only the signatures are required. Every other argument is optional.

First list (required): any mix of signature_ids, signature_names and omic_signatures. On its own it must hold at least two signatures, since each is compared with the others.
Second list (optional): any mix of signature_ids2, signature_names2 and omic_signatures2. With a second list, one signature per list is enough.
conn_handler: required only when a signature is requested by id or name. Comparing supplied OmicSignature objects needs no connection.

So the smallest calls are compareSignatures(conn_handler, signature_ids = c(12, 34)) and compareSignatures(omic_signatures = list(a = sig_a, b = sig_b)).

Leaving the other arguments alone runs an overlap (Fisher's exact) test on each signature's features. For each signature it keeps features with adj_p at most 0.05 (adj_p_cutoff) and no score cutoff (score_cutoff = 0). It uses at least 5 (min_features) and at most 500 (max_feature) features, and reads the standard SigRepo columns (feature_name, score, adj_p, p_value, group_label). Change the column arguments only when your tables name them differently. The arguments that take NULL treat it as "choose for me" rather than "nothing":

background = NULL uses every feature in the compared signatures' signature and difexp tables.
label_pairing = NULL pairs each bi-directional signature's two group_label levels by position (level 1 with level 1). A warning says when that may not line up; pass label_pairing to pin the pairs.
Leaving the *2 arguments out runs a self-comparison.

method = "ks_rank", "ks_score" and "gsea" also need a ranking signature: at least one bi-directional signature with a difexp table in the second list, or in the first list for a self-comparison. "gsea" needs the fgsea package. Categorical signatures are not supported by any method.

Examples

# The bundled example signatures need no database
utils::data("omic_signature_1", "omic_signature_2", "omic_signature_3", package = "SigRepo")

res <- SigRepo::compareSignatures(
  omic_signatures = list(v1 = omic_signature_1, v2 = omic_signature_2, v3 = omic_signature_3),
  method = "overlap",
  min_features = 3,
  max_feature = 10
)
res$comparisons$level1_vs_level1$jaccard
#>    v1 v2 v3
#> v1  1  1  1
#> v2  1  1  1
#> v3  1  1  1

# Query versus reference: rows are the first list, columns the second
res2 <- SigRepo::compareSignatures(
  omic_signatures = list(v1 = omic_signature_1),
  omic_signatures2 = list(v2 = omic_signature_2, v3 = omic_signature_3),
  method = "ks_rank",
  min_features = 3,
  max_feature = 10
)
res2$comparisons$level1_vs_level1$score
#>           v2        v3
#> v1 0.9939467 0.9939467

if (FALSE) { # \dontrun{
conn_handler <- SigRepo::newConnHandler(
  dbname = "sigrepo", host = "localhost", port = 3306,
  user = "your_username", password = "your_password"
)

# Signatures stored in the database, by id and by name
res <- SigRepo::compareSignatures(
  conn_handler = conn_handler,
  signature_ids = c(12, 34),
  signature_names = "my_signature",
  method = "overlap"
)

# A query signature against a reference set, mixing stored and local ones
res <- SigRepo::compareSignatures(
  conn_handler = conn_handler,
  signature_ids = 12,
  signature_ids2 = c(34, 56),
  omic_signatures2 = list(local = my_omic_signature),
  method = "gsea"
)
} # }