Create Term-Gene Graph

Create Term-Gene Graph

create_term_gene_graph(
  result_df,
  genes_df = NULL,
  order_by = "lowest_p",
  term_size = "num_genes",
  term_fill = NULL,
  num_terms = 10,
  use_description = FALSE,
  use_edge_weights = FALSE
)

Arguments

result_df

A dataframe of pathfindR results that must contain the following columns:

Term_Description

Description of the enriched term (necessary if use_description = TRUE)

ID

ID of the enriched term (necessary if use_description = FALSE)

lowest_p

the lowest adjusted-p value of the given term over all iterations

Up_regulated

the up-regulated genes in the input involved in the given term's gene set, comma-separated

Down_regulated

the down-regulated genes in the input involved in the given term's gene set, comma-separated

genes_df

(optional) the input data that was used with run_pathfindR (default: NULL). It must be a data frame with at least 2 columns:

1. Gene.Symbol (required)

2. logFC (required)

order_by

Argument to order the `result_df`, this influences the `num_terms` displayed (default: 'lowest_p').

term_size

Argument to indicate whether to use number of significant genes ('num_genes')

term_fill

Argument to indicate by what column to fill the term nodes (e.g. term_fill = "Fold_Enrichment") (default: NULL).

num_terms

Number of top enriched terms to use while creating the graph. Set to NULL to use all enriched terms (default = 10, i.e. top 10 terms)

use_description

Boolean argument to indicate whether term descriptions (in the 'Term_Description' column) should be used. (default: FALSE)

use_edge_weights

Boolean argument to indicate whether genes are weighted by their term interactions, similar to an Up-Set plot but in graph context (default = FALSE). or the -log10(lowest p value) ('p_val') for adjusting the term node sizes (default: 'num_genes')

Value

A igraph object

Details

This function constructs an igraph object from pathfindR output, creating a network that connects enriched biological terms to their involved genes. By default, the graph connects term nodes to up-regulated genes and down-regulated genes. The size of term nodes can be adjusted by either the number of significant genes (`term_size = 'num_genes'`) or by the statistical significance (`term_size = 'p_val'`, using -log10(lowest p value)).

When `genes_df` is provided, gene nodes contain values and not mere up/down binary values, allowing visualization of expression direction and magnitude. When `term_fill` is supplied, term nodes obtain values enabling simultaneous visualization of pathway enrichment strength.

Setting `use_edge_weights = TRUE` highlights hub genes by weighting edges based on how many terms a gene participates in, similar to an Up-Set plot but in a graph context. The `num_terms` parameter controls how many top enriched terms are included (default: top 10), and `order_by` determines the ordering criterion for term selection. The resulting igraph object can be visualized using create_term_gene_plot.

Examples

# Normal gene-term with up/down regulated genes
g <- create_term_gene_graph(
  result_df = example_pathfindR_output
)
g <- create_term_gene_graph(
  result_df = example_pathfindR_output,
  num_terms = 5
)
g <- create_term_gene_graph(
  result_df = example_pathfindR_output,
  term_size = "p_val"
)

# Coloring the term nodes
g <- create_term_gene_graph(
  result_df = example_pathfindR_output,
  term_fill = "Fold_Enrichment"
)

# Adding edge weights
g <- create_term_gene_graph(
  result_df = example_pathfindR_output,
  term_fill = "Fold_Enrichment",
  use_edge_weights = TRUE
)