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")
#> ##  (21:56:12) 09Dec2024:   Doing debug='overlap' 


pdf.options(encoding="ISOLatin2.enc")
vl <- assemble_venndir_label(
   overlap_labels=c("\u2191\u2191 15",
      "\u2193\u2193 23")[1],
   debug="overlap")
#> ##  (21:56:12) 09Dec2024:   Doing debug='overlap' 

   
vl2 <- assemble_venndir_label(
   signed_labels=c("\u2191\u2191 15",
      "\u2193\u2193 23"),
   count_labels=c("38"),
   debug="overlap")
#> ##  (21:56:12) 09Dec2024:   Doing 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")
#> ##  (21:56:12) 09Dec2024:   Doing 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")
#> ##  (21:56:12) 09Dec2024:   Doing 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")
#> ##  (21:56:12) 09Dec2024:   Doing 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")
#> ##  (21:56:12) 09Dec2024:   Doing 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")