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

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.

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.

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)

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