Curate Venn labels

Usage

curate_venn_labels(
  x,
  type = c("sign", "color", "hide_singlet", "all"),
  curate_df = NULL,
  unicode = TRUE,
  blend_preset = "ryb",
  split = " ",
  ...
)

Arguments

x

vector of overlap labels.

type

character string, default 'type'.

type="sign" will curate x to sign
type="color" will curate x to color
type="hide_singlet" will indicate whether to hide singlet values, intended for values such as "agreement" which are not useful to display for singlet (single group) count values.
type="all" will return all the above as data.frame.

curate_df

data.frame or NULL with optional curation rules. The input is coerced to data.frame if necessary. The colnames are expected to include:

"from" - regular expression patterns
"sign" - replacement value when type="sign"
"color" - replacement R color when type="color"
"hide_singlet" - logical whether to display signed counts for singlet overlap sets.

unicode

logical default TRUE, whether to use Unicode characters, passed to get_venndir_curate_df.

blend_preset

character string passed as preset to colorjam::blend_colors() to define the color wheel used during color blending operations.

split

character string used to split each "sign" in the input string x, assumed to be space character " ". This split is required to process replacement for each "sign" value without iteratively replacing values in x which can cause re-replacement of values which is not intended.

...

additional arguments are ignored.

Value

vector of labels or colors, based upon argument type, or when type="all" it returns data.frame with rows for each entry in x.

Details

This venndir utility function is used to convert a basic directional label such as "0 1 0 -1" suitable for display. It can output either Unicode or non-Unicode text label, or a corresponding color.

The input is defined in a data.frame obtained from get_venndir_curate_df(), or using the user-provided curate_df.

Each sign returned by signed_overlaps() is matched in the 'from' column, then replaced with values in the 'sign' column, then colorized by the 'color' column.

Note that zeros "0" are typically removed before calling this function.

The curate_df must contain these four colnames:

"from" - regular expression patterns, which will be surrounded by "^(" and ")$" to ensure complete match.
"sign" - character replacement for each value matched in "from" when type="sign".
"color" - character R color to assign to each value matched in "from", when type="color".
"hide_singlet" - logical indicating whether signed singlet counts should be hidden, for example "agreement" has no meaning when only one set is involved.

Multiple signs are concatenated together, in the event the input overlap has multiple values, for example "1 1" becomes "^^" with no spacing.

To impose whitespace between sign characters, define sign=c("^ ", "v ") to include whitespace. Any leading/trailing whitespace will be removed afterwards.

Examples

venn_labels <- c("0 1 0 -1", "1 -1", "1 1 1", "mixed", "agreement", "1 1 0 0");
(curate_venn_labels(venn_labels, "sign"))
#> [1] "-↑-↓" "↑↓"   "↑↑↑"  "X"    "="    "↑↑--"
(curate_venn_labels(venn_labels, "sign", unicode=FALSE))
#> [1] "-^-v" "^v"   "^^^"  "X"    "="    "^^--"

(curate_venn_labels(venn_labels, "color"))
#> [1] "#9E4497FF" "#9E4497FF" "#B22222FF" "#737373FF" "#1874CDFF" "#B22222FF"

(curate_venn_labels(venn_labels, "all"))
#>   sign     color hide_singlet
#> 1 -↑-↓ #9E4497FF        FALSE
#> 2   ↑↓ #9E4497FF        FALSE
#> 3  ↑↑↑ #B22222FF        FALSE
#> 4    X #737373FF        FALSE
#> 5    = #1874CDFF         TRUE
#> 6 ↑↑-- #B22222FF        FALSE

jamba::printDebug(as.list(curate_venn_labels(venn_labels, "sign")),
   collapse=", ",
   fgText=as.list(curate_venn_labels(venn_labels, "color")))
#> ##  (00:41:52) 02Jun2025:   -↑-↓, ↑↓, ↑↑↑, X, =, ↑↑--