Plot an interactive network of pathway enrichments.
Usage
enrichment_network_vis(
pw_enrich_res = NULL,
tissues = NULL,
assays = MotrpacRatTraining6moData::ASSAY_ABBREV,
cluster = NULL,
feature_to_gene = MotrpacRatTraining6moData::FEATURE_TO_GENE_FILT,
intersection_id_type = "ensembl_gene",
similarity_cutoff = 0.375,
adj_pval_cutoff = 0.1,
title = NULL,
label_nodes = TRUE,
add_group_label_nodes = FALSE,
parent_pathways = MotrpacRatTraining6moData::PATHWAY_PARENTS,
multitissue_pathways_only = FALSE,
include_metab_singletons = TRUE,
similarity_scores_file = NULL,
out_html = "/dev/null",
overwrite_html = TRUE,
return_html = FALSE,
return_graph_for_cytoscape = FALSE,
verbose = TRUE
)
Arguments
- pw_enrich_res
optional data frame of enrichment results. May be a subset of MotrpacRatTraining6moData::GRAPH_PW_ENRICH or a data frame returned from
cluster_pathway_enrichment()
. Columns must include "adj_p_value", "ome", "tissue", "intersection", "computed_p_value", "term_name", "term_id". If not specified,tissues
andcluster
must be specified.NULL
by default.- tissues
character vector of tissue abbreviations, at least one of MotrpacRatTraining6moData::TISSUE_ABBREV. Used to subset MotrpacRatTraining6moData::GRAPH_PW_ENRICH. Must be specified if
pw_enrich_res
is not provided.NULL
by default.- assays
optional character vector of assay abbreviations, at least one of MotrpacRatTraining6moData::ASSAY_ABBREV. Used to subset MotrpacRatTraining6moData::GRAPH_PW_ENRICH. All assays by default.
- cluster
character, graphical cluster of interest. Used to subset MotrpacRatTraining6moData::GRAPH_PW_ENRICH. Must be specified if
pw_enrich_res
is not provided. e.g., "8w_F1_M1" for features that are up-regulated (1) in females (F) and up-regulated in males (M1) at 8 weeks of training (8w), or "1w_F0_M1->2w_F0_M1->4w_F0_M1->8w_F1_M1" for features that are up-regulated in males at all time points (1w_F?_M1, 2w_F?_M1, 4w_F?_M1, 8w_F?_M1) and up-regulated in females at 8 weeks of training only. See MotrpacRatTraining6moData::GRAPH_PW_ENRICH$graphical_cluster
for all possible options. See the vignette for a detailed description of how to interpret and construct these strings.NULL
by default.- feature_to_gene
data frame, map between
intersection_id_type
and gene symbols. Columns must include "gene_symbol" and "ensembl_gene" ifintersection_id_type == "ensembl_gene"
. MotrpacRatTraining6moData::FEATURE_TO_GENE_FILT by default.- intersection_id_type
character, type of gene identifier used to define
pw_enrich_res$intersection
, either "ensembl_gene" or "gene_symbol". "ensembl_gene" by default.- similarity_cutoff
numeric, edges are drawn between pairs of pathways if they have a similarity metric above this value. Increase this value to make a sparser network; decrease it to make a denser network. 0.375 by default.
- adj_pval_cutoff
numeric, pathway enrichments are only considered for the network if the corresponding adjusted p-value (
pw_enrich_res$adj_p_value
) is less than this value. 0.1 (10% FDR) by default.- title
character, plot title.
NULL
by default.- label_nodes
boolean, whether to label groups at all.
TRUE
by default. Iflabel_nodes = FALSE
,add_group_label_nodes
is ignored.- add_group_label_nodes
boolean, whether to label groups with nodes. If
FALSE
, use a standard legend instead.- parent_pathways
named list, map of KEGG and REAC pathway term ID to parent pathway. Used to create labels for clusters of pathway enrichments. List names must correspond to values in
pw_enrich_res$term_id
. MotrpacRatTraining6moData::PATHWAY_PARENTS by default. If NULL, then only the pathway names are used to create cluster labels, which is quite meaningless is all pathway names are unique. In that case, it is recommended to setlabel_nodes
toFALSE
.- multitissue_pathways_only
boolean. If
TRUE
, only include pathways in the network if they are significantly enriched in more than one tissue inpw_enrich_res
.- include_metab_singletons
boolean. If
TRUE
, include pathways enriched only by metabolites (ome METAB) as singleton nodes- similarity_scores_file
character or
NULL
, path in which to save pairwise pathway similarity scores as an RDS file. If this file exists, the pairwise similarity scores are loaded from the file instead of being recalculated.NULL
by default.- out_html
character, output file for HTML. "/dev/null" by default.
- overwrite_html
boolean, whether to overwrite
out_html
if it already exists.TRUE
by default. Ifout_html
exists andoverwrite_html=FALSE
, then the pathout_html
is returned.- return_html
boolean, whether to return the path to
out_html
. IfFALSE
, return thevisNetwork
object instead.FALSE
by default.- return_graph_for_cytoscape
boolean. If
TRUE
, return anigraph
graph object that can be exported to Cytoscape.- verbose
boolean, whether to print verbose output
Value
If return_graph_for_cytoscape=FALSE
and return_html=FALSE
, return a
visNetwork
graph. If return_graph_for_cytoscape=TRUE
, return an
igraph object. If return_html=TRUE
, return the path to the HTML file in
which the interactive visNetwork
was saved.
Details
Inspired by the EnrichmentMap Cytoscape App. Each node is a significantly enriched pathway; edges connect nodes where there is a high overlap between the sets of genes underlying each pathway enrichment. For pathways with significant enrichments in multiple assays, genes are combined across assays to calculate this similarity score. Node size is proportional to the number of datasets (tissue and assay combinations) with a significant enrichment; edge weight is scaled to the similarity score. Presenting pathway enrichments in this way allows groups of highly similar pathways to be more easily summarized at a higher level.
Nodes in the graph are colored by the cluster of nodes they belong to, determined
by igraph::cluster_louvain()
. If label_nodes = TRUE
, node labels indicate
the cluster number, a summary term for the cluster, and the number of nodes in
the cluster from which this summary term was derived, e.g., "3: Fatty acid metabolism (4/15)".
The summary term is defined as the most common pathway or parent pathway name.
For example, the "3: Fatty acid metabolism (4/15)" label indicates that the pathway
or parent pathway name for 4 out of 15 nodes in cluster 3 are "Fatty acid metabolism".
See also
Ancillary functions include calc_similarity_metric()
, replace_ensembl_with_symbol()
,
format_gene_symbols()
, edge_intersection()
, collapse_p()
, add_line_breaks()
,
format_gene_lists()
, and cleanup()
.
The input pw_enrich_res
can also be generated with cluster_pathway_enrichment()
.
Examples
# Example 1: Plot an interactive network of pathway enrichments from the HEART:8w_F1_M1 node,
# i.e., features that are up-regulated in both males and females after 8 weeks of training
enrich_res = MotrpacRatTraining6moData::GRAPH_PW_ENRICH
enrich_res = enrich_res[enrich_res$cluster == "HEART:8w_F1_M1",]
enrichment_network_vis(enrich_res, add_group_label_nodes = TRUE)
#> Formatting inputs...
#> Subsetting feature-to-gene map...
#> Calculating similarity metric between pairs of enriched pathways...
#> Constructing graph...
#> Elapsed time: 0.392s
#>
# # Equivalently:
# enrichment_network_vis(tissues="HEART",
# cluster="8w_F1_M1",
# add_group_label_nodes = TRUE)
if (FALSE) { # \dontrun{
# Example 2: Export the above network to Cytoscape.
# Cytoscape must be running locally for this to work.
library(RCy3)
g = enrichment_network_vis(enrich_res, return_graph_for_cytoscape = T)
RCy3::cytoscapePing()
RCy3::createNetworkFromIgraph(g, new.title='HEART:8w_F1_M1')
} # }
# Example 3: Plot an interactive network of pathway enrichments corresponding to
# features that are up-regulated in both sexes at 8 weeks in any of the 3 muscle tissues.
# Only include pathways that are enriched in at least 2 muscle tissues.
# Plot the color legend on the left instead of using colored labels pointing to nodes
enrichment_network_vis(tissues = c("SKM-GN","SKM-VL","HEART"),
cluster = "8w_F1_M1",
similarity_cutoff = 0.3,
title = "Muscle 8w_F1_M1",
add_group_label_nodes = FALSE,
multitissue_pathways_only = TRUE)
#> Formatting inputs...
#> Subsetting feature-to-gene map...
#> Calculating similarity metric between pairs of enriched pathways...
#> Constructing graph...
#> Elapsed time: 0.947s
#>