Add optional legend to venndir figures (developmental)

Add optional legend to venndir figures (developmental). This function is being evaluated and developed, and will very likely change again in an upcoming release.

Usage

venndir_legender(
  venndir_output = NULL,
  x = "bottomleft",
  setlist = NULL,
  set_colors = NULL,
  unicode = TRUE,
  sign_count_delim = NULL,
  keep_newlines = FALSE,
  legend_total = TRUE,
  legend_percentage = NULL,
  legend_signed = NULL,
  combine_signed = TRUE,
  combine_size = TRUE,
  legend_color_style = c("fill", "border"),
  box.lwd = 0,
  legend_style = c("grid", "data.frame"),
  item_type = "",
  header_color = "#000000",
  header_bg = "#FFFFFF00",
  header_border = "#FFFFFF00",
  lwd = 1,
  x_inset = grid::unit(2, "lines"),
  y_inset = grid::unit(2, "lines"),
  font_cex = 1,
  fontfamily = "Arial",
  fontfamilies = list(signed = fontfamily, count = fontfamily, overlap = fontfamily),
  poly_alpha = 0.8,
  table_theme = NULL,
  draw_legend = TRUE,
  alias = NULL,
  labels = NULL,
  legend_padding = 3,
  set_suffix = "",
  vp = NULL,
  verbose = FALSE,
  ...
)

Arguments

venndir_output

Venndir object returned by venndir(), which is used to generate the legend counts. When supplied, the set_colors are also defined by this object.

x

character string indicating the position of the legend, as passed to graphics::legend() when legend_style="base". Not relevant when legend_style="data.frame".

setlist

list alternative when venndir_output is not supplied as a Venndir object. Used internally by textvenn().

set_colors

character optional vector of R colors, whose names should match names(setlist). When not supplied, colors are inferred from venndir_output, and when that is not supplied, colors are defined using colorjam::rainbowJam().

unicode

logical default TRUE, whether to use unicode arrows for signed counts, used when legend_signed=TRUE. This argument is passed to curate_venn_labels().

keep_newlines

logical indicating whether to keep newlines (line breaks) in the set labels used in the Venn legend.

legend_total

logical default TRUE, whether to include the total unique items in the legend. When FALSE it also sets legend_percentage=FALSE.

legend_percentage

logical default NULL, whether to include the percentage of total items represented in each set. This option is only used when legend_total=TRUE.

When set to NULL it will display percentage only when present as a text label, as when show_labels include "p" or "P".

legend_signed

logical default FALSE, whether to include signed counts in the legend.

When set to NULL it displays signed counts only when available, which requires: overlap_type is not "overlap", and legend_df column "type" has entries with "sign".

combine_signed

logical default TRUE, whether to combine multiple signed counts into one column (TRUE), or keep separate columns (FALSE). Somewhat experimental. This option is only used when signed counts are included.

combine_size

logical default TRUE, whether to combine counts in the "Size" column with signed counts. When TRUE, this option also left-aligns the "Size" column.

legend_color_style

character string to customize how colors are used, c("fill", "border") are default:

"fill": will use the Venn fill color
"border": will use the Venn border color
"nofill": will remove the Venn fill color
"noborder": will remove the Venn border color
"greyfill": will use "F4F4f4" grey fill color, matching the Total.
"greyborder": will use "#999999" border color, matching the Total.
"blackborder": will use "#000000" border color, matching the Total.

box.lwd

numeric used to define the box line width, as passed to graphics::legend() when legend_style="base".

legend_style

character string indicating the style of legend:

"grid" uses gridExtra::grid.table()
"data.frame" only returns the venndir legend data.frame.

item_type

character string used as a suffix to the counts displayed in the legend. Use item_type="" or item_type=NULL to hide this suffix.

header_color, header_bg, header_border

character R colors to define colors for particular elements:

header_color defines the text color of the column headers. To hide the column header, currently use header_color="white", matching whatever color is used for header_bg.
header_bg defines the background fill color for the column headers.
header_border defines the border color for the header, which is also applied to all cells in the table. Note that the line is drawn with line width lwd.

lwd

numeric value for line width used for the cell border in the legend table, when legend_style="grid".

x_inset, y_inset

grid::unit object that defines the inset distance away from each plot edge, along the x-axis and y-axis, respectively. For example x_inset=grid::unit(2, "lines") will place the legend table 2 character lines (which are defined by line height for typical character size) away from the left or right edge of the plot. Any valid grid::unit can be used, however using "lines" units provides some consistent width rather than using "npc" in terms of fraction of overall plot width or height.

font_cex

numeric adjustment to default font sizes. The default font size with legend_style="grid" uses a 12 point font, so to adjust to a specific font size like 8 points, use: font_cex=8/12

fontfamily

character used as the default font for all labels, and is used in fontfamilies by default. However fontfamilies takes priority when defined.

fontfamilies

list with named elements: "overlap", "count", "signed", to allow a custom font for each element of the legend. This argument is also used by assemble_venndir_label().

The "overlap" font is used for set names, and column headers. Column headers are currently always bold.
Note that "overlap" is used for "Size" and "Percent" columns, and when combine_size=TRUE the signed counts are in the same cell and therefore use the same font.
When combine_size=FALSE the signed counts use "signed".

table_theme

list of theme parameters as described in gridExtra::tableGrob(), and gridExtra::ttheme_default(). When supplied, the font_cex argument is ignored. The list components include:

base_size - default font size
base_colour - default font color
base_family - default font family
parse - logical whether to parse plotmath expressions
padding - grid::unit() for horizontal and vertical padding within each cell

draw_legend

logical indicating whether to draw the resulting legend. Because this function is in development, the legend_style="grid" seems to be preferred, however it may be useful to return the grob object for manipulation before rendering inside the active plot. In that case, use arguments: legend_style="grid", draw_legend=FALSE.

alias

character vector with optional set aliases, experimental feature to allow referring to entries in setlist by shorter aliases. Note that names(alias) must also match names(setlist). Note: The argument labels is more likely to be useful, since the original call to venndir() should use setlist with aliased names, and expanded labels would be provided separately.

labels

character vector with optional set labels, experimental feature to supply a longer label associated with each entry in setlist. Note that names(labels) must also match names(setlist). Note: The most useful workflow would be to assign short aliases to names(setlist) when calling venndir(), then use the original long label names as argument labels here.

legend_padding

numeric or grid::unit used to define padding for each table cell. This value is only used when table_theme is not provided.

set_suffix

character string (default "") used as optional suffix, and previously used ":" but was changed to "".

verbose

logical indicating whether to print verbose output.

...

additional arguments are passed to internal functions. Notably curate_venn_labels() may accept the curate_df argument, to allow custom labeling.

Value

data.frame with legend information is returned invisibly, unless using legend_style="grid", draw_legend=FALSE in which case the legend grob object is returned which can then be manipulated before rendering.

Details

Note this function is experimental and is under active development. The implementation and arguments may change in future.

Limitations: Currently this function relies upon having the setlist used to produce the venndir() output, and the venndir() output. In future, the setlist could be derived from the venndir() output object directly. That step likely needs a new function.

When using arguments legend_style="grid" and draw_legend=FALSE the grid grob object is returned, so that it can be manipulated as needed before rendering. Note that in this case, the viewport will have already been defined and stored into legend_grob$vp with x position legend_grob$vp$x and y position legend_grob$vp$y. Total legend width is: sum(legend_grob$widths), and total legend height is: sum(legend_grob$heights).

Todo:

Consider bottom-justifying text in each cell, left-justifying text labels, and right-justifying numeric values.

Examples

setlist <- make_venn_test(100, 3, do_signed=TRUE);
# by default the legend is shown
vo <- venndir(setlist)


# move to different corner
vo <- venndir(setlist, legend_x="bottomleft")


# turn off the default legend
vo <- venndir(setlist, draw_legend=FALSE)
venndir_legender(setlist=setlist,
   venndir_output=vo,
   x="bottomleft")


# test multi-line labels
names(setlist) <- c("Group B-<br>Group A",
   "Group C-<br>\nGroup B",
   "Group_C-<br>\nGroupA")
vo <- venndir(setlist,
   draw_legend=FALSE,
   show_segments=FALSE)
venndir_legender(setlist=setlist,
   venndir_output=vo,
   x="bottomleft")


# Same as above, showing how to render the legend_grob.
# This method also "hides" the column headers.
vo <- venndir(setlist,
   show_segments=FALSE,
   draw_legend=FALSE,
   font_cex=c(1, 1, 0.5, 0.5))
legend_grob <- venndir_legender(setlist=setlist,
   venndir_output=vo,
   draw_legend=FALSE,
   header_color="white",
   x="bottomleft")
grid::grid.draw(legend_grob)


# custom grid table theme
vo <- venndir(setlist,
   show_segments=FALSE,
   draw_legend=FALSE)
legend_grob <- venndir_legender(setlist=setlist,
   venndir_output=vo,
   headers=FALSE,
   x="bottomright",
   table_theme=gridExtra::ttheme_default(base_size=11,
      base_family="sans",
      padding=grid::unit(c(2, 2), "mm")))


# optional expanded labels, and subset setlist
setlist <- make_venn_test(100, 5, do_signed=TRUE);
vo <- venndir(setlist,
   sets=c(4, 1, 2),
   show_segments=FALSE,
   draw_legend=FALSE)
venndir_legender(venndir_output=vo,
   font_cex=0.8,
   setlist=setlist,
   labels=jamba::nameVector(
      paste0("This is set ", LETTERS[1:5]),
      names(setlist)))


# Venn with no border, and more transparent colors
vo124 <- venndir(setlist, sets=c(1, 2, 4), poly_alpha=0.4, do_plot=FALSE)
vo124@jps@polygons$border.lwd <- 0.1
vo124@jps@polygons$innerborder.lwd <- 0.1
vor124 <- render_venndir(vo124, draw_legend=FALSE)
venndir_legender(setlist=setlist, venndir_output=vo124)