Add legend to a Venndir figure

Usage

venndir_legender(
  venndir_output = NULL,
  setlist = NULL,
  x = "bottomright",
  set_colors = NULL,
  legend_style = c("grid", "data.frame"),
  unicode = TRUE,
  legend_headers = c(Set = "Set", Size = "Size", Percentage = "Percentage", Sign =
    "Sign"),
  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,
  item_type = "",
  header_color = "#000000",
  header_bg = "#FFFFFF00",
  header_border = "#FFFFFF00",
  lwd = 1,
  x_inset = grid::unit(0.5, "lines"),
  y_inset = grid::unit(0.5, "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 = 2,
  set_suffix = "",
  curate_df = NULL,
  vp = NULL,
  fg_fun = marquee_text_grob,
  verbose = FALSE,
  ...
)

Arguments

venndir_output

Venndir object, default NULL, or one of:

Venndir object, also used to define set_colors when applicable
list representing setlist
data.frame output from signed_overlaps()

setlist

list, default NULL, used when venndir_output is NULL

list representing setlist
data.frame with output from signed_overlaps(), with columns "sets", "overlap", "count". It may include "each" which is required to display signed counts with legend_signed=TRUE.

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

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

legend_style

character string, default "grid" with the legend style, with these options:

"grid" generates a grid grob using gridExtra::grid.table().
"data.frame" generates the legend data.frame.

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

legend_headers

character vector with headers to use, named by the default heading. To display no column header, set legend_headers=NULL or legend_headers=FALSE. Recognized names:

"Set" - the header for the set names, default "Set".
"Label" - when labels or legend_labels are defined, the header "Label" can be customized.
"Size" - the header for the set sizes, default "Size".
"Sign" - the header for the set signs, default "Sign".
"Percentage" - the header for the set size percentage overall, default "Percentage".

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 NULL, 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
"greyfill": will use "F4F4f4" grey fill color, matching the Total.
"noborder": will remove the Venn border color
"whiteborder": will use "#FFFFFF" border 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".

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, default 1, cell border line width used in the legend table, when legend_style="grid".

x_inset, y_inset

grid::unit, default 1 line each, used when legend_style="grid" to position the legend relative to x, useful when positioning the legend near the edge x="bottomleft".

The inset controls distance from the plot edge along the x- and y-axes. 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. Note that the metric is "plot edge", and the plot is fixed 1:1 aspect, so for wide plot devices a negative x_inset may be used to nudge the legend outside the typical plot boundary.

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 to allow a custom font for each element of the legend, consistent with usage by assemble_venndir_label().

"overlap": used for set labels and column headers, and column headers are currently always bold font.
"count": used for main counts in "Size", and percentage in "Percentage" when displayed.
"signed": used for signed counts, when shown and when combine_size=FALSE, otherwise the signed labels are combined with count labels and they re-use the same font as "count" above.

table_theme

list default NULL, optional theme 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, default TRUE, whether to draw the resulting legend. When FALSE the data is returned based upon legend_style, when legend_style="grid" it returns a grid grob, otherwise it returns data.frame.

alias

character, default NULL, optional set aliases, intended to add a new first column to the legend with these aliases. Useful to display a short label in the legend table, while also supplying a longer label via names(setlist) or labels. This argument differs from labels in that labels replaces the names(setlist) in the legend table with labels. However, alias adds a new column to the table as column 1.

labels

character default NULL, optional custom labels to display in place of names(setlist) in the legend table. Note: names(labels) must also match names(setlist). This argument differs from labels in that labels replaces the names(setlist) in the legend table with labels. However, alias adds a new column to the table as column 1.

legend_padding

numeric or grid::unit, default 5, padding for each table cell. This value is also adjusted by font_cex. 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 "".

curate_df

data.frame, default NULL will use the metadata of venndir_output to retrieve any custom curate_df already in use for the Venndir object.

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

Add a Venndir legend to the perimeter of an existing Venndir figure. Note this function it typically called from venndir() via render_venndir() when argument draw_legend=TRUE (default). By using draw_legend=FALSE the returned Venndir object can be used as input to venndir_legender() to draw the legend in a custom location, for example using the overall figure viewport instead of being limited to the Venndir viewport.

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

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")


# add alias column
vo <- venndir(setlist,
   legend_labels=setNames(paste0("Items detected in ", LETTERS[1:3]),
      names(setlist)),
   alias=setNames(LETTERS[1:3], names(setlist)))


# 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>\nGroup A")
vo <- venndir(setlist,
   draw_legend=FALSE,
   font_cex=1.3,
   fontfamily="Arial",
   expand_fraction=c(-0.1, 0.4, -0.1, 0.1),
   show_segments=FALSE)
venndir_legender(setlist=setlist,
   venndir_output=vo,
   font_cex=1.3,
   x="bottomleft")

   
# some common customizations
vo <- venndir(setlist,
   draw_legend=FALSE,
   expand_fraction=c(0.2, 0.2, 0.2, 0.2)*3,
   font_cex=0.7,
   fontfamily="Arial")
venndir_legender(vo,
   legend_headers=c(Set="Comparison",
      Size="Counts (Signed Counts)"),
   legend_color_style=c("nofill", "blackborder"),
   font_cex=0.8,
   x="bottomleft")
venndir_legender(vo,
   combine_size=FALSE,
   legend_headers=c(Set="Comparison",
      Size="Counts", Sign="(Signed Counts)"),
   legend_color_style=c("nofill", "blackborder"),
   font_cex=0.8,
   x="bottomright")
venndir_legender(vo,
   combine_size=FALSE,
   combine_sign=FALSE,
   legend_headers=c(Set="Comparison",
      Size="Counts", Sign="(Signed Counts)"),
   legend_color_style=c("nofill", "blackborder"),
   font_cex=0.8,
   x="topright")
venndir_legender(vo,
   legend_percent=TRUE,
   legend_headers=c(Set="Comparison",
   Percentage="Pct.",
      Size="Counts", Sign="(Signed Counts)"),
   legend_color_style=c("nofill", "blackborder"),
   font_cex=0.8,
   x="topleft")


# Example showing how to render the legend_grob
# which may offer some flexibility.
vo <- venndir(setlist,
   draw_legend=FALSE)
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=1,
   setlist=setlist,
   labels=jamba::nameVector(
      paste0("This is set ", LETTERS[1:5]),
      names(setlist)))