cmap/sig_gutc_tool repository overview

⁠Description:

Sig GUTC computes the similarity between input genesets (queries) and perturbational gene expression signatures in the CMap database. The results are transformed to a percentile scale and reported at different levels of granularity to aid interpretation.

Briefly the algorithm operates as follows. First raw similarity scores between a query and CMap signatures are computed. While the method is agnostic to the specific similarity metric used, the default choice is a two-tailed weighted enrichment score.

The raw scores are then scaled (Normalized) to adjust for co-variates like cell line and the type of perturbation. The normalized scores are transformed to percentile scores by comparing the test scores to those of a reference collection of signatures called Touchstone.

The per-signature normalized connectivity scores are summarized to yield connectivity to individual perturbagens within a cell line, across-cell lines and for perturbational classes (PCLs). Any summary statistic can be employed, but in practice the maximal-quantile (MAXQ) score is used. Given a set of scores X and a pair of percentiles PL and PU, MAXQ returns the percentile value of X that has the maximum absolute value (By default GUTC uses PL=33 and PU=67).

At each level of summarization, percentile scores are re-computed by comparing to the corresponding results when applied to the Touchstone signatures. For a given connection, the percentiles are computed within perturbagens with the cell type that the connection corresponds to.

An important variant of GUTC is the matched mode specified by the is_matched parameter. Matched mode incorporates cell-line information when query data has been generated systematically in cell types that match the touchstone signatures. Currently this includes the following 9 cell types : [A375, A549, HEPG2, HCC515, HA1E, HT29, MCF7, PC3, VCAP]. To run GUTC in this mode, the is_matched flag should be set to true. Also, the required metadata should be provided using the query_meta argument. Note that the the tool expects 1 query per cell-line for each unique [pert_id, pert_idose, pert_itime] combination. The default query grouping variables can be changed using the match_group argument.

⁠Synopsis:

sig_gutc_tool [--help, -h] [--undef_action UNDEF_ACTION] [-o, --out OUT] [--runtests] [--rundemo] [--rpt RPT] [--create_subdir CREATE_SUBDIR] [--verbose VERBOSE] [--encode_url ENCODE_URL] [--config CONFIG] [--query_result QUERY_RESULT] [--up, --uptag UP] [--down, --dntag DOWN] [--query_meta QUERY_META] [--is_matched IS_MATCHED] [--match_group MATCH_GROUP] [--metric METRIC] [--es_tail ES_TAIL] [--feature_space FEATURE_SPACE] [--sample_space SAMPLE_SPACE] [--pcl_set PCL_SET] [--bkg_path BKG_PATH]

⁠Arguments:

--help, -h Show this help message and exit --undef_action UNDEF_ACTION Action to take if an undefined argument is encountered. Default is error. Options are {error|warn|ignore} -o, --out OUT Output path --runtests Execute functional and unit tests. Default is 0 --rundemo Run the tool with sample inputs. Default is 0 --rpt RPT Report folder prefix --create_subdir CREATE_SUBDIR Create subfolder within out for saving results. Default is 1 --verbose VERBOSE Print debugging messages. Default is 1 --encode_url ENCODE_URL Encode all input URLs. Default is 0 --config CONFIG Argument configuration file --query_result QUERY_RESULT Load pre-computed query results from supplied connectivity matrix. --up, --uptag UP Geneset(s) to use for the up portion of the query --down, --dntag DOWN Geneset(s) to use for the down portion of the query --query_meta QUERY_META Metadata for each query. This is required for matched_mode. The following fields are required for matching with default parameters: [pert_id, cell_id, pert_idose, pert_itime] --is_matched IS_MATCHED If true, compute GUTC in cell-line matched mode. Default is 0 --match_group MATCH_GROUP Query grouping variable(s) for cell-line matching. Note that the tool expects 1 query per cell-line for each unique grouping. Default is pert_id|pert_idose|pert_itime --metric METRIC Similarity metric. Default is wtcs. Options are {wtcs} --es_tail ES_TAIL Specify two-tailed or one-tailed statistic for enrichment metrics. Default is both. Options are {both|up|down} --feature_space FEATURE_SPACE Feature space for comparisions. Default is bing. Options are {lm|bing|bing_v1|bing_v2|full} --sample_space SAMPLE_SPACE Signature space. Default is full. Options are {full} --pcl_set PCL_SET Perturbational classes in GMT format. Default is /cmap/data/vdb/touchstone_v1.1/matched/annot/pcl_n171_20170201.gmt --bkg_path BKG_PATH Path to background signature definition and percentile transforms. Default is /cmap/data/vdb/touchstone_v1.1/matched

⁠Examples:

Run queries and apply GUTC sig_gutc_tool --up up.gmt --down down.gmt

Apply GUTC on pre-computed query results sig_gutc_tool --query_result /path/to/sig_query/results/wtcs.gctx

Run GUTC in cell-line matched mode sig_gutc_tool --query_result /path/to/sig_query/results/wtcs.gctx --query_meta /path/to/query_info.txt --is_matched 1