Skip to contents

Convert MultiEnrichment incidence matrix to Cnet plot

Source: R/jamenrich-mem2cnet.R
mem2cnet.Rd

Convert MultiEnrichment incidence matrix to Cnet plot

Usage

mem2cnet(
  memIM,
  categoryShape = c("pie", "coloredrectangle", "circle", "ellipse"),
  geneShape = c("pie", "coloredrectangle", "circle", "ellipse"),
  forceColors = FALSE,
  categoryColor = "#E5C494",
  geneColor = "#B3B3B3",
  categoryLabelColor = "darkblue",
  geneLabelColor = "grey25",
  categorySize = 12,
  geneSize = 6,
  categoryCex = 1,
  geneCex = 0.8,
  frame_darkFactor = NULL,
  geneIM = NULL,
  geneIMcolors = NULL,
  geneIMdirection = NULL,
  enrichIM = NULL,
  enrichIMcolors = NULL,
  enrichIMdirection = NULL,
  coloredrect_nrow = 1,
  coloredrect_ncol = NULL,
  coloredrect_byrow = TRUE,
  colorV = NULL,
  direction_col_fn = NULL,
  direction_cutoff = NULL,
  direction_max = 2,
  gene_direction_cutoff = 0,
  gene_direction_max = 1.2,
  gene_direction_col_fn = NULL,
  hide_solo_pie = TRUE,
  remove_blanks = TRUE,
  remove_singlet_genes = TRUE,
  do_reorder = TRUE,
  spread_labels = FALSE,
  repulse = 3.5,
  verbose = FALSE,
  ...
)

memIM2cnet(
  memIM,
  categoryShape = c("pie", "coloredrectangle", "circle", "ellipse"),
  geneShape = c("pie", "coloredrectangle", "circle", "ellipse"),
  forceColors = FALSE,
  categoryColor = "#E5C494",
  geneColor = "#B3B3B3",
  categoryLabelColor = "darkblue",
  geneLabelColor = "grey25",
  categorySize = 12,
  geneSize = 6,
  categoryCex = 1,
  geneCex = 0.8,
  frame_darkFactor = NULL,
  geneIM = NULL,
  geneIMcolors = NULL,
  geneIMdirection = NULL,
  enrichIM = NULL,
  enrichIMcolors = NULL,
  enrichIMdirection = NULL,
  coloredrect_nrow = 1,
  coloredrect_ncol = NULL,
  coloredrect_byrow = TRUE,
  colorV = NULL,
  direction_col_fn = NULL,
  direction_cutoff = NULL,
  direction_max = 2,
  gene_direction_cutoff = 0,
  gene_direction_max = 1.2,
  gene_direction_col_fn = NULL,
  hide_solo_pie = TRUE,
  remove_blanks = TRUE,
  remove_singlet_genes = TRUE,
  do_reorder = TRUE,
  spread_labels = FALSE,
  repulse = 3.5,
  verbose = FALSE,
  ...
)

Arguments

memIM

one of the following:

  • Mem S4 object, preferred. In this case, the arguments regarding 'geneIM' and 'enrichIM' data are taken directly from 'mem'.

  • legacy list mem object, for backward compatibility,

  • numeric matrix in the form of a memIM gene-pathway incidence matrix. In this case, other arguments involving geneIM and enrichIM matrices are required for correct behavior of this function. When mem format is supplied, relevant arguments which are empty will use corresponding data from mem, for example geneIM, geneIMcolors, enrichIM, enrichIMcolors.

categoryShape, geneShape

character string with node shape, default 'pie' uses pie nodes. Note that 'pie' shapes with only one segment are converted to 'circle' for convenience. When using jam_igraph() to plot, it already treats single-segment pie nodes as circle anyway, and vectorizes pie node plotting to make the overall rendering time substantially faster.

forceColors

logical default FALSE, whether to force node colors to use categoryColor and geneColor arguments, otherwise colors are defined using enrichIMcolors() and geneIMcolors(), respectively. Enabling this option will skip all pie and directional styling.

categoryColor, geneColor

character R color for default node colors, used when geneIMcolors,enrichIMcolors is not supplied, respectively.

categoryLabelColor, geneLabelColor

character R color used as default node label color.

categorySize, geneSize

numeric default node size.

categoryCex, geneCex

numeric adjustment to default node label font size.

frame_darkFactor

numeric passed to jamba::makeColorDarker() so the frame color is slightly darker than the node fill color.

geneIM, geneIMcolors, geneIMdirection, enrichIM, enrichIMcolors, enrichIMdirection

matrix data used only when the input 'mem' is not an Mem or legacy list mem object which already contains these data. When input 'mem' is supplied as a matrix, these value enable this function to operate on nearly any custom data.

  • geneIMcolors is used to define gene (row) node colors

  • enrichIMcolors is used to define set (column) node colors

  • geneIMdirection,enrichIMdirection is used to define optional border colors defined by the direction, where -1 is down, 0 is no change, and +1 is up. Use direction_col_fn to define a custom color function, however the default uses the reversed "RdBu" Brewer color ramp with blue (down), white (no change) and red (up).

coloredrect_nrow, coloredrect_ncol, coloredrect_byrow

arguments used when geneShape="coloredrectangle", to define layout and placement of colors across columns in geneIMcolors. By default, one row of colors is used.

colorV

character optional vector of R colors, taken from 'mem' for Mem or legacy list mem objects. When supplied, it should be a vector named to match colnames(enrichIM). When defined, these colors override enrichIMcolors.

direction_col_fn

function used to colorize 'Set' node borders via enrichIMdirection. The default uses colorjam::col_div_xf() which applies reverse Brewer "RdBu" for blue (down), white (no change), and red (up) with maximum color at 2.0. When not supplied, direction_cutoff and direction_max are used with colorjam::col_div_xf().

direction_cutoff

numeric default is taken from memIM when provided as Mem, typical default is 1.0 to require directional z-score at least 1.0 in order to apply any directional border color.

direction_max

numeric default 2, the numeric value to apply maximum color from the color gradient function.

gene_direction_cutoff

numeric default 0, the minimum value in geneIMdirection to apply up/down color. Using 0 will colorize any non-zero color.

gene_direction_max

numeric default 1.2, the numeric value to apply maximum color from the color gradient function. Typical values are -1 and 1, so using 1.2 will apply nearly the maximum color.

gene_direction_col_fn

function used to colorize 'Gene' node borders via enrichIMdirection. The default uses colorjam::col_div_xf() which applies reverse Brewer "RdBu" for blue (down), white (no change), and red (up) with maximum color at 1.2. *When not supplied, gene_direction_cutoff and gene_direction_max are used with colorjam::col_div_xf().

hide_solo_pie

logical default TRUE, passed to apply_cnet_direction() to determine whether to display border only as one outer frame color when all colors are identical. When FALSE, all pie wedges are individually colored.

remove_blanks

logical default TRUE, whether to remove blank color subsections from each node, using removeIgraphBlanks(). This argument is useful for 'pie', 'jampie', or 'coloredrectangle' node shapes, so they will only indicate the relevant color.

remove_singlet_genes

logical default TRUE, whether to remove singlet genes, which are genes (rows) not represented in any pathway gene sets (columns).

do_reorder

logical default TRUE used to re-order nodes in "equivalent positions" by border color, color, etc. by calling reorder_igraph_nodes(). Equivalent nodes are common in Cnet (bipartite) networks, for example numerous 'Gene' nodes may be connected to the same 2 pathway 'Set' nodes, and therefore the node positions are interchangeable. Sorting by node attributes (notably color, then alphabetically by label) helps visual review.

spread_labels

logical default FALSE, whether to spread node labels away from incoming edges, also adding label distance via vertex attribute 'label.dist'. This step calls spread_igraph_labels(), and can be customized further by passing arguments through '...' ellipses.

repulse

numeric value passed to layout_with_qfr() when either do_reorder or spread_labels is TRUE. Otherwise there is no layout applied. The 'repulse' value effectively defines node spacing, usually with values between 3 and 4, which 3 giving broad spacing, and 4 giving very close spacing of nodes in equivalent network positions, and broad spacing otherwise. Higher values tend to "clump" nodes closer together.

verbose

logical indicating whether to print verbose output.

...

additional arguments are passed to downstream functions:

Value

igraph object with Concept network data, containing pathways connected to genes. Each node has attribute "nodeType" of either "Set" or "Gene".

Details

This function takes Mem S4 object, or legacy list mem data, or even bare matrix data, and produces a Concept network (Cnet) in the form of an igraph object.

Cnet network data are a form of bipartite graph, where every node is either 'Gene' or 'Set', and where nodes are only connected across 'Gene' <--> 'Set'. See igraph::graph_from_biadjacency_matrix(). A Cnet plot has particularly useful characteristic that Set (pathway) nodes tend to be connected to very many Gene nodes, creating an imbalance which is useful when defining a visual layout.

A vertex attribute 'nodeType' stores the type of node: 'Gene' or 'Set'.

The memIM defines the network, and non-zero value constitutes an edge (connection) between row (Gene) and column (Set).

Other data are associated with nodes when available.

  1. geneIM, geneIMcolors, geneIMdirection: define 'Gene' node fill and border colors.

  2. enrichIM, enrichIMcolors, enrichIMdirection: define 'Set' node fill and border colors.

Everything else helps customize the output, and can be used as-is.

Generic Cnet

The memIM can be supplied as an matrix of integer values, with no other data supplied, and this is sufficient to create a Cnet plot. Therefore, any incidence matrix can be used to create a network.

If no other data are provided, nodes are colored by categoryColor (Set) and geneColor (Gene), and shapes defined by categoryShape and geneShape.

Be aware that remove_singlet_genes=TRUE default will hide rows (Genes) which have no connection to any columns (Sets). This default ensures that an incidence matrix can be subset for columns (Sets) of interest without also filtering rows.

However, columns (Sets) are not removed, because they typically are not empty in the most common workflows. Singlet columns, Set nodes with no connected Gene nodes, can be filtered by calling removeIgraphSinglets().

See also

Other jam Mem utilities: Mem-class, MemPlotFolio-class, fixSetLabels(), mem2emap()

Other jam igraph functions: communities2nodegroups(), drawEllipse(), edge_bundle_bipartite(), edge_bundle_nodegroups(), fixSetLabels(), flip_edges(), get_bipartite_nodeset(), highlight_edges_by_node(), igraph2pieGraph(), label_communities(), mem2emap(), nodegroups2communities(), rectifyPiegraph(), removeIgraphBlanks(), subsetCnetIgraph(), subset_igraph_components(), sync_igraph_communities()

Examples

use_sets <- c("eNOS Signaling",
   "Growth Hormone Signaling",
   "mTOR Signaling")
jam_igraph(mem2cnet(Memtest[, use_sets, ]),
   use_shadowText=TRUE)