Render venndir output, Venndir generic plot()

Render venndir output, generic plot function for a Venndir object

Usage

render_venndir(
  venndir_output = NULL,
  expand_fraction = NULL,
  font_cex = 1,
  main = NULL,
  item_cex = NULL,
  item_cex_factor = 1,
  plot_warning = FALSE,
  show_labels = NULL,
  show_items = NULL,
  item_degrees = NULL,
  max_items = 100,
  show_zero = TRUE,
  show_segments = NULL,
  segment_buffer = NULL,
  label_preset = c("none"),
  label_style = c("custom", "basic", "fill", "shaded", "shaded_box", "lite", "lite_box"),
  fontfamily = NULL,
  inside_percent_threshold = 0,
  item_style = NULL,
  item_buffer = NULL,
  group_labels = TRUE,
  template = NULL,
  adjust_center = FALSE,
  draw_legend = NULL,
  legend_x = "bottomright",
  legend_font_cex = NULL,
  draw_footnotes = NULL,
  show_label = NA,
  display_counts = TRUE,
  do_newpage = TRUE,
  do_draw = TRUE,
  draw_buffer = FALSE,
  verbose = FALSE,
  debug = FALSE,
  ...
)

Arguments

venndir_output

Venndir output from venndir(), or list with element "vo" as a Venndir object.

expand_fraction

numeric value, default NULL to use automated settings. It defines the figure margin fraction on each side in order: bottom, left, top, right. The default settings:

When draw_legend=FALSE it uses c(0, 0, 0, 0).
When draw_legend=TRUE it uses c(0.18, 0, 0, 0), in order to help prevent the Venn diagram from overlapping the legend.
When expand_fraction is defined, it is used without any adjustment.

font_cex

numeric scalar to adjust font sizes.

main

character string used as a plot title, default NULL will render no title. When provided, it is rendered using gridtext::richtext_grob() which enables some Markdown-style formatting. The title is stored in venndir@metadata$main for persistence.

item_cex

numeric default NULL, used to define baseline font size (single value), or exact font cex values (multiple values).

When a single value is provided, each set of items is used to define a font scaling, based upon the relative area of the overlap polygon to the max item polygon area, and the number of items in each polygon. These values are multiplied by item_cex to produce the final adjustment. These values are multiplied by item_cex_factor.
When multiple values are provided with names, the names are matched with overlap names: venndir_output@label_df$overlap_set, and applied accordingly. Any missing values retain the pre-existing value by default.
When multiple values are provided without names, the length is matched to the number of polygons in venndir_output@jps@polygons with non-zero and non-NA venn_counts; or the number of unique polygons in venndir_output@jps@polygons$venn_name; or the number of unique overlaps in venndir_output@label_df$overlap_set. If a length match is found, those values are assigned to names(item_cex). There is no further adjustment by polygon area, nor number of labels. These values are multiplied by item_cex_factor.

item_cex_factor

numeric, default 1, used to adjust the item_cex values overall. It is intended to be a single value, and is multiplied by item_cex as it is defined for each set of items.

plot_warning

logical indicating whether to include a warning when one or more non-zero overlap counts cannot be displayed in the figure. Not yet re-implemented since version 0.0.30.900.

show_labels

character string to define the labels to display, and where they should be displayed. The definition uses a single letter to indicate each type of label to display, using UPPERCASE to display the label outside the Venn shape, and lowercase to display the label inside the Venn shape. The default "Ncs" displays _N_ame (outside), _c_ount (inside), and _s_igned count (inside).

The label types are defined below:

_N_ame: "n" or "N" - the set name, by default it is displayed.
_O_verlap: "o" or "O" - the overlap name, by default it is hidden, because these labels can be very long, also the overlap should be evident in the Venn diagram already.
_c_ount: "c" or "C" - overlap count, independent of the sign
_p_ercentage: "p" or "P" - overlap percentage, by default hidden, but available as an option
_s_igned count: "s" or "S" - the signed overlap count, tabulated based upon overlap_type ("each", "concordant", "agreement", etc/)
_i_tems: "i" only, by default hidden. When enabled, item labels defined by show_items are spread across the specific Venn overlap region.

show_items

character used to define the item label, only used when the show_label entry includes "i" which enables item display inside the Venn diagram.

"item": shows only the item labels
"sign": shows only the sign of each item
"sign items": shows the sign and item together (or "item sign" will show the item, then the sign).

item_degrees

numeric angle (default 0) in degrees used to adjust item label display.

max_items

numeric (default 3000) indicating the maximum number of item labels to display when enabled.

show_zero

logical (default FALSE) indicating whether empty overlaps are labeled with count zero 0. When show_zero=TRUE the count zero label is displayed, otherwise no count label is shown.

show_segments

logical (default TRUE) indicating whether to draw a line segment from the Venn region to any label positioned outside.

segment_buffer

numeric (default -0.1) indicating the depth inside each Venn region a line segment will be drawn, relevant only when show_segments=TRUE.

label_preset

character deprecated in favor of show_labels. This argument is passed to venndir_label_style().

label_style

character string indicating the style for labels. Label color is adjusted based upon the determined background color, determined based upon the label fill color, and either the device background color, or Venn overlap fill color. There are pre-defined label styles.

"basic" no background shading
"fill" an opaque colored background
"shaded" a partially transparent colored background
"lite" a partially transparent lite background
"box" adds a dark border around the label region

fontfamily

character string to define the fontfamily. Default is "sans" because it should get mapped to a supported font for each graphics device, and any missing glyphs such as the Unicode upArrow and downArrow should be substituted with a suitable font with those glyphs. The fontfamily must match a font 'family' recognized by systemfonts. Use subset_systemfonts() to review values in column 'family', or systemfonts::font_info() to inspect possible font substitutions based upon weight, style, or other typography. These substitutions can be controlled in advanced, see systemfonts::font_fallback() and related functions to define substitutions upfront as needed.

In some circumstances, either the font or substitution is not compatible with PDF output, which tends to produce blank labels, presumably when the font encoded in the PDF is not available to the PDF viewer. You may check grDevices::pdfFonts() for more information. A potential workaround is to embed the glyphs or fonts using grDevices::embedGlyphs() or grDevices::embedFonts().

The ragg devices, and svglite device, have the best systemfonts support. RStudio works best with ragg output, which can be set with RStudio Options->General->Graphics then set 'Backend' to use 'AGG'. For ragg, try ragg::agg_png(), ragg::agg_tiff(), ragg::agg_jpeg(). For PDF, try cairo_pdf() or Cairo::CairoPDF().

The extreme fallback is to set unicode=FALSE, thereby avoiding Unicode arrows. Further, use fontfaces and set all values to 'plain' to avoid using bold fonts.

inside_percent_threshold

numeric (default 0) indicating the percent area that a Venn overlap region must contain in order for the count label to be displayed inside the region, otherwise the label is displayed outside the region. Values are expected to range from 0 to 100.

item_style

character string (default "text") indicating the style to display item labels when they are enabled.

"default" detects whether item labels contain "<br>" for newlines, and uses "gridtext" if that is the case, otherwise it uses "text" which is markedly faster.
"text" option is substantially faster, but does not allow markdown.
"gridtext": substantially slower for a large number of labels, but enables use of limited markdown by calling gridtext::richtext_grob(). Mostly useful for venn_meme().

item_buffer

numeric value (default -0.15) indicating the buffer adjustment applied to Venn overlap regions before arranging item labels. Passed to label_fill_JamPolygon() via render_venndir(). Negative values are recommended, so they shrink the region.

group_labels

logical (default TRUE) indicating whether to group label components together, therefore drawing fill and border around the group instead of each component. In most cases this setting should be TRUE.

template

character (default "wide") describing the default layout for counts and signed counts. The value is stored in venndir@metadata$template for persistence.

"wide" - main counts on the left, right-justified; signed counts on the right, left-justified.
"tall" - main counts, center-justified; signed counts below main counts, center-justified.

adjust_center

logical (default TRUE) used when labels are grouped, whether the group should be re-centered on the target point. Try adjust_center=FALSE if wide label groups are adjusted so that the count label is too far left.

draw_legend

logical (default NULL) indicating whether to draw a legend, calling venndir_legender(). When NULL it uses metadata(venndir_output)$draw_legend when defined, otherwise defaults to TRUE.

legend_x

character passed to venndir_legender() to customize the position of the legend.

legend_font_cex

numeric scalar to adjust the legend font size.

draw_footnotes

logical (default NULL) indicating whether to draw footnotes if they exist in the 'metadata' slot, calling render_venndir_footnotes().

do_newpage

logical (default TRUE) indicating whether to call grid::grid.newpage(). This option allows the figure to be rendered inside an active display device, or active grid::viewport. Note: When do_draw=FALSE, it also forces do_newpage=FALSE.

do_draw

logical indicating whether to call grid::grid.draw(). The grid graphical objects are returned in attributes: "gtree", "grob_list", "viewport", and can be drawn separately.

verbose

logical indicating whether to print verbose output.

debug

numeric optional internal debug.

...

additional arguments are passed to internal functions.

Value

Venndir object with attributes that contain underlying grid graphical objects (grobs):

"gtree": a grid::gTree object suitable for drawing with grid::grid.draw(attr(vo, "gtre"))
"grob_list": a list of grid object components used to build the complete diagram, they can be plotted individually, or assembled with do.call(grid::gList, grob_list). The grid::gList can be assembled into a gTree with: grid::grobTree(gList=do.call(grid::gList, grob_list)
"viewport": the grid::viewport that holds important context for the graphical objects, specifically the use of coordinate grid::unit measure "snpc", which maintains a fixed aspect ratio.

Details

About fonts and unicode symbols

R handles unicode symbols for each graphics device somewhat independently. Creating a PNG uses a different set of fonts than creating a PDF. Not all fonts used for PNG are compatible with PDF, and vice versa. (It is not solely an R problem.)

For the most part, users should not have to care about these details...

How this affects venndir:

Not every font registered in R supports extended unicode characters upArrow and downArrow, which causes it to draw blank boxes like []. The quick options:

Try a different fontfamily that may support the characters of interest.
Try a different grob type, see text_grob_type="marquee" below.
Install extrafont, which may be useful for installing consistent fonts to be used with PNG and PDF output formats.

Additional custom options

Several options are passed through ... (ellipses) to internal functions, documented below:

'L_threshold' is passed to make_color_contrast() to control the Luminance at which text is either dark or light. If dark text is shown on a dark background, set L_threshold=55 or below the default 65.
'text_grob_type' is passed to assemble_venndir_labels() to control the type of grid graphical object (grob).
- text_grob_type="marquee" (default) uses marquee::marquee_grob(). Its rendering of Unicode is outstanding, and is the future of R font rendering. It is not 100% compatible with all device outputs. Its main feature is using systemfonts to substitute missing glyphs to use another font, for example it always finds Unicode upArrow/downArrow and other Unicode symbols. It also handles CommonMark markdown, images, bullets, but not HTML.
- text_grob_type="textGrob" uses grid::textGrob(), which is the grid default. It does not handle markdown syntax, and no special handling of Unicode characters. It is the fastest rendering option.
- text_grob_type="richtext_grob" uses gridtext::richtext_grob(), which requires the gridtext package. This approach will be removed, and is kept as a fallback option until marquee is more fully tested. It recognizes markdown, and some limited HTML.
'fontfamilies' is passed to assemble_venndir_label(), as a list with three named elements: "overlap", "count", "signed"
- It allows a custom font to be used for each type of label. It may be useful to use a light font or narrow font for signed labels, for example.
- The custom font is also recognized by venndir_legender() for consistency, for example a custom count font is used for count labels in the legend.
outerborder,outerborder.lwd,innerborder,innerborder.lwd, border,border.lwd
- These arguments are passed to plot.JamPolygon() and override internal values when defined. They can produce interesting effects.
- The innerborder is drawn only on the inside edge of each polygon.
- The outerborder is drawn only on the outside edge of each polygon.
- The border is drawn on the border edge itself - and for Venndir objects by default is typically not drawn.
- Use white borders: outerborder=NA, innerborder="white"
- Use wide internal border, thin white line: outerborder=NA, innerborder.lwd=4, border="white", border.lwd=1