Skip to contents

Pathway enrichment network

Source: R/pathway_enrichment_networks.R
enrichment_network_vis.Rd

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 and cluster 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" if intersection_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. If label_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 set label_nodes to FALSE.

multitissue_pathways_only

boolean. If TRUE, only include pathways in the network if they are significantly enriched in more than one tissue in pw_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. If out_html exists and overwrite_html=FALSE, then the path out_html is returned.

return_html

boolean, whether to return the path to out_html. If FALSE, return the visNetwork object instead. FALSE by default.

return_graph_for_cytoscape

boolean. If TRUE, return an igraph 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
#>