Apply Cnet border color by directionality

Source: R/jamenrich-apply-cnet-direction.R

Apply Cnet border color by directionality

apply_cnet_direction(
  cnet,
  hitim = NULL,
  col = circlize::colorRamp2(breaks = c(-1, 0, 1), colors = c("blue", "grey80",
    "firebrick3")),
  col_l_max = 80,
  hide_solo_pie = TRUE,
  frame_blank = default_igraph_values()$vertex$frame.color,
  frame_lwd_blank = 0.2,
  border_lwd = 2,
  do_reorder = FALSE,
  ...
)

Arguments

cnet

igraph object with node attribute "pie.color" populated as a list of character vectors, named by enrichment. The enrichment names should match colnames(hitim).

hitim

numeric matrix with values centered at zero for no change, positive values +1 for up-regulation, and negative values -1 for down-regulation. The values are converted to color using color function col.

col

function that takes numeric input and assigns a color. The default assigns red for positive values, blue for negative values, and white for zero, using colorjam::col_div_xf(1.2).

col_l_max

numeric maximum HCL Lightness permitted for output colors, for example because the middle color in "RdBu_r" is nearly white, it may be preferable to apply a darker grey color.

hide_solo_pie

logical indicating whether a single-color border should only be applied to "frame.color" and not to individual "pie.border" entries.

  • When hide_solo_pie=TRUE and all wedges (one or more) will have the same pie.border color, then pie.border is defined as NA, and instead the frame.color is assigned to this color. Both pie.lwd and frame.lwd will be assigned border_lwd, since pie.border is NA it will not be rendered, only the frame.color will be rendered.

  • When hide_solo_pie=FALSE each pie wedge border color is assigned to pie.border, frame.color will be assigned frame_blank, and frame.lwd will be assigned frame_lwd_blank which is useful for displaying a small outer frame for each node.

frame_blank

character string to define the color used for "frame.color" when colors are defined in "pie.border". In this case, the frame is drawn around the inner pie.border colors, and only serves to add visual clarity. The frame border can be blank (frame_blank="transparent") or can be a thinner line, controlled with frame_lwd_blank=0.2. By default, the default igraph vertex frame.color is used, defined by default_igraph_values()$vertex$frame.color.

frame_lwd_blank

numeric line width for nodes that have "blank" frame, which means the pie.border colors are defined. In this case the frame border can be invisible (frame_lwd_blank=0) or a very thin line (default frame_lwd_blank=0.2) to surround the inner borders drawn with pie.border.

border_lwd

numeric line width used whenever a node is matched with rownames(hitim). When the colors are applied to pie.color, the border is defined with pie.lwd. When colors are applied to frame.color, the border is defined with frame.lwd. (Soon to become frame.width.)

do_reorder

logical indicating whether to call reorder_igraph_nodes() on the resulting igraph, so that the border color can be used in the sort conditions. Note that when do_reorder=TRUE, other relevant arguments are passed through ... to reorder_igraph_nodes() such as:

  • colorV - which controls the expected order of colors, and should be supplied if known upfront.

  • sortAttributes - usually contains appropriate default values

  • nodeSortBy - usually contains appropriate default values

  • orderByAspect=TRUE - controls whether left-right and top-bottom order is affected by the aspect ratio of each nodeset.

...

additional arguments are passed to reorder_igraph_nodes() when do_reorder=TRUE.

Details

This function specifically requires the "pie.color" node attribute of the cnet object igraph is populated with a list of colors whose name is the enrichment, and matches colnames(hitim) of the supplied hit incidence matrix.

The node names V(cnet)$name also must match rownames(hitim), otherwise the "pie.border" and "coloredrect.border" is assigned its previous value. In that case "frame.color" retains its original value.

This function may be run multiple times with different hitim, for example using geneIMdirection and enrichIMdirection in two steps.

When there are multiple colors for a given node, they are populated in node attributes "pie.border" in list form. For these nodes, the attribute "frame.color" is set to NULL so it is not displayed on top of the pie wedge colors.

When there are no matching rownames(hitim), or all colors are identical, the "pie.border" is populated with NULL, so the pie wedges do not each show a color. Also for single-wedge pie nodes, this process avoids drawing a small line at the top of each node. Instead the attribute "frame.color" is populated with the one unique border color, so that only the outer border is colorized.