assemble_venndir_label: Assemble grid grobs into venndir labels

In jmw86069/venndir: Directional Venn diagrams

Assemble grid grobs into venndir labels

Description

Assemble grid grobs into venndir labels

Usage

assemble_venndir_label(
  x = NULL,
  y = NULL,
  just = c("center", "center"),
  signed_labels = NULL,
  count_labels = NULL,
  overlap_labels = NULL,
  template = c("wide", "tall"),
  fontfamily = "Helvetica",
  fontfamilies = list(signed = fontfamily, count = fontfamily, overlap = fontfamily),
  fontsizes = list(signed = 12, count = c(16, 12), overlap = 16),
  fontfaces = list(signed = "plain", count = c("plain", "bold.italic"), overlap = "bold"),
  fontcolors = list(signed = c("red3", "dodgerblue3", "grey55"), count = "black", overlap
    = "black"),
  label_borders = list(signed = grid::unit(1, "mm"), count = grid::unit(2, "mm"), overlap
    = grid::unit(3, "mm")),
  do_frame = TRUE,
  frame_r = grid::unit(0.1, "snpc"),
  frame_border = "#44444477",
  frame_fill = "#FDDD6644",
  text_grob_type = c("textGrob", "marquee", "richtext_grob"),
  debug = FALSE,
  verbose = FALSE,
  ...
)

Arguments

x, y	grid::unit, default NULL, indicating optional placement of labels. When defined, a viewport is defined for the label so it is rendered at this position.
just	character used only when x,y are defined, default "center" places the label at the center position; "right" will align the label so the right edge touches the x,y coordinate; c("bottom", "left") will align the label so the bottom-left corner touches the x,y coordinate.
signed_labels, count_labels, overlap_labels	character vector, default NULL, with one or more entries indicating the label should be included.
template	character default "wide" indicating the placement of counts and signed counts when both are defined: "wide" places signed counts to the right of counts. "tall" places signed counts below counts.
fontfamily	character default "Helvetica" used as convenient default for fontfamilies.
fontfamilies, fontsizes, fontfaces, fontcolors, label_borders	list with three named elements: "overlap", "count", "signed", providing one or more values for each type of label. When multiple values are provided for a label type, these values are recycled to the number of values. For example signed_labels=c("^ 21", "v 24") and fontcolors=list(signed=c("red", "blue", "grey")) would use c("red", "blue") for these two labels. The label_borders values refer to the border "buffer whitespace" between adjacent labels for each type, line by line. By default: 1mm between signed labels; 2mm between count labels; 3mm between overlap labels.
do_frame	logical default TRUE, indicating whether to define a frame around the grouped labels, returning grid::gTree with the frame and labels together as one "grob".
frame_r	grid::unit default 0.1snpc, indicating the corner radius when do_frame=TRUE, causing it to use grid::roundrectGrob() instead of grid::rectGrob(). Note the default is proportional to the plot coordinates, not the font size.
frame_border, frame_fill	character R colors used when do_frame=TRUE for the frame border, and color fill, respectively. Default is black border, cream/beige fill.
text_grob_type	character default "textGrob" indicating the type of text grob to use for labels. In future, this choice should be substantially improved, but for now it is user choice. "textGrob" uses grid::textGrob() - solid all-around, however it does not support markdown. "marquee" uses marquee::marquee_grob() - best overall: Supports markdown, and fallback glyph use so up/down arrows are displayed even for fonts that do not include them. Not compatible with MacOS and R-4.4.1 or older, so it will revert to "textGrob" in that specific scenario. "richtext_grob" uses gridtext::richtext_grob() - solid alternative for markdown support, however some graphics devices show inconsistent spacing between words.
debug	character default FALSE, indicating whether to run one of the debug modes used for testing: "overlap" will display the label at the center of the plot. "groblist" will return a list of grobs: signed_grobs, count_grobs, overlap_grobs. "list" will return a list of grobs as "groblist", then the overlap_frame which contains the gTree or gtable final grob.
verbose	logical indicating whether to print verbose output.
...	additional arguments are ignored.

Details

Grobs are defined by signed_labels, count_labels, and overlap_labels, or when any argument is NULL the label is skipped. The labels are assembled with the following rules:

• For each of the labels, when multiple values are provided, they are stacked on top of each other.

  • For signed_labels, they are left-justified when template="wide", otherwise they and all other labels are center-justified.

• When both count_labels and signed_labels are defined, they are combined according to template:

  • template="wide": combines count_labels on the left, and signed_labels on the right. They are center/middle-justified relative to each other, in terms of height.

  • template="tall": combines count_labels on the top, and signed_labels on the bottom.

• The combined labels of count_labels and/or signed_labels are arranged center-justified underneath overlap_labels, when overlap_labels is defined.

• For each label, the font settings are applied in order, or recycled to the vector length. For example if signed_labels contains three values, then fontsizes$signed is recycled to length 3, and applied to each label in order.

  • fontsizes: applies to each label in order

  • fontfamilies: by default uses fontfamily for all labels, but permits any label to use a custom font

  • fontfaces: applies fontface to each label in order, with recognized values: "plain", "bold", "italic", "bold.italic"

  • fontcolors: applies font color to each label in order

Examples

pdf.options(encoding="ISOLatin1.enc")
vl <- assemble_venndir_label(
   signed_labels=c("\u2191\u2191 15",
      "\u2193\u2193 23"),
   debug="overlap")

pdf.options(encoding="ISOLatin2.enc")
vl <- assemble_venndir_label(
   overlap_labels=c("\u2191\u2191 15",
      "\u2193\u2193 23")[1],
   debug="overlap")
   
vl2 <- assemble_venndir_label(
   signed_labels=c("\u2191\u2191 15",
      "\u2193\u2193 23"),
   count_labels=c("38"),
   debug="overlap")

vl3 <- assemble_venndir_label(
   signed_labels=c("\u2191\u2191 15",
      "\u2193\u2193 23"),
   count_labels=c("38"),
   overlap_labels="Set Name Goes Here",
   debug="overlap")

vl4 <- assemble_venndir_label(template="wide",
   signed_labels=c("\u2191\u2191 15",
      "\u2193\u2193 23"),
   count_labels=c("38", "12%"),
   overlap_labels="Set Name Goes Here",
   debug="overlap")

vl5 <- assemble_venndir_label(
   signed_labels=c("\u2191\u2191 15",
      "\u2191\u2193 8",
      "\u2193\u2193 23"),
   fontcolors=list(signed=c("red3", "darkorchid", "dodgerblue3")),
   count_labels=c("46", "12%"),
   overlap_labels="Set Name Goes Here",
   debug="overlap")

vl6 <- assemble_venndir_label(
   signed_labels=c("\u2191\u2191 15",
      "\u2193\u2193 23"),
   #count_labels=c("38", "12%"),
   overlap_labels="Set Name Goes Here",
   debug="overlap")

# example preparing multiple labels, one at a time
vlxy1 <- assemble_venndir_label(fontfamily="Times",
   just="right",
   x=grid::unit(0.25, "snpc"), grid::unit(0.5, "snpc"),
   count_labels=c("138"),
   signed_labels=c("\u2191\u2191 15",
      "\u2193\u2193 23"))
vlxy2 <- assemble_venndir_label(template="wide",
   just=c("right", "top"),
   x=grid::unit(0.25, "snpc"), grid::unit(0.25, "snpc"),
   count_labels=c("101", "24%"),
   signed_labels=c("\u2191\u2191 27",
      "\u2193\u2193 74"))

# each label can be drawn individually, or combined into gList (below)
new_gtree <- grid::gTree(children=grid::gList(
   vlxy1, vlxy2))
grid::grid.newpage();
grid::grid.draw(new_gtree);
grid::grid.points(x=grid::unit(c(0.25, 0.25), "snpc"),
   y=grid::unit(c(0.50, 0.25), "snpc"),
   pch=3,
   gp=grid::gpar(cex=0.8, lwd=2, col="darkorange"));

pdf.options(encoding="ISOLatin1.enc")

jmw86069/venndir documentation built on Dec. 14, 2024, 2:36 p.m.