venndir_legender: Add optional legend to venndir figures (developmental)
In jmw86069/venndir: Directional Venn diagrams

venndir_legender

R Documentation

Add optional legend to venndir figures (developmental)

Description

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(
  setlist = NULL,
  x = "bottomleft",
  venndir_out = 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 = "#FFFFFF",
  header_border = "#FFFFFF",
  lwd = 1,
  x_inset = grid::unit(2, "lines"),
  y_inset = grid::unit(2, "lines"),
  font_cex = 1,
  poly_alpha = 0.8,
  table_theme = NULL,
  draw_legend = TRUE,
  alias = NULL,
  labels = NULL,
  verbose = FALSE,
  ...
)

Arguments

`setlist`	`list` used as input to `venndir()`, which is used only to derive the number of elements.
`x`	`character` string indicating the position of the legend, as passed to `graphics::legend()` when `style="base"`.
`venndir_out`	`list` object returned by `venndir()`, which is used to generate the legend counts. When supplied, the `set_colors` are also defined by this object.
`set_colors`	`character` optional vector of R colors, whose names should match `names(setlist)`. When not supplied, colors are inferred from `venndir_out`, 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.
`verbose`	`logical` indicating whether to print verbose output.
`...`	additional arguments are passed to subsequent functions.

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, so there is consistent alignment of labels that end in ":" with the numerical value. This adjustment would only affect multi-line labels.

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.

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_out=vo,
   x="bottomleft")

# test multi-line labels
names(setlist) <- c("Group A-<br>Group B",
   "Group B-<br>\nGroup C",
   "Dex_KO-\nVeh_WT")
vo <- venndir(setlist,
   show_segments=FALSE)
venndir_legender(setlist=setlist,
   venndir_out=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_out=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_out=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_out=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$vo@jps@polygons$border.lwd <- 0.1
vo124$vo@jps@polygons$innerborder.lwd <- 0.1
vor124 <- render_venndir(vo124$vo, draw_legend=FALSE)
venndir_legender(setlist=setlist, venndir_out=vo124)

jmw86069/venndir documentation built on June 15, 2024, 1:52 p.m.