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.

from	sign	color	hide_singlet
1	↑	firebrick	FALSE

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.

Unicode characters are described in Wikipedia 'List of Unicode characters'. * A 'Checkmark' is Unicode U+2713 \(✓\). * A 'Ballot X' is Unicode U+2717 \(✕\).

The following steps were used to create Figure 4.20:

Retrieve the default curate_df.
Edit the 'agreement' row, and update column 'sign'.
Edit the 'mixed' row, and update columns 'sign', and 'color'.
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=1,
   curate_df=curate_df)

Figure 4.20: 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 value can be used.

Figure 4.21 shows the effect of replacing signed values '1' and '-1' with text strings: 'up' and 'dn'.

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

Figure 4.21: 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.

In fact, the values 'up' and 'dn' can be assigned to Unicode characters as shown in Customize the Symbols. The custom signs are also shown in the legend.

Figure 4.22 shows how to customize curate_df to match the custom signs 'up' and 'dn'. For added fun, the values in 'sign' are also customized 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")

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

The following example pushes the limits further, using three signs instead of two. In this example, there are three signs: 'a', 'b', and 'c'. See Figure 4.23.

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

Figure 4.23: Venndir using three signs: 'a', 'b', and 'c'.

The signs 'a', 'b', and 'c' can be converted to their own signs with curate_df. The final example is shown in Figure 4.24, with three custom Unicode symbols shown to represent 'a', 'b', and 'c'.

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.24: Venndir using three signs 'a', 'b', 'c' which are converted to Unicode arrows using curate_df.