signed_overlaps: Signed overlaps

In jmw86069/venndir: Directional Venn diagrams

Signed overlaps

Description

Calculate signed, directional overlaps across sets

Usage

signed_overlaps(
  setlist,
  overlap_type = c("detect", "each", "overlap", "concordance", "agreement"),
  return_items = FALSE,
  return_item_labels = return_items,
  sep = "&",
  trim_label = TRUE,
  include_blanks = TRUE,
  ...
)

Arguments

setlist	list of named vectors, whose names represent set items, and whose values represent direction using values c(-1, 0, 1).
overlap_type	character value indicating the type of overlap logic: "each" records each combination of signs; "overlap" disregards the sign and returns any match item overlap; "concordance" represents counts for full agreement, or "mixed" for any inconsistent overlapping direction; "agreement" represents full agreement in direction as "agreement", and "mixed" for any inconsistent direction.
return_items	logical indicating whether to return the items within each overlap set.
return_item_labels	logical indicating whether to return the directional label associated with each item. A directional label combines the direction from setlist by item.
sep	character used as a delimiter between set names, the default is "&".
trim_label	logical indicating whether to trim the directional label, for example instead of returning "0 1 -1" it will return "1 -1" because the overlap name already indicates the sets involved.
include_blanks	logical indicating whether each set overlap should be represented at least once even when no items are present in the overlap. When include_blanks=TRUE is useful in that it guarantees all possible combinations of overlaps are represented consistently in the output.
...	additional arguments are passed to list2imsigned().

Details

This function is the core function to summarize overlaps that include signed directionality. It is intended for situations where two sets may share items, but where the signed direction associated with those items may or may not also be shared.

One motivating example is with biological data, where a subset of genes, proteins, or regions of genome, may be regulated up or down, and this direction is relevant to understanding the biological process. Two experiments may identify similar genes, proteins, or regions of genome, but they may not regulate them in the same direction. This function is intended to help summarize item overlaps alongside the directionality of each item.

The directional counts can be summarized in slightly different ways, defined by the argument overlap_type:

• overlap_type="detect" - default behavior: each vector in setlist is handled independently:

  • a vector with no names will use the vector values as items after converting them to character;

  • a named vector with character or factor values will will use the vector names as items, and character values as item values;

  • a named vector with numeric or integer values will use vector names as items, and will convert numeric values to sign().

• overlap_type="each" - this option returns all possible directions individually counted.

• overlap_type="concordance" - this option returns the counts for each consistent direction, for example "up-up-up" would be counted, and "down-down-down" would be counted, but any mixture of "up" and "down" would be summarized and counted as "mixed". For 3-way overlaps, there are 8 possible directions, the labels are difficult to place in the Venn diagram, and are not altogether meaningful. Note that this option is the default for venndir().

• overlap_type="overlap" - this option only summarizes overlaps without regard to direction. This option returns standard Venn overlap counts.

• overlap_type="agreement" - this option groups all directions that agree and returns them as "concordant", all others are returned as "mixed".

Note that overlap_type="agreement" and overlap_type="concordance" will not convert numeric values to sign(), so if the input contains numeric values such as 1.2435 they should probably be converted to sign() before calling signed_overlaps(), for example: signed_overlaps(lapply(setlist, sign))

See Also

Other venndir core: render_venndir(), textvenn(), venn_meme(), venndir()

Examples

setlist <- make_venn_test(100, 2, do_signed=FALSE);

# detect overlap_type
attr(signed_overlaps(setlist, "detect"), "overlap_type")

setlist <- make_venn_test(100, 2, do_signed=TRUE);

# detect overlap_type
attr(signed_overlaps(setlist, "detect"), "overlap_type")

# straight overlap counts
signed_overlaps(setlist, "overlap");

# each directional overlap count
signed_overlaps(setlist, "each");

# concordance overlap counts
signed_overlaps(setlist, "concordance");

# agreement overlap counts
signed_overlaps(setlist, "agreement");

# test to ensure factor input is handled properly
inputlist <- list(setA=factor(c("A", "B", "D")),
   setB=factor(c("A", "C", "E", "F")))
signed_overlaps(inputlist, return_items=TRUE)

# check to verify
signed_overlaps(inputlist, return_items=TRUE)$items

jmw86069/venndir documentation built on July 12, 2024, 12:21 a.m.