Visualise the community structure in significantly perturbed gene-set network

plot_community(
  normalisedScores,
  gsTopology,
  gsAnnotation = NULL,
  colorBy = c("robustZ", "pvalue", "community"),
  communityMethod = "cluster_louvain",
  foldGSname = TRUE,
  foldafter = 2,
  layout = "fr",
  markCommunity = "ellipse",
  markAlpha = 0.2,
  edgeAlpha = 0.8,
  up_col = "brown3",
  down_col = "steelblue3",
  scale_edgeWidth = c(0.5, 3),
  edgeLegend = FALSE,
  scale_nodeSize = c(3, 6),
  nodeShape = 16,
  color_lg_title = NULL,
  lb_size = 3,
  lb_color = "black",
  plotIsolated = FALSE,
  ...
)

Arguments

normalisedScores: A data.frame derived from the normalise_by_permu() function
gsTopology: List of pathway topology matrices generated using function retrieve_topology()
gsAnnotation: A data.frame containing gene-sets categories used for pathway annotation. Must contain at least two columns: c("gs_name", "category"), where gs_name denotes gene-sets names that are matched to names of pathway topology matrices, and category records the categorization of the given pathway. If customized annotation is not provided, it's assumed that the pathways investigated were from KEGG database and the inbuilt KEGG pathway annotation information will be used,
colorBy: Choose to color nodes either by community, robustZ or pvalue. To color by robustZ or pvalue, a column must exist in the normalisedScores for the chosen parameter
communityMethod: A community Detection method supported by igraph. See details for all methods available.
foldGSname: logical. Should long gene-set names be folded into two lines
foldafter: The number of words after which gene-set names should be folded. Defaulted to 2
layout: The layout algorithm to apply. Accepted layouts are "fr", "dh", "gem", "graphopt", "kk", "lgl", "mds" and "sugiyama"
markCommunity: character A geom_mark_ method supported by ggforce to annotate sets of nodes belonging to the same community. Either NULL, ellipse, circle, hull, rect
markAlpha: Transparency of annotation areas. Default to 0.2
edgeAlpha: Transparency of edges. Default to 0.8
up_col: The color used to label activated gene-sets. Only applicable if colorBy is set to be "robustZ"
down_col: The color used to label inhibited gene-sets. Only applicable if colorBy is set to be "robustZ"
scale_edgeWidth: A numerical vector of length 2 to be provided to ggraph::scale_edge_width_continuous() for specifying the minimum and maximum edge widths after transformation. Defaulted to c(0.5, 3)
edgeLegend: logical Should edge weight legend be shown
scale_nodeSize: A numerical vector of length 2 to be provided to ggplot2::scale_size() for specifying the minimum and maximum node sizes after transformation. Defaulted to c(3,6)
nodeShape: The shape to use for nodes
color_lg_title: Title for the color legend
lb_size: Size of node text labels
lb_color: Color of node text labels
plotIsolated: logical.Should nodes not connected to any other nodes be plotted. Default to FALSE
...: Used to pass various potting parameters to ggforce::geom_mark_*()

Value

A ggplot2 object

Details

A community detection strategy specified by communityMethod will be applied to pathway-pathway network, and communities will be annotated with the pathway category that had the highest number of occurrence, denoting the main biological processes perturbed in that community.

At the moment, only categorisations of KEGG pathway were built into the package, so if the provided normalisedScores contains perturbation scores of pathways derived from other databases, annotation of communities will not be performed unless pathway information is provided through the gsAnnotation parameter. The categorisation information needs to be stored in a data.frame contain gs_name (gene-set names) and category (categorisation of the given pathways).

The accepted igraph layout algorithms are: "fr", "bipartite", "star", "tree", "circle", " Plotting parameters accepted by geom_mark_* could be passed to the function to adjust the annotation area or the annotation label. See ?ggforce::geom_mark_* for more details.

Examples

load(system.file("extdata", "gsTopology.rda", package = "sSNAPPY"))
load(system.file("extdata", "normalisedScores.rda", package = "sSNAPPY"))
#Subset the first 10 rows of the normalisedScores data.frame as an example
subset <- normalisedScores[1:15,]
# Color network plot nodes by the community they were assigned to and mark nodes belonging
# to the same community by ellipses
plot_community(subset, gsTopology, colorBy = "community",layout = "kk",
color_lg_title = "Community")


# Color network plot nodes by pathways' directions of changes and mark nodes belonging
# to the same community by ellipses
plot_community(subset, gsTopology, colorBy = "robustZ",layout = "kk",
color_lg_title = "Direction of pathway Perturbation")


# Plotting parameters accepted by `geom_mark_*` could be passed to the function
# to adjust the annotation area or the annotation label. See
# `?ggforce::geom_mark_*` for more details. For example, to change the linetype
# of the connector:
plot_community(subset, gsTopology, colorBy = "robustZ",layout = "kk",
color_lg_title = "Direction of pathway Perturbation", con.linetype = "dashed")


# To change the colour and fill of `geom_mark_*` annotation, use any
# `scale_fill_*` and/or `scale_color_*`
# functions supported by `ggplot2`. For example:
p <- plot_community(subset, gsTopology, colorBy = "robustZ",layout = "kk",
markCommunity = "rect",color_lg_title = "Direction of pathway Perturbation")
p + ggplot2::scale_color_ordinal() + ggplot2::scale_fill_ordinal()