Render venndir output
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,
show_label = NA,
display_counts = TRUE,
do_newpage = TRUE,
do_draw = TRUE,
draw_buffer = FALSE,
verbose = FALSE,
debug = FALSE,
...
)
Arguments
- venndir_output
Venndir
output fromvenndir()
, orlist
with element"vo"
as aVenndir
object.- expand_fraction
numeric
value, defaultNULL
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 usesc(0, 0, 0, 0)
.When
draw_legend=TRUE
it usesc(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 usinggridtext::richtext_grob()
which enables some Markdown-style formatting. The title is stored invenndir@metadata$main
for persistence.- item_cex
numeric
default NULL, used to define baseline font size (single value), or exact fontcex
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 byitem_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 invenndir_output@jps@polygons$venn_name
; or the number of unique overlaps invenndir_output@label_df$overlap_set
. If a length match is found, those values are assigned tonames(item_cex)
. There is no further adjustment by polygon area, nor number of labels. These values are multiplied byitem_cex_factor
.
- item_cex_factor
numeric
, default 1, used to adjust theitem_cex
values overall. It is intended to be a single value, and is multiplied byitem_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 theshow_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 zero0
. Whenshow_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 whenshow_segments=TRUE
.- label_preset
character
deprecated in favor ofshow_labels
. This argument is passed tovenndir_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. Thefontfamily
must match a recognized font for the given output device, and this font must be capable of producing UTF-8 / Unicode characters, in order to print up arrow and down arrow. You may reviewsystemfonts::system_fonts()
for a listing of fonts recognized byragg
devices, which seems to have the best overall font capabilities. When it does not work, either useunicode=FALSE
, or check the output fromSys.getlocale()
to ensure the setting is capable of using UTF-8 (for example "C" may not be sufficient). Using the packageragg
appears to be more consistently successful for rasterized output than base R output, for example:ragg::agg_png()
,ragg::agg_tiff()
,ragg::agg_jpeg()
produce substantially higher quality output, and with more successful usage of system fonts, thanpng()
,tiff()
, andjpeg()
. Similarly, for PDF output, considercairo_pdf()
orCairo::CairoPDF()
instead of usingpdf()
.- 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 callinggridtext::richtext_grob()
. Mostly useful forvenn_meme()
.
- item_buffer
numeric
value (default -0.15) indicating the buffer adjustment applied to Venn overlap regions before arranging item labels. Passed tolabel_fill_JamPolygon()
viarender_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 invenndir@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. Tryadjust_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, callingvenndir_legender()
. WhenNULL
it usesmetadata(venndir_output)$draw_legend
when defined, otherwise defaults toTRUE
.- legend_x
character
passed tovenndir_legender()
to customize the position of the legend.- legend_font_cex
numeric
scalar to adjust the legend font size.- do_newpage
logical
(default TRUE) indicating whether to callgrid::grid.newpage()
. This option allows the figure to be rendered inside an active display device, or activegrid::viewport
. Note: Whendo_draw=FALSE
, it also forcesdo_newpage=FALSE
.- do_draw
logical
indicating whether to callgrid::grid.draw()
. Thegrid
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"
: agrid::gTree
object suitable for drawing withgrid::grid.draw(attr(vo, "gtre"))
"grob_list"
: alist
ofgrid
object components used to build the complete diagram, they can be plotted individually, or assembled withdo.call(grid::gList, grob_list)
. Thegrid::gList
can be assembled into agTree
with:grid::grobTree(gList=do.call(grid::gList, grob_list)
"viewport"
: thegrid::viewport
that holds important context for the graphical objects, specifically the use of coordinategrid::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 options
Several options are passed through ...
(ellipses) to internal
functions, documented below:
L_threshold
is passed tomake_color_contrast()
and controls the _L_uminance at which text is either dark or light.text_grob_type
is passed toassemble_venndir_labels()
and controls the textgrid
graphical object (grob) type used. Note that"marquee"
requires themarquee
package, which implicitly requires R-4.3 or newer, though somehow that is not a formal dependency. R-4.3 adds glyph rendering, which is required bymarquee
.text_grob_type="textGrob"
(default) usesgrid::textGrob()
which only handles text, and no markdown. It is also fastest.text_grob_type="richtext_grob"
usesgridtext::richtext_grob()
, and requires thegridtext
package. It handles a subset of markdown (bold, italics, but not bullets), and a subset of HTML markup such as inline CSS styles. It sometimes produces visual glitches, where whitespace between words can be inconsistent, otherwise it would have been the default.text_grob_type="marquee"
usesmarquee::marquee_grob()
, which requires themarquee
package. It may rarely cause a full R crash on MacOS, apparently due to font handling subsystems, otherwise it would have been the default. Its rendering of Unicode is outstanding, since it usessystemfonts
to substitute any missing glyphs per font, for example the upArrow/downArrow symbols. It handles full markdown, including bullets, but not tables, nor HTML. It does not support table format, through version 0.1.0, however.
fontfamilies
is passed toassemble_venndir_label()
, as alist
with three named elements:"overlap"
,"count"
,"signed"
.The fontfamily can be customized for each element, which may be useful for a custom font for the overlap label, and a different font (e.g. one that contains upArrow/downArrow unicode characters) for the count and signed count labels.
The custom font is also accepted by
venndir_legender()
for consistency.
outerborder
,outerborder.lwd
,innerborder
,innerborder.lwd
,border
,border.lwd
- these arguments are passed toplot.JamPolygon()
and override internal values when defined. They can be used to produce interesting visual variations of the Venn diagram. For example:outerborder.lwd=0, innerborder.lwd=0, border="white", border.lwd=3
will use a white border.outerborder.lwd=0, innerborder.lwd=4, border="white", border.lwd=1
will use a wide internal border, and thin white line between overlaps.
See also
Other venndir core:
signed_overlaps()
,
textvenn()
,
venn_meme()
,
venndir()