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.

venndir_legender(
  venndir_output = NULL,
  x = "bottomleft",
  setlist = NULL,
  set_colors = NULL,
  keep_newlines = FALSE,
  include_total = TRUE,
  box.lwd = 0,
  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",
  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 style="base".

setlist

list DEPRECATED and no longer necessary when venndir_output is supplied as a Venndir object, which already contains the setlist.

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().

keep_newlines

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

box.lwd

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

style

character string indicating the style of legend:

"base" uses graphics::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 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 style="grid" uses a 12 point font, so to adjust to a specific font size like 8 points, use: font_cex=8/12

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 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: 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 subsequent functions.

Value

data.frame with legend information is returned invisibly, unless using 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 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)

Add optional legend to venndir figures (developmental)

Arguments

Value

Details

See also

Examples