4.12 Custom Signs

One of the defining features of a Venndir figure is the use of \(↑\) up and \(↓\) down arrows to indicate signed counts. By default, these labels are also colored red and blue, respectively.

It may be useful to customize the colors or the symbols associated with each sign, and this definition can be customized in venndir() using an advanced argument curate_df.

4.12.1 Review Sign Curation

The default curate_df can be reviewed with get_venndir_curate_df(), the output is shown in Table 4.3.

get_venndir_curate_df()
Table 4.3: Table 4.4: Default table used to curate sign data when generating signed count labels.
from sign color hide_singlet
-1 ↓ dodgerblue3 FALSE
1 ↑ firebrick FALSE
0 FALSE
concordant = dodgerblue3 TRUE
agreement = dodgerblue3 TRUE
mixed X grey45 FALSE

There is a bit to unpack in how this simple data.frame is used to create the labels shown by Venndir.

First, the input setlist is passed to signed_overlaps() to produce a complete summary of overlaps, and associated overlap signs. An important argument is overlap_type which defines how the overlap signs are summarized. The recognized values are shown in Table 4.5.

Table 4.5: Table 4.6: Values recognized overlap type, with corresponding description.
overlap_type Description
'overlap' Sign information is ignored. Overlap counts are tabulated without sign information.
'concordance' Sign information is tabulated into three general subsets: (1) all agree up, (2) all agree down, and (3) 'mixed'. For (1) and (2) the original signs are retained, keeping '1 1 1' or '-1 -1 -1'. All values with mixed signs, such as '1 -1' are converted to 'mixed'. When hide_singlet=TRUE then single-set counts ignore the sign.
'each' Signed is tabulated for every overlap in maintained without modification.
'agreement' Similar to 'concordance', except that agreement up and agreement down are combined and labeled 'agreement'.

To summarize:

  • Overlaps are tabulated by combinations of sets. Within each overlap, counts are also tabulated by the directionalities using the following rules:
  • overlap_type='overlap' will not tabulate values by signs.
  • overlap_type='concordance' will tabulate values by signs such as '1', '-1', '1 1', '-1 -1', and 'mixed'.
  • overlap_type='each' will tabulate values by signs such as '1', '-1', '1 1', '-1 -1', '1 -1', and '-1 1'.
  • overlap_type='agreement' will tabulate values by signs such as 'agreement', and 'mixed'.

Using overlap_type='each' is recommended to retain all combinations of the sign.

For each overlap, the tabulated signs are used to create a curated "sign prefix", for example '1 1' is converted to '\(↑↑\)', and this prefix is appended to the actual counts. For example the signed label might be '\(↑↑ 12\)'.

Consider the tabulated sign '1 -1':

  • The tabulated sign '1 -1' is split by whitespace into components '1' and '-1'.

  • The first component '1' is matched to 'from' in curate_df:

    from sign color hide_singlet
    1 ↑ firebrick FALSE
    • The value in column 'sign' (\(↑\)) is added to the sign.
    • The color 'firebrick' is added to the sign colors.

  • The next component '-1' is matched to 'from' in curate_df:

    from sign color hide_singlet
    -1 ↓ dodgerblue3 FALSE
    • The value in column 'sign' (\(↓\)) is added to the sign.
    • The color 'dodgerblue3' is added to the sign colors.

  • The sign prefix is '\(↑↓\)'.

  • The colors 'firebrick', 'dodgerblue3' are blended to purple.

  • The complete signed count label is \(↑↓ {counts}\), colored purple.

Additional comments on processing:

  • If the tabulated sign is 'agreement' the signed prefix will be \('='\), colored blue.
  • If the tabulated sign is 'mixed' the signed prefix will be \('X'\).

4.12.2 Customize the Symbols

An optional argument for venndir() is curate_df, which provides a mechanism to customize the visual sign that appears in the Venn diagram.

To illustrate the process, in this example the goal is to use custom symbols to indicate agreement and disagreement: 'Checkmark' to indicate agreement, and 'Ballot X' to indicate disagreement.

Tips:

Unicode characters are described in Wikipedia Unicode.
Formats described as 'U+2191' should be used in R in this form: "\u2191" in order to produce: \(↑\) * Up arrow is Unicode U+2191: \(↑\) * Down arrow is Unicode U+2193: \(↓\) * Checkmark is Unicode U+2713: \(✓\) * Ballot X is Unicode U+2717: \(✗\)

The following steps were used to create Figure 4.18:

  1. Retrieve the default curate_df.
  2. Edit the 'agreement' row, and update column 'sign'.
  3. Edit the 'mixed' row, and update columns 'sign', and 'color'.
  4. Call venndir() with arguments overlap_type='agreement' and curate_df=curate_df.
curate_df <- get_venndir_curate_df()
curate_df[curate_df$from %in% "agreement",
   "sign"] <- "\u2713";
curate_df[curate_df$from %in% "mixed",
   "sign"] <- "\u2715";
curate_df[curate_df$from %in% "mixed",
   "color"] <- "red";

v <- venndir(make_venn_test(do_signed=TRUE),
   overlap_type="agreement",
   innerborder="white", outerborder="white",
   poly_alpha=0.8,
   curate_df=curate_df)
Venn diagram using 'Checkmark' and 'Ballot X' to indicate agreement and disagreement, respectively.

Figure 4.18: Venn diagram using 'Checkmark' and 'Ballot X' to indicate agreement and disagreement, respectively.

4.12.3 More Advanced Signs

In principle, and named list is recognized as a value-list, whose names are items, and values are 'signs'. These 'signs' are typically -1 and 1 to indicate directionality, however any sign values may be used.

Any sign values not recognized by curate_df, as described in Customize the Symbols, remain unchanged and un-colored.

Figure 4.19 shows the effect of changing the signed list values from '1' and '-1', to strings: 'up' and 'dn'. Because 'up' and 'dn' are not defined in curate_df, they remain unchanged in the output Venndir.

setlist <- make_venn_test(n_sets=2, do_signed=TRUE)
setlist2 <- lapply(setlist, function(i){
   i[] <- c("1"="up", "-1"="dn")[as.character(i)]
   i
})
v <- venndir(setlist2,
   overlap_type="each")
Venndir using custom values 'up' and 'dn' instead of 1 and -1.

Figure 4.19: Venndir using custom values 'up' and 'dn' instead of 1 and -1.

The figure shows combinations that include 'upup', 'dnup', and 'dnup'. Notice even the legend tabulates the signed counts using the sign values 'up' and 'dn'.

Further, the sign values 'up' and 'dn' can be assigned to Unicode character as shown in Customize the Symbols. The value can be a string, or even markdown, described in Venndir Markdown Support. The custom value is also shown in the legend.

Figure 4.20 demonstrates how to customize curate_df, matching the sign values 'up' and 'dn', and converts them to new Unicode characters.

curate_df <- get_venndir_curate_df()
du_match <- match(c("-1", "1"), curate_df$from)
curate_df[du_match, "from"] <- c("dn", "up")
curate_df[du_match, "sign"] <- c("\u21E9", "\u21E7")
#
v <- venndir(setlist2,
   curate_df=curate_df,
   overlap_type="each")
Venndir showing the custom signs 'up' and 'down' used to produce Unicode signs as before.

Figure 4.20: Venndir showing the custom signs 'up' and 'down' used to produce Unicode signs as before.

Although directional sign is most often 'up' and 'down', Venndir can recognize more than two signs. The following example demonstrates three signs instead of two. In the simplest form, it uses three letters: 'a', 'b', and 'c'.

setlist <- make_venn_test(n_items=150, n_sets=3, do_signed=TRUE,
   set_names=c("Set 1", "Set 2", "Set 3"))
set.seed(123)
setlist2 <- lapply(setlist, function(i){
   i[] <- c("1"="up", "-1"="dn")[as.character(i)]
   i[] <- sample(letters[1:3],
      replace=TRUE, size=length(i))
   i
})
v <- venndir(setlist2,
   sets=1:2,
   overlap_type="each")
Venndir using three signs: 'a', 'b', and 'c' (left), which are converted to Unicode symbols (right).Venndir using three signs: 'a', 'b', and 'c' (left), which are converted to Unicode symbols (right).

Figure 4.21: Venndir using three signs: 'a', 'b', and 'c' (left), which are converted to Unicode symbols (right).

These signs are converted to custom symbols: \(↑\), \(↓\), \(∆\).

curate_df <- get_venndir_curate_df()
# define a, b, c
curate_df[1, "from"] <- "a"
curate_df[2, "from"] <- "b"
curate_df[3, "from"] <- "c"
# define Unicode symbols
curate_df[1, "sign"] <- "\u2191"
curate_df[2, "sign"] <- "\u2193"
curate_df[3, "sign"] <- "\u2206"
# define colors
curate_df[1, "color"] <- "firebrick"
curate_df[2, "color"] <- "royalblue"
curate_df[3, "color"] <- "gold"

v <- venndir(setlist2,
   curate_df=curate_df,
   overlap_type="each")

Figure 4.21 shows the three-sign example using letters (left), and Unicode symbols (right).

4.12.4 Custom Sign Label Colors

In some scenarios, colorized labels may not be appropriate, or custom colors may be preferred. Custom signed colors can be defined by editing curate_df as described in Custom Signs to this point.

# black text labels
curate_df <- get_venndir_curate_df()
curate_df$color <- "black"
v1 <- venndir(make_venn_test(do_signed=TRUE),
   show_segments=FALSE,
   draw_legend=FALSE,
   curate_df=curate_df,
   poly_alpha=0.01,
   border="black",
   border.lwd=2)
# custom color labels
k <- match(c("-1", "1", "mixed"), curate_df$from)
curate_df$color[k] <- c("purple4", "darkorange", "red3")
v2 <- venndir(make_venn_test(do_signed=TRUE),
   show_segments=FALSE,
   L_lo=65,
   draw_legend=FALSE,
   curate_df=curate_df,
   poly_alpha=0.01,
   border="black",
   border.lwd=2)
Signed Venn diagrams with sign count labels in black (left), and custom colors.Signed Venn diagrams with sign count labels in black (left), and custom colors.

Figure 4.22: Signed Venn diagrams with sign count labels in black (left), and custom colors.

The important step is to edit the column 'color' in curate_df. In the example above, the color contrast is adjusted also, with make_color_contrast(), and optional argument L_lo=65 is passed to allow slightly brighter text on white background, which allows the orange font color saturation to be slighter more pronounced.