| Title: | Headless Venn Diagram Analysis and Rendering |
|---|---|
| Description: | Headless companion to the 'Venn Diagram Lab' web tool (<https://www.venndiagramlab.org/>). Build, render, and statistically analyze Venn / 'UpSet' diagrams from 'CSV' / 'TSV' / 'GMT' / 'GMX' inputs. Provides the same 44 SVG models, intersection / 'Jaccard' / hypergeometric statistics, and PDF report layout as the web tool, with byte-equivalent 'TSV' exports (parity-tested against the published Python package). Integrates with 'ggplot2', 'tidygraph', and 'broom'. |
| Authors: | Zoltán Dul [aut, cre] (ORCID: <https://orcid.org/0000-0002-9523-3450>), Márton Ölbei [aut] (ORCID: <https://orcid.org/0000-0002-4903-6237>), N. Shaun B. Thomas [aut], Azeddine Si Ammour [aut] (ORCID: <https://orcid.org/0000-0002-5504-4444>), Attila Csikász-Nagy [aut] (ORCID: <https://orcid.org/0000-0002-2919-5601>) |
| Maintainer: | Zoltán Dul <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 2.9.0 |
| Built: | 2026-11-13 13:50:36 UTC |
| Source: | https://github.com/zoliqua/venn-diagram-lab |
Compute the Venn region map for a ['VennDataset-class'] and bind it to a model.
analyze(dataset, model = "auto")analyze(dataset, model = "auto")
dataset |
A ['VennDataset-class'] (from one of the 'load_*' functions). |
model |
Model identifier. '"auto"' picks the canonical model for the dataset's set count (alphabetical first match), e.g. 4 sets -> 'venn-4-set'. '"proportional"' requests an area-proportional layout (only supports 2-3 sets, added in Phase 3). Otherwise pass an explicit name from [list_models()]. |
A ['RegionResult-class'] with the per-region item membership, set sizes, and (lazily) 'statistics(result)'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) result@model ds <- load_sample("dataset_real_cancer_drivers_4") result <- analyze(ds, model = "auto") result@modelds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) result@model ds <- load_sample("dataset_real_cancer_drivers_4") result <- analyze(ds, model = "auto") result@model
Read-only, pure companion to ['.binary_columns_to_dataset()'] / ['.aggregated_columns_to_dataset()']. Runs the *same* scanning rules those loaders use internally (including their real dedup-via-'unique()' and blank-identifier-row skipping) and reports what would be silently collapsed or skipped, instead of collapsing/skipping it. It never mutates 'headers'/'rows', never lower-cases an item before recording it, and never calls into 'VennDataset' construction – a purely descriptive pass.
analyze_data_quality( headers, rows, mode = c("binary", "aggregated"), prefix_cols = 1L )analyze_data_quality( headers, rows, mode = c("binary", "aggregated"), prefix_cols = 1L )
headers |
Character vector of column headers (as returned by '.parse_table()$headers'). |
rows |
List of character vectors, one per data row (as returned by '.parse_table()$rows'). |
mode |
'"binary"' (default) or '"aggregated"'. |
prefix_cols |
Number of leading metadata columns in binary mode (default 1). Only column 1 is ever read as the item identifier, matching '.binary_columns_to_dataset()'. Ignored when 'mode = "aggregated"'. |
## Mirroring R's real loader behaviour (not TS/Python byte-parity)
* **Aggregated mode**: like ['.aggregated_columns_to_dataset()'], a whole trimmed cell is treated as *one* item – there is no delimiter-splitting in R's real loader, so none happens here either. * **Binary mode**: like ['.binary_columns_to_dataset()'], only column 1 is read as the item identifier (any extra 'prefix_cols' beyond the first are metadata the loader itself never reads). Rows whose identifier is blank after trimming are skipped **entirely** – not scored for duplicates, case collisions, or empty cells – exactly mirroring 'valid_idx' in '.binary_columns_to_dataset()'. Duplicates are scored **per set column** (mirroring the loader's own 'unique()' applied independently to each set's truthy identifiers), not as one flat id-column entry – R has no "row contributes if any column is truthy" concept the way the TS array-based loader does, so unlike TS/Python, ALL non-blank-id rows count toward case-collision scope regardless of whether any of their set cells are truthy (this matches 'item_order_seen <- unique(item_ids[valid_idx])', which is computed before/independent of the truthy test).
A list with: * 'duplicates_removed' – list of 'list(column, column_name, count, examples)' entries, one per column that has duplicates (columns without duplicates are omitted). 'column' is the 1-based index into 'headers'. 'examples' holds up to 5 item strings, each captured at its 2nd occurrence, in encounter order. * 'empty_cells_skipped' – single integer count of blank cells found while scanning (scope depends on mode; see divergences above). * 'case_collisions' – list of 'list(items = character())' entries, each holding 2+ distinct case-sensitive spellings that share a lower-cased form, in first-appearance order. Purely descriptive: item identity is never folded or merged anywhere in this function. * 'has_warnings' – 'TRUE' if any of the above found something.
headers <- c("Gene", "SetA", "SetB") rows <- list(c("g1", "1", "0"), c("g1", "1", "1"), c("", "1", "0")) report <- analyze_data_quality(headers, rows, mode = "binary") report$has_warningsheaders <- c("Gene", "SetA", "SetB") rows <- list(c("g1", "1", "0"), c("g1", "1", "1"), c("", "1", "0")) report <- analyze_data_quality(headers, rows, mode = "binary") report$has_warnings
Returns one row per item in the dataset's universe, with boolean columns indicating set membership and a 'region_label' column naming the exact region (e.g. '"A"', '"AB"', '"ABC"') the item belongs to. Item ordering follows 'dataset@item_order' (first-seen across all sets, JS Set/Map semantics).
## S3 method for class 'RegionResult' augment(x, ...)## S3 method for class 'RegionResult' augment(x, ...)
x |
A ['RegionResult-class']. |
... |
Unused (broom convention). |
Region labels use the package's positional letter convention (A-I), matching the labels in 'RegionResult@regions' and the bundled SVG models, regardless of the dataset's 'set_names'.
A tibble (or data.frame fallback) with 'nrow(out) == length(x@dataset@item_order)' and columns: 'item' (character), one logical column per set (named after the set), 'region_label' (character).
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (requireNamespace("broom", quietly = TRUE)) broom::augment(result) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) broom::augment(result)ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (requireNamespace("broom", quietly = TRUE)) broom::augment(result) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) broom::augment(result)
Wraps 'stats::p.adjust(p, method = "BH")'. Returns adjusted p-values in the same order as the input. Empty input -> empty output.
bh_fdr(p_values)bh_fdr(p_values)
p_values |
Numeric vector of raw p-values in [0, 1]. |
Numeric vector of adjusted p-values, same length as input.
bh_fdr(c(0.001, 0.01, 0.05, 0.5))bh_fdr(c(0.001, 0.01, 0.05, 0.5))
Mirrors 'src/utils/proportionalLayout.ts circleIntersectionArea' (web tool) and Python 'circle_intersection_area' byte-for-byte.
circle_intersection_area(r1, r2, d)circle_intersection_area(r1, r2, d)
r1 |
Radius of circle 1 (positive numeric). |
r2 |
Radius of circle 2 (positive numeric). |
d |
Distance between centers (non-negative numeric). |
Numeric: 0 if circles are disjoint, pi * min(r1,r2)^2 if fully nested, else the lens-shaped intersection area.
circle_intersection_area(1, 1, 1) # ~ 1.228 circle_intersection_area(1, 1, 3) # 0 (disjoint)circle_intersection_area(1, 1, 1) # ~ 1.228 circle_intersection_area(1, 1, 3) # 0 (disjoint)
Wraps stats::hclust to produce a normalized output that mirrors
the webtool's pure-JS clusterSetOrder and Python
cluster_set_order.
cluster_set_order(D, linkage = c("average", "complete", "single"))cluster_set_order(D, linkage = c("average", "complete", "single"))
D |
Symmetric numeric distance matrix (NxN, zero diagonal). |
linkage |
One of "average" (UPGMA), "complete", "single". |
A list with:
leaf_order: 1-based integer vector — left-to-right
ordering of original indices. At each internal node the
subtree whose minimum original leaf index is smaller is
placed on the left (deterministic; mirrors the webtool /
Python convention).
merges: data.frame with columns left,
right (0-based cluster ids matching the webtool/Python
convention; leaves are 0..N-1, internal nodes are N..2N-2),
height (linkage distance), size (number of
leaves in the merged cluster).
D <- matrix(c(0, 0.2, 0.9, 0.2, 0, 0.85, 0.9, 0.85, 0), nrow = 3) cluster_set_order(D, linkage = "average")D <- matrix(c(0, 0.2, 0.9, 0.2, 0, 0.85, 0.9, 0.85, 0), nrow = 3) cluster_set_order(D, linkage = "average")
Orchestrator that returns a ['StatisticsResult-class'] populated with Jaccard, Dice, Overlap Coefficient, Fold Enrichment (square NxN matrices) plus a long-form hypergeometric table with BH-FDR adjustment.
compute_pairwise( set_names, inclusive_sizes, pairwise_intersections, universe_size )compute_pairwise( set_names, inclusive_sizes, pairwise_intersections, universe_size )
set_names |
Ordered character vector of set identifiers (e.g. c("A","B","C")). |
inclusive_sizes |
Named integer vector of inclusive set sizes ('names(inclusive_sizes)' matches 'set_names'). |
pairwise_intersections |
Named list of pair intersection counts. Keys are "set_a|set_b" with set_a appearing earlier in 'set_names' than set_b. |
universe_size |
Hypergeometric universe N (population size). Integer >= 1. |
A ['StatisticsResult-class'] object.
compute_pairwise( set_names = c("A", "B"), inclusive_sizes = c(A = 10L, B = 8L), pairwise_intersections = list("A|B" = 5L), universe_size = 100L )compute_pairwise( set_names = c("A", "B"), inclusive_sizes = c(A = 10L, B = 8L), pairwise_intersections = list("A|B" = 5L), universe_size = 100L )
Computes 2 * |A intersection B| / (|A| + |B|). Returns 0 if both sets are empty (matches web tool convention).
dice(size_a, size_b, intersection)dice(size_a, size_b, intersection)
size_a |
Inclusive size of set A (integer >= 0). |
size_b |
Inclusive size of set B (integer >= 0). |
intersection |
Inclusive intersection size |A intersection B|. |
Numeric in [0, 1].
dice(10, 10, 5)dice(10, 10, 5)
Returns the universe N consistent with the web tool. Binary CSV/TSV datasets get 'dataset@universe_size' (= csv.rows.length, includes all-zero rows); aggregated/GMT/GMX datasets fall back to 'length(item_order)' (= |union of items|).
effective_universe(result) ## S4 method for signature 'RegionResult' effective_universe(result)effective_universe(result) ## S4 method for signature 'RegionResult' effective_universe(result)
result |
A ['RegionResult-class']. |
Integer, the universe size N.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) effective_universe(result) ds <- load_sample("dataset_real_cancer_drivers_4") result <- analyze(ds) effective_universe(result) # 20000 for binary cancer drivers sampleds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) effective_universe(result) ds <- load_sample("dataset_real_cancer_drivers_4") result <- analyze(ds) effective_universe(result) # 20000 for binary cancer drivers sample
Returns items in EXACTLY the combination of sets listed in 'sets' — that is, in every set in 'sets' AND in none of the other sets in the dataset.
exclusive_items(result, sets)exclusive_items(result, sets)
result |
A ['RegionResult-class'] from [analyze()]. |
sets |
Character vector of set letters ('"A"', '"B"', ...) or display names (values from 'result@dataset@set_names'). May mix both. |
A character vector of item IDs. Empty character if none.
ds <- methods::new("VennDataset", set_names = c("A", "B", "C"), items = list(A = c("x", "y"), B = c("y", "z"), C = c("z", "w")), item_order = c("x", "y", "z", "w"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) exclusive_items(res, c("A", "B")) # "y" (in A and B, not in C)ds <- methods::new("VennDataset", set_names = c("A", "B", "C"), items = list(A = c("x", "y"), B = c("y", "z"), C = c("z", "w")), item_order = c("x", "y", "z", "w"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) exclusive_items(res, c("A", "B")) # "y" (in A and B, not in C)
Computes (k * N) / (K * n). Returns 0.0 if any denominator is zero (matches web tool convention).
fold_enrichment(N, K, n, k)fold_enrichment(N, K, n, k)
N |
Population size (total items in the universe). Integer >= 1. |
K |
Number of success states in the population (e.g. inclusive |A|). Integer >= 0. |
n |
Number of draws (e.g. inclusive |B|). Integer >= 0. |
k |
Observed successes (e.g. |A intersection B|). Integer >= 0. |
Numeric (>= 0; can exceed 1 for over-representation).
fold_enrichment(20000, 138, 581, 126)fold_enrichment(20000, 138, 581, 126)
Log-scale Wald interval. Only k is random (K/N is the fixed population fraction), so with p_hat = k/n: SE(log FE) = SE(log p_hat), approximately sqrt(1/k - 1/n) by the delta method. A Jeffreys-style continuity correction (k+0.5 successes, n+1 trials) keeps the interval finite at k = 0. Bounds are exponentiated back. Byte-parity port of the TypeScript 'foldEnrichmentCI' (packages/core/src/statistics.ts); coverage is validated by Monte Carlo under the null in scripts/bio_validation.py.
fold_enrichment_ci(N, K, n, k)fold_enrichment_ci(N, K, n, k)
N |
Population size (total items in the universe). Integer >= 1. |
K |
Number of success states in the population (e.g. inclusive |A|). Integer >= 0. |
n |
Number of draws (e.g. inclusive |B|). Integer >= 0. |
k |
Observed successes (e.g. |A intersection B|). Integer >= 0. |
Numeric length-2 vector 'c(low, high)' (>= 0).
fold_enrichment_ci(20000, 138, 581, 126)fold_enrichment_ci(20000, 138, 581, 126)
Circle sizes and inter-circle distances are solved analytically (2-set, exact) or by triangulation (3-set, approximate) so that overlap areas match the requested intersection counts. The returned SVG matches the 44-model schema: ShapeA-I, NameA-I, Count_*, CountSUM_*, Bullet* elements are all present and addressable via xml2.
generate_proportional_svg( result, width = .PROP_DEFAULT_WIDTH, height = .PROP_DEFAULT_HEIGHT )generate_proportional_svg( result, width = .PROP_DEFAULT_WIDTH, height = .PROP_DEFAULT_HEIGHT )
result |
A ['RegionResult-class']. |
width |
Canvas width in pixels (default 600). |
height |
Canvas height in pixels (default 600). |
A 'character' (length 1) with the raw SVG.
tmp <- tempfile(fileext = ".tsv") writeLines(c("Gene\tSetA\tSetB", "GENE1\t1\t0", "GENE2\t1\t1", "GENE3\t0\t1"), tmp) ds <- load_tsv(tmp, binary = TRUE) res <- analyze(ds, model = "proportional") svg <- generate_proportional_svg(res) nchar(svg) > 0tmp <- tempfile(fileext = ".tsv") writeLines(c("Gene\tSetA\tSetB", "GENE1\t1\t0", "GENE2\t1\t1", "GENE3\t0\t1"), tmp) ds <- load_tsv(tmp, binary = TRUE) res <- analyze(ds, model = "proportional") svg <- generate_proportional_svg(res) nchar(svg) > 0
Returns a list of ggplot2 layers that draw 'data' (a ['RegionResult-class']) as a rasterized Venn diagram on a unit-square coordinate system, ready to compose with other ggplot2 elements (titles, themes, additional annotations).
geom_venn( mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., width_px = .GEOM_VENN_DEFAULT_WIDTH )geom_venn( mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., width_px = .GEOM_VENN_DEFAULT_WIDTH )
mapping |
Accepted for ggplot2 layer-signature consistency. Currently ignored (the Venn diagram is rendered from 'data', not from aesthetic mappings). Reserved for a future Stat-based extension. |
data |
A ['RegionResult-class'] (required). The Venn diagram to embed. |
stat |
Accepted for signature consistency; currently ignored. |
position |
Accepted for signature consistency; currently ignored. |
... |
Forwarded to 'ggplot2::annotation_custom()' (e.g. 'xmin', 'xmax', 'ymin', 'ymax' to position the venn on a non-unit coordinate system). |
width_px |
Raster width in pixels (default 800). Larger values give sharper output at the cost of memory. |
This is a NEW capability – the Python package has no equivalent. It uses the same rasterization pipeline as [to_pdf_report()]: render the SVG via [render_venn_svg()], rasterize via 'rsvg::rsvg_nativeraster()', and wrap as a 'grid::rasterGrob()' inside 'ggplot2::annotation_custom()'.
A list of ggplot2 layers: an 'annotation_custom' carrying the rasterized Venn, a 'geom_blank' establishing '[0, 1] x [0, 1]' limits, and a 'coord_fixed(ratio = 1)' so the diagram remains square. Note that 'coord_fixed' will override any coordinate system the user has already added; add 'geom_venn()' before other coord layers to avoid a warning.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (getRversion() >= "4.6") { p <- ggplot2::ggplot() + geom_venn(data = result) + ggplot2::theme_void() inherits(p, "ggplot") } if (getRversion() >= "4.6") { result <- analyze(load_sample("dataset_real_cancer_drivers_4")) library(ggplot2) ggplot() + geom_venn(data = result) + theme_void() + ggtitle("Cancer driver overlap (4 sources)") }ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (getRversion() >= "4.6") { p <- ggplot2::ggplot() + geom_venn(data = result) + ggplot2::theme_void() inherits(p, "ggplot") } if (getRversion() >= "4.6") { result <- analyze(load_sample("dataset_real_cancer_drivers_4")) library(ggplot2) ggplot() + geom_venn(data = result) + theme_void() + ggtitle("Cancer driver overlap (4 sources)") }
Returns a 1-row tibble summarizing the analysis: number of sets, number of non-empty regions, total unique items, hypergeometric universe size, resolved model name, whether the layout is approximate (proportional 3-set), and the count of statistically significant / highly significant pairs (FDR-adjusted q < 0.05 / < 0.001).
## S3 method for class 'RegionResult' glance(x, ...)## S3 method for class 'RegionResult' glance(x, ...)
x |
A ['RegionResult-class']. |
... |
Unused (broom convention). |
A 1-row tibble (or data.frame fallback) with columns: 'n_sets', 'n_regions', 'n_items', 'universe_size', 'model', 'is_approximate', 'n_significant', 'n_highly_significant'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (requireNamespace("broom", quietly = TRUE)) broom::glance(result) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) broom::glance(result)ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (requireNamespace("broom", quietly = TRUE)) broom::glance(result) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) broom::glance(result)
Computes P(X >= k) where X ~ Hypergeometric(N, K, n). Returns 1.0 for invalid inputs so the metric is safe to feed into BH-FDR without filtering.
hypergeometric_p_value(N, K, n, k)hypergeometric_p_value(N, K, n, k)
N |
Population size (total items in the universe). Integer >= 1. |
K |
Number of success states in the population (e.g. inclusive |A|). Integer >= 0. |
n |
Number of draws (e.g. inclusive |B|). Integer >= 0. |
k |
Observed successes (e.g. |A intersection B|). Integer >= 0. |
Maps to R's ‘phyper(k - 1, K, N - K, n, lower.tail = FALSE)'. Note that R’s phyper parameter convention differs from Python's scipy: R uses 'm' for success-in-population and 'n' for failure-in-population (= N - K), where Python uses 'N' for total population.
Numeric in [0, 1].
hypergeometric_p_value(20000, 138, 581, 126)hypergeometric_p_value(20000, 138, 581, 126)
Returns items that appear in every set listed in 'sets', regardless of whether they also appear in other (unlisted) sets. For "items in this specific combination only", see [exclusive_items()].
intersection_items(result, sets)intersection_items(result, sets)
result |
A ['RegionResult-class'] from [analyze()]. |
sets |
Character vector of set letters ('"A"', '"B"', ...) or display names (values from 'result@dataset@set_names'). May mix both. |
A character vector of item IDs. Empty character if none.
ds <- methods::new("VennDataset", set_names = c("A", "B", "C"), items = list(A = c("x", "y"), B = c("y", "z"), C = c("z", "w")), item_order = c("x", "y", "z", "w"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) intersection_items(res, c("A", "B")) # "y"ds <- methods::new("VennDataset", set_names = c("A", "B", "C"), items = list(A = c("x", "y"), B = c("y", "z"), C = c("z", "w")), item_order = c("x", "y", "z", "w"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) intersection_items(res, c("A", "B")) # "y"
Computes |A intersection B| / |A union B|. Matches the web tool's convention of returning 0 when both sets are empty (NaN-safe).
jaccard(size_a, size_b, intersection)jaccard(size_a, size_b, intersection)
size_a |
Inclusive size of set A (integer >= 0). |
size_b |
Inclusive size of set B (integer >= 0). |
intersection |
Inclusive intersection size |A intersection B|. |
Numeric in [0, 1].
jaccard(10, 10, 5) jaccard(0, 0, 0)jaccard(10, 10, 5) jaccard(0, 0, 0)
Returns metadata for the 44 bundled SVG model templates plus the 'proportional' synthetic generator (added in Phase 3). Read from JSON region files in 'inst/extdata/models/json/'.
list_models()list_models()
A 'data.frame' with columns 'name' (filename stem), 'set_count' (2-9), and 'display_name' (from the JSON 'name' field). Sorted by '(set_count, name)'.
head(list_models())head(list_models())
Returns the names of the 5 bundled sample datasets, sorted alphabetically. Use [load_sample()] to load one.
list_samples()list_samples()
Character vector of 5 sample identifiers.
list_samples()list_samples()
Supports two layouts: * Binary mode (default): one row per item, with 0/1 columns marking membership in each set. The first 'prefix_cols' columns are item metadata; remaining columns are sets. * Aggregated mode ('binary = FALSE'): each column is a set, and cells contain item identifiers. Empty cells are ignored.
load_csv(path, binary = TRUE, delimiter = NULL, prefix_cols = 1L)load_csv(path, binary = TRUE, delimiter = NULL, prefix_cols = 1L)
path |
Path to the file. |
binary |
'TRUE' for binary 0/1 mode (default), 'FALSE' for aggregated. |
delimiter |
Explicit delimiter override. 'NULL' auto-detects from ',', ';', tab, and space. |
prefix_cols |
Number of leading metadata columns in binary mode (default 1). Ignored when 'binary = FALSE'. |
A ['VennDataset-class'].
tmp <- tempfile(fileext = ".csv") writeLines(c("Gene,SetA,SetB", "G1,1,0", "G2,1,1", "G3,0,1"), tmp) ds <- load_csv(tmp, binary = TRUE) ds@set_namestmp <- tempfile(fileext = ".csv") writeLines(c("Gene,SetA,SetB", "G1,1,0", "G2,1,1", "G3,0,1"), tmp) ds <- load_csv(tmp, binary = TRUE) ds@set_names
Each line is one set: 'set_name<TAB>description<TAB>item1<TAB>item2<TAB>...'. Lines with fewer than 3 tab-separated columns or empty set names are skipped.
load_gmt(path)load_gmt(path)
path |
Path to the .gmt file. |
A ['VennDataset-class'].
tmp <- tempfile(fileext = ".gmt") writeLines(c("SetA\tdesc\tGENE1\tGENE2\tGENE3", "SetB\tdesc\tGENE2\tGENE3\tGENE4"), tmp) ds <- load_gmt(tmp) ds@set_namestmp <- tempfile(fileext = ".gmt") writeLines(c("SetA\tdesc\tGENE1\tGENE2\tGENE3", "SetB\tdesc\tGENE2\tGENE3\tGENE4"), tmp) ds <- load_gmt(tmp) ds@set_names
Row 0 = set names, row 1 = descriptions, rows 2+ = items column-aligned.
load_gmx(path)load_gmx(path)
path |
Path to the .gmx file. |
A ['VennDataset-class'].
tmp <- tempfile(fileext = ".gmx") writeLines(c("SetA\tSetB", "desc_A\tdesc_B", "GENE1\tGENE2", "GENE2\tGENE3"), tmp) ds <- load_gmx(tmp) length(ds@items)tmp <- tempfile(fileext = ".gmx") writeLines(c("SetA\tSetB", "desc_A\tdesc_B", "GENE1\tGENE2", "GENE2\tGENE3"), tmp) ds <- load_gmx(tmp) length(ds@items)
Sample datasets ship inside the package under 'inst/extdata/samples/' and cover biological (cancer drivers, MSigDB pathways) and mock (streaming platforms, gene sets) use cases. Use [list_samples()] to enumerate.
load_sample(name)load_sample(name)
name |
Sample identifier from [list_samples()]. |
A ['VennDataset-class'] with the appropriate format and mode applied.
ds <- load_sample("dataset_mock_gene_sets") length(ds@set_names) ds <- load_sample("dataset_real_cancer_drivers_4") analyze(ds)@modelds <- load_sample("dataset_mock_gene_sets") length(ds@set_names) ds <- load_sample("dataset_real_cancer_drivers_4") analyze(ds)@model
Equivalent to 'load_csv(path, binary = binary, delimiter = "\t", prefix_cols = prefix_cols)'.
load_tsv(path, binary = TRUE, prefix_cols = 1L)load_tsv(path, binary = TRUE, prefix_cols = 1L)
path |
Path to the file. |
binary |
'TRUE' for binary 0/1 mode (default), 'FALSE' for aggregated. |
prefix_cols |
Number of leading metadata columns in binary mode (default 1). Ignored when 'binary = FALSE'. |
A ['VennDataset-class'].
tmp <- tempfile(fileext = ".tsv") writeLines(c("Gene\tSetA\tSetB", "G1\t1\t0", "G2\t1\t1", "G3\t0\t1"), tmp) ds <- load_tsv(tmp, binary = TRUE) ds@universe_sizetmp <- tempfile(fileext = ".tsv") writeLines(c("Gene\tSetA\tSetB", "G1\t1\t0", "G2\t1\t1", "G3\t0\t1"), tmp) ds <- load_tsv(tmp, binary = TRUE) ds@universe_size
Ported byte-for-byte from the web tool's 'oneVsRestEnrichment' (‘packages/core/src/statistics.ts') / Python’s 'one_vs_rest_enrichment' ('venn_diagram_lab.statistics'). For each set S, "rest" is the union of the inclusive members of all *other* sets, derived purely from region counts:
one_vs_rest_enrichment( set_names, inclusive_sizes, exclusive_only_sizes, union_size, universe_size )one_vs_rest_enrichment( set_names, inclusive_sizes, exclusive_only_sizes, union_size, universe_size )
set_names |
Ordered character vector of set identifiers. |
inclusive_sizes |
Named integer vector: set name -> inclusive size (K). |
exclusive_only_sizes |
Named integer vector: set name -> items present in exactly that set alone (the single-set region's exclusive count, excl_S). Names missing from this vector default to 0. |
union_size |
U: union of ALL sets (sum of exclusive counts over every non-empty region, including multi-set regions). |
universe_size |
N: the hypergeometric sampling universe (same value [compute_pairwise()] receives as 'universe_size'). |
* 'U' ('union_size') = union of ALL sets = sum of the exclusive counts over every one of the '2^n - 1' region labels (items in >= 1 set). Binary mode: ‘U' <= the dataset’s row-count universe (rows may belong to no set). Aggregated mode: 'U' == universe. * 'K' = 'inclusive_sizes[[name]]' (inclusive size of S) * 'excl_S' = 'exclusive_only_sizes[[name]]' (items only in S), 0 if absent * 'rest_size' = 'U - excl_S' (items in >= 1 non-S set) * 'k' = 'K - excl_S' (S items also in >= 1 other set) * 'N' ('universe_size') = sampling universe for the hypergeometric test
**Critical:** 'rest_size' is derived from 'union_size' (U), NOT from 'universe_size' (N). This is what makes the test meaningful: in binary mode N > U, so the observed 'k' sits above the hypergeometric support minimum and the p-value is informative. When N == U (aggregated mode, universe equals union) the p-value is ~1 – mathematically honest ("no background to enrich against"), not a bug. See '.superpowers/sdd/task-F6-ts-report.md' for the full derivation.
Uses the same hypergeometric machinery as [compute_pairwise()]. Benjamini-Hochberg FDR is computed over the 'n' one-vs-rest tests (one per set); Bonferroni = 'min(1, p * n)'. Returned rows are sorted by p-value ascending (stable), matching the pairwise convention.
A data.frame with columns 'name, size, rest_size, intersection, expected, fold_enrichment, p_value, p_adjusted, p_bonferroni, significant', sorted by 'p_value' ascending.
one_vs_rest_enrichment( set_names = c("A", "B"), inclusive_sizes = c(A = 10L, B = 8L), exclusive_only_sizes = c(A = 5L, B = 3L), union_size = 13L, universe_size = 100L )one_vs_rest_enrichment( set_names = c("A", "B"), inclusive_sizes = c(A = 10L, B = 8L), exclusive_only_sizes = c(A = 5L, B = 3L), union_size = 13L, universe_size = 100L )
Computes |A intersection B| / min(|A|, |B|). Useful when one set is much smaller than the other.
overlap_coefficient(size_a, size_b, intersection)overlap_coefficient(size_a, size_b, intersection)
size_a |
Inclusive size of set A (integer >= 0). |
size_b |
Inclusive size of set B (integer >= 0). |
intersection |
Inclusive intersection size |A intersection B|. |
Numeric in [0, 1].
overlap_coefficient(10, 5, 3)overlap_coefficient(10, 5, 3)
Translates an expression like '"A & B + !C"' into a sorted integer vector of region bitmasks (each '1..2^n_sets - 1'). The output is intended for composition with [render_venn_svg()] ('highlight = ...') and with the region-accessor family in user code.
parse_region_expression(expr, n_sets)parse_region_expression(expr, n_sets)
expr |
Character scalar; a Boolean expression in the grammar above. |
n_sets |
Integer; number of sets in the diagram (2..9). |
Grammar:
'A', 'B', ..., 'I' — set atoms (uppercase ASCII).
'&' — intersection.
'|' or '+' — union.
'~' or '!' — complement (unary, against '1..2^n_sets - 1').
'(', ')' — grouping.
Precedence (highest first): '~ !', '&', '| +'. Binary operators are left-associative.
Sorted integer vector of region bitmasks. Empty integer vector when the expression is satisfiable by no region (e.g. '"A & ~A"').
parse_region_expression("A & B", n_sets = 3L) # c(3L, 7L) parse_region_expression("A + B", n_sets = 3L) # c(1, 2, 3, 5, 6, 7) parse_region_expression("A & ~B", n_sets = 3L) # c(1L, 5L) parse_region_expression("(A | B) & C", n_sets = 3L) # c(5L, 6L, 7L)parse_region_expression("A & B", n_sets = 3L) # c(3L, 7L) parse_region_expression("A + B", n_sets = 3L) # c(1, 2, 3, 5, 6, 7) parse_region_expression("A & ~B", n_sets = 3L) # c(1L, 5L) parse_region_expression("(A | B) & C", n_sets = 3L) # c(5L, 6L, 7L)
Returned as elements of 'RegionResult@regions'. Bitmask convention: bit 'i' set means "in set with index 'i'" in 'dataset@set_names'.
bitmaskRegion bitmask (1 to 2^n - 1).
labelHuman-readable label like '"AB"' or '"ABC"'.
set_indicesInteger vector of 0-based set indices in this region.
set_namesNames of the sets in this region.
exclusive_itemsItems present in exactly these sets.
inclusive_itemsItems present in at least these sets.
Bundles the input dataset, chosen model, region map, set sizes, and a lazy ['StatisticsResult-class'] accessible via 'statistics(result)'.
datasetThe input ['VennDataset-class'].
modelResolved model name (e.g. '"venn-4-set"' or '"proportional"').
regionsNamed list keyed by 'as.character(bitmask)', each value a ['RegionData-class']. Only non-empty regions are stored (sparse for high set counts with few overlaps).
set_sizesNamed integer vector: set name -> inclusive size.
is_approximate'TRUE' for the proportional 3-set layout where exact areas can't be achieved with circles.
Mirrors the webtool's cluster-aware buildEnrichmentHeatmapSvg path.
Distance D = 1 - Jaccard is fed to [cluster_set_order()]; the
resulting leaf_order permutes both axes, and merge heights drive
the L-shaped overlays emitted under <g class="hm-dendro-col">
(top band) and <g class="hm-dendro-row"> (left band).
render_cluster_heatmap( result, linkage = c("average", "complete", "single"), show_row_dendrogram = TRUE, show_col_dendrogram = TRUE, dendrogram_fraction = 0.12, style = NULL )render_cluster_heatmap( result, linkage = c("average", "complete", "single"), show_row_dendrogram = TRUE, show_col_dendrogram = TRUE, dendrogram_fraction = 0.12, style = NULL )
result |
A ['RegionResult-class'] from [analyze()]. |
linkage |
Linkage method passed to [cluster_set_order()]:
one of |
show_row_dendrogram |
Logical, default |
show_col_dendrogram |
Logical, default |
dendrogram_fraction |
Fraction of the grid extent reserved per
dendrogram band (default |
style |
Optional named list of style overrides (reserved for v2.3+; currently ignored). |
Pure string construction – no xml2.
An ['SvgImage-class'] with 'content', 'width', 'height' set from the computed layout extents.
ds <- load_sample("dataset_real_cancer_drivers_4") res <- analyze(ds) img <- render_cluster_heatmap(res, linkage = "average") nchar(slot(img, "content")) > 0ds <- load_sample("dataset_real_cancer_drivers_4") res <- analyze(ds) img <- render_cluster_heatmap(res, linkage = "average") nchar(slot(img, "content")) > 0
One bar per pairwise statistic, ordered by '(set_a_index, set_b_index)'. Bar height is proportional to the chosen 'metric':
'"neglog10fdr"' (default): (BH-FDR), floor 1e-300.
'"foldEnrichment"': from
[StatisticsResult-class]'s 'fold_enrichment' slot.
render_enrichment_bar( result, metric = c("neglog10fdr", "foldEnrichment"), width = 560L, height = 240L )render_enrichment_bar( result, metric = c("neglog10fdr", "foldEnrichment"), width = 560L, height = 240L )
result |
A ['RegionResult-class'] from [analyze()]. |
metric |
Bar-height metric – '"neglog10fdr"' or '"foldEnrichment"'. |
width, height
|
Output SVG dimensions in pixels. |
Bars use #2e7d32 for significant pairs (FDR < 0.05) and
#888888 otherwise. Significance markers '***' (< 0.001),
'**' (< 0.01), and '*' (< 0.05) appear above each bar.
Pure string construction – no xml2.
An ['SvgImage-class'] with 'content', 'width', 'height'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) img <- render_enrichment_bar(res) nchar(slot(img, "content")) > 0ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) img <- render_enrichment_bar(res) nchar(slot(img, "content")) > 0
Same data and significance scheme as [render_enrichment_bar()] but as a
stem-and-dot plot: a vertical line rises from the baseline to the metric
value, capped by a filled circle whose radius scales with
sqrt(intersection / max_intersection) (range 2.5–8 px).
render_enrichment_lollipop( result, metric = c("neglog10fdr", "foldEnrichment"), width = 560L, height = 240L )render_enrichment_lollipop( result, metric = c("neglog10fdr", "foldEnrichment"), width = 560L, height = 240L )
result |
A ['RegionResult-class'] from [analyze()]. |
metric |
Stem-height metric – '"neglog10fdr"' or '"foldEnrichment"'. |
width, height
|
Output SVG dimensions in pixels. |
Pure string construction – no xml2.
An ['SvgImage-class'] with 'content', 'width', 'height'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) img <- render_enrichment_lollipop(res) nchar(slot(img, "content")) > 0ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) img <- render_enrichment_lollipop(res) nchar(slot(img, "content")) > 0
Builds a ggraph plot where nodes are sets (sized by inclusive cardinality) and edges are pairwise overlaps (thickness proportional to the chosen metric; blue for FDR-significant edges below 'significance_threshold', grey otherwise). Layout uses the deterministic 'stress' algorithm from graphlayouts.
render_network( result, edge_metric = "intersection", seed = 42L, significance_threshold = 0.05, node_color_map = NULL )render_network( result, edge_metric = "intersection", seed = 42L, significance_threshold = 0.05, node_color_map = NULL )
result |
A ['RegionResult-class']. |
edge_metric |
One of '"intersection"', '"jaccard"', '"fold_enrichment"' (capped at 20.0), '"overlap_coefficient"'. |
seed |
Retained for API compatibility; currently unused. The 'stress' layout algorithm is fully deterministic and does not rely on a random seed. |
significance_threshold |
FDR p_adjusted threshold below which edges are colored as significant (default 0.05). |
node_color_map |
Optional named character vector mapping letters ('"A"', '"B"', ...) to fill hex colors. Unspecified letters default to yellow ('"#FFF200"'). |
Idiomatic R port of Python 'render_network' – same parameter contract, but renders via ggraph + tidygraph instead of networkx + matplotlib.
A 'ggplot' (ggraph subclass).
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) p <- render_network(result) inherits(p, "ggplot") result <- analyze(load_sample("dataset_real_cancer_drivers_4")) p <- render_network(result, edge_metric = "jaccard") ggplot2::ggsave(tempfile(fileext = ".png"), p, width = 7, height = 7)ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) p <- render_network(result) inherits(p, "ggplot") result <- analyze(load_sample("dataset_real_cancer_drivers_4")) p <- render_network(result, edge_metric = "jaccard") ggplot2::ggsave(tempfile(fileext = ".png"), p, width = 7, height = 7)
Builds a ComplexUpset ggplot showing intersection sizes (top bars), set membership matrix (middle dot grid), and per-set sizes (left bars). Idiomatic R port of Python 'render_upset' – same parameter contract, but renders via ComplexUpset (ggplot2) instead of matplotlib (not a 1:1 port).
render_upset( result, max_columns = 20L, sort_by = c("size", "degree"), threshold = 0L, color_mode = c("depth", "heatmap", "custom"), colors = NULL )render_upset( result, max_columns = 20L, sort_by = c("size", "degree"), threshold = 0L, color_mode = c("depth", "heatmap", "custom"), colors = NULL )
result |
A ['RegionResult-class']. |
max_columns |
Maximum number of intersections to display (default 20). Top-N by the active sort. |
sort_by |
'"size"' (default – descending) or '"degree"' (membership count ascending then alphabetical). |
threshold |
Exclude intersections with size strictly below this value (default 0L = no filter). |
color_mode |
'"depth"' (default – viridis on degree), '"heatmap"' (Reds on size), or '"custom"' (use the 'colors' mapping). |
colors |
Named character vector mapping intersection LABELS (e.g. '"AB"') to fill hex colors when 'color_mode = "custom"'. Unspecified labels fall back to '"#cccccc"'. |
A 'ggplot' object (saveable via 'ggplot2::ggsave()').
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (getRversion() >= "4.6") { p <- render_upset(result) inherits(p, "ggplot") } if (getRversion() >= "4.6") { result <- analyze(load_sample("dataset_real_cancer_drivers_4")) p <- render_upset(result, sort_by = "degree", color_mode = "heatmap") ggplot2::ggsave(tempfile(fileext = ".png"), p, width = 8, height = 5) }ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (getRversion() >= "4.6") { p <- render_upset(result) inherits(p, "ggplot") } if (getRversion() >= "4.6") { result <- analyze(load_sample("dataset_real_cancer_drivers_4")) p <- render_upset(result, sort_by = "degree", color_mode = "heatmap") ggplot2::ggsave(tempfile(fileext = ".png"), p, width = 8, height = 5) }
Loads the bundled SVG template for 'result@model' (or the explicit 'model' override), walks the DOM via xml2 to overwrite text content ('Name*', 'Count_*', 'CountSUM_*', 'Title') and inline 'fill:' colors ('Shape*', 'Shape*2' for Euler extras, 'Bullet*'), and serializes back to a string.
render_venn_svg( result, model = NULL, set_names = NULL, colors = NULL, title = NULL, show_names = TRUE, show_counts = TRUE, show_items = FALSE, item_options = NULL, highlight = NULL )render_venn_svg( result, model = NULL, set_names = NULL, colors = NULL, title = NULL, show_names = TRUE, show_counts = TRUE, show_items = FALSE, item_options = NULL, highlight = NULL )
result |
A ['RegionResult-class']. |
model |
Optional model id override (filename stem). Default = 'result@model'. |
set_names |
Optional named character vector mapping letters ('"A"', '"B"', ...) to display names. Unspecified letters fall back to 'result@dataset@set_names'. |
colors |
Optional named character vector mapping letters to fill hex colors. Applies to 'BulletX', 'ShapeX', and 'ShapeX2' (Euler extra shapes). |
title |
Optional title override. If ‘NULL', the template’s default title text is preserved. |
show_names |
If 'FALSE', blanks every 'NameA-I' element. |
show_counts |
If 'FALSE', blanks every 'Count_*' and 'CountSUM_*' element. |
show_items |
If 'TRUE', replace the per-region count text with the actual item identifiers (rendered as '<tspan>' lines inside each 'Count_*' text node). Default 'FALSE'. |
item_options |
Named list of overrides for the item-text engine. Recognised keys: 'max_items_per_region' (default 20), 'ncol_items' (default 1), 'truncate_long_names' (default 12; 0 disables), 'line_height' (default 10), 'font_size' (default 8), 'show_counts_with_items' (default 'FALSE'), 'ellipsis' (default '"..."'). Unknown keys raise a warning. |
highlight |
Character vector of region labels (e.g. 'c("AB", "ABC")') or an integer vector of region bitmasks (e.g. the output of [parse_region_expression()]). When set, only the listed regions keep their original fill colour; all other set-shapes are desaturated to '#cccccc' at 25% opacity. Default 'NULL' (no spotlight). |
For 'model = "proportional"', delegates to [generate_proportional_svg()].
Mirrors Python 'render_venn_svg' byte-for-byte except for: (a) the return type is 'character' instead of an 'SvgImage' wrapper class; (b) xml2 may emit slightly different whitespace/attribute ordering than lxml. Functional content (text, fill colors, structure) is identical.
A 'character' (length 1) with the raw SVG.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) svg <- render_venn_svg(result) nchar(svg) > 0 result <- analyze(load_sample("dataset_real_cancer_drivers_4")) svg <- render_venn_svg(result) nchar(svg) > 0ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) svg <- render_venn_svg(result) nchar(svg) > 0 result <- analyze(load_sample("dataset_real_cancer_drivers_4")) svg <- render_venn_svg(result) nchar(svg) > 0
Solves for two circles whose areas equal 'a_only + ab' and 'b_only + ab' and whose intersection area equals 'ab', by analytical bisection on the inter-center distance. Always exact (returns 'is_approximate = FALSE').
solve_2set(a_only, b_only, ab)solve_2set(a_only, b_only, ab)
a_only |
Items in A only (integer >= 0). |
b_only |
Items in B only (integer >= 0). |
ab |
Items in A intersection B (integer >= 0). |
Mirrors Python 'solve_2set' byte-for-byte.
A named list with elements:
Length-2 list of 'list(cx, cy, r)' named lists.
Relative error of the achieved area fit (typically < 1e-4).
Always 'FALSE' for 2-set.
solve_2set(a_only = 30L, b_only = 30L, ab = 10L)solve_2set(a_only = 30L, b_only = 30L, ab = 10L)
Computes pairwise inter-center distances via bisection on the lens intersection area, then places circle C via barycentric triangulation against AB. Always sets 'is_approximate = TRUE' because perfect 3-circle area-proportional fits don't always exist mathematically.
solve_3set(regions)solve_3set(regions)
regions |
Named list keyed by 'as.character(bitmask)' (1..7) -> exclusive count. Missing keys are treated as 0. |
Mirrors Python 'solve_3set' byte-for-byte (including the 'error = NaN' deliberate sentinel - 3-set fit error is not measured in v0.1).
A named list with elements 'circles' (length 3), 'error' (always NaN in v0.1), 'is_approximate' (always TRUE).
solve_3set(list("1" = 100L, "2" = 80L, "3" = 30L, "4" = 60L, "5" = 20L, "6" = 15L, "7" = 5L))solve_3set(list("1" = 100L, "2" = 80L, "3" = 30L, "4" = 60L, "5" = 20L, "6" = 15L, "7" = 5L))
Computes (and on subsequent calls re-computes) the ['StatisticsResult-class'] for the pairwise metric tables. R has no built-in 'cached_property' equivalent for S4 slots, so this is recomputed each call. Cache externally via 'stats <- statistics(result)' if you need to access it many times.
statistics(result) ## S4 method for signature 'RegionResult' statistics(result)statistics(result) ## S4 method for signature 'RegionResult' statistics(result)
result |
A ['RegionResult-class']. |
A ['StatisticsResult-class'].
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) stats <- statistics(result) stats@jaccard["A", "B"] result <- analyze(load_sample("dataset_real_cancer_drivers_4")) stats <- statistics(result) stats@jaccard stats@hypergeometricds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) stats <- statistics(result) stats@jaccard["A", "B"] result <- analyze(load_sample("dataset_real_cancer_drivers_4")) stats <- statistics(result) stats@jaccard stats@hypergeometric
Returned by [compute_pairwise()] and (lazily) by 'statistics()' on a 'RegionResult'. Holds five tables:
jaccardNxN named matrix of Jaccard indices.
diceNxN named matrix of Sorensen-Dice coefficients.
overlap_coefficientNxN named matrix of Szymkiewicz-Simpson overlap coefficients.
fold_enrichmentNxN named matrix of fold-enrichment values.
hypergeometricLong-form data.frame (one row per set pair) with columns: set_a, set_b, intersection, expected, p_value, p_adjusted, p_bonferroni, p_two_sided, jaccard_ci_low, jaccard_ci_high, dice_ci_low, dice_ci_high, significant, highly_significant.
Returned by [render_share_distribution()] and [render_cluster_heatmap()]. Mirrors the Python 'SvgImage' dataclass so cross-package parity tests can use a uniform attribute name ('content'). Note that [render_venn_svg()] still returns a plain 'character' for backward compatibility with the v2.0.x public API; the new plot renderers return 'SvgImage' so callers can introspect explicit 'width' / 'height' extents.
contentThe SVG document as a string.
widthPixel width of the rendered SVG.
heightPixel height of the rendered SVG.
Returns a long-form table with one row per ordered set pair, combining the five pairwise statistical metrics (Jaccard, Dice, overlap coefficient, fold enrichment, hypergeometric p-value + BH-FDR-adjusted q-value). Pair ordering is '(set_a, set_b)' with 'set_a' appearing earlier in 'result@dataset@set_names'.
## S3 method for class 'RegionResult' tidy(x, ...)## S3 method for class 'RegionResult' tidy(x, ...)
x |
A ['RegionResult-class']. |
... |
Unused (broom convention). |
A tibble (or data.frame if 'tibble' is not installed) with columns 'set_a', 'set_b', 'intersection', 'expected', 'jaccard', 'dice', 'overlap_coefficient', 'fold_enrichment', 'p_value', 'p_adjusted', 'significant', 'highly_significant'. One row per unordered pair, so 'n*(n-1)/2' rows for an 'n'-set dataset.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (requireNamespace("broom", quietly = TRUE)) broom::tidy(result) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) broom::tidy(result)ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) if (requireNamespace("broom", quietly = TRUE)) broom::tidy(result) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) broom::tidy(result)
Sheets:
Jaccard – NxN matrix of Jaccard indices.
Sorensen-Dice (the actual sheet title uses the o-with-stroke
character) – NxN matrix of Dice coefficients.
Enrichment – long-form (set_a, set_b,
intersection, union, expected,
fold_enrichment, p_value, fdr,
significant).
to_excel_workbook(result, path)to_excel_workbook(result, path)
result |
A ['RegionResult-class'] from [analyze()]. |
path |
Output xlsx file path. |
Mirrors the Python 'to_excel_workbook()' byte-for-byte in sheet titles, column order, and 4-decimal numeric formatting. Uses openxlsx (pure R, no Java dependency).
Invisibly returns 'NULL'.
ds <- load_sample("dataset_real_cancer_drivers_4") res <- analyze(ds) to_excel_workbook(res, tempfile(fileext = ".xlsx"))ds <- load_sample("dataset_real_cancer_drivers_4") res <- analyze(ds) to_excel_workbook(res, tempfile(fileext = ".xlsx"))
Mirrors the React webapp's "Export Matrix" button + Python's 'RegionResult.to_matrix_tsv()' byte-for-byte.
to_matrix_tsv(result, path) ## S4 method for signature 'RegionResult' to_matrix_tsv(result, path)to_matrix_tsv(result, path) ## S4 method for signature 'RegionResult' to_matrix_tsv(result, path)
result |
A ['RegionResult-class']. |
path |
Destination file path. |
Columns: Item, <SetName1>, <SetName2>, ..., Region. Rows: one per item. Iteration order: mask 1..(2^n - 1); within each mask, items in 'dataset@item_order'.
Invisibly returns 'path'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_matrix_tsv(result, tempfile(fileext = ".tsv")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_matrix_tsv(result, tempfile(fileext = ".tsv"))ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_matrix_tsv(result, tempfile(fileext = ".tsv")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_matrix_tsv(result, tempfile(fileext = ".tsv"))
Mirrors the React webapp's "GraphML" Cytoscape export button + Python's 'to_network_graphml()' byte-for-byte. Nodes are sets (id = letter, label = set name, size = inclusive cardinality); edges are ALL pairwise overlaps (weight = the 'intersection' metric by default) carrying jaccard, foldEnrichment, overlapCoeff, dice, pValue, fdr, and significant attributes. Node/edge order and numeric rendering are pinned – see 'packages/core/src/networkExport.ts' for the parity contract.
to_network_graphml(result, path) ## S4 method for signature 'RegionResult' to_network_graphml(result, path)to_network_graphml(result, path) ## S4 method for signature 'RegionResult' to_network_graphml(result, path)
result |
A ['RegionResult-class']. |
path |
Destination file path. |
Invisibly returns 'path'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_network_graphml(result, tempfile(fileext = ".graphml")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_network_graphml(result, tempfile(fileext = ".graphml"))ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_network_graphml(result, tempfile(fileext = ".graphml")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_network_graphml(result, tempfile(fileext = ".graphml"))
Mirrors the React webapp's "SIF" Cytoscape export button + Python's 'to_network_sif()' byte-for-byte. One line per edge (in edge order), tab-separated: source letter, the literal interaction type 'overlap', then target letter. Isolated nodes (degree 0) are emitted as lone single-token lines after all edges, in node order.
to_network_sif(result, path) ## S4 method for signature 'RegionResult' to_network_sif(result, path)to_network_sif(result, path) ## S4 method for signature 'RegionResult' to_network_sif(result, path)
result |
A ['RegionResult-class']. |
path |
Destination file path. |
Invisibly returns 'path'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_network_sif(result, tempfile(fileext = ".sif")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_network_sif(result, tempfile(fileext = ".sif"))ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_network_sif(result, tempfile(fileext = ".sif")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_network_sif(result, tempfile(fileext = ".sif"))
Mirrors the React webapp's "Enrichment: one-vs-rest (TSV)" export button + Python's 'RegionResult.to_one_vs_rest_tsv()' byte-for-byte.
to_one_vs_rest_tsv(result, path) ## S4 method for signature 'RegionResult' to_one_vs_rest_tsv(result, path)to_one_vs_rest_tsv(result, path) ## S4 method for signature 'RegionResult' to_one_vs_rest_tsv(result, path)
result |
A ['RegionResult-class']. |
path |
Destination file path. |
Each set S is tested against the union of all OTHER sets. 'Rest_Size' is derived from 'U' (the union of ALL sets = sum of exclusive counts over every non-empty region), NOT from [effective_universe()] ('N') – see [one_vs_rest_enrichment()] for the full derivation. Float formatting mirrors [to_statistics_tsv()] byte-for-byte:
Columns: Set, Name, Size, Rest_Size, Intersection, Expected, Fold_Enrichment, P_value, FDR, Bonferroni, Significant. * Expected: 2 decimals * Fold_Enrichment: 3 decimals * P_value / FDR / Bonferroni: scientific (JS toExponential(2)) if '< 0.001', else 6 decimals * Significant: one of '"***"', '"**"', '"*"', '"ns"' keyed off FDR thresholds (0.001, 0.01, 0.05).
Rows are sorted by P_value ascending (matches the underlying [one_vs_rest_enrichment()] table).
Invisibly returns 'path'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_one_vs_rest_tsv(result, tempfile(fileext = ".tsv")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_one_vs_rest_tsv(result, tempfile(fileext = ".tsv"))ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_one_vs_rest_tsv(result, tempfile(fileext = ".tsv")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_one_vs_rest_tsv(result, tempfile(fileext = ".tsv"))
Writes a US Letter landscape PDF with overview, venn+upset, statistics tables, and (by default) network and methodology pages. Each page has a footer with package version, generation timestamp, and page number.
to_pdf_report( result, path, title = NULL, include_network = TRUE, include_about = TRUE, include_share = TRUE, include_cluster = FALSE )to_pdf_report( result, path, title = NULL, include_network = TRUE, include_about = TRUE, include_share = TRUE, include_cluster = FALSE )
result |
A ['RegionResult-class']. |
path |
Output PDF file path. |
title |
Optional title override for the overview page. |
include_network |
If 'TRUE' (default), include the network page. |
include_about |
If 'TRUE' (default), include the methodology page. |
include_share |
If 'TRUE' (default), include the Item Share Distribution page. |
include_cluster |
If 'TRUE', include the Cluster Heatmap page (default ‘FALSE' — opt-in like Python’s 'cluster_heatmap=True'). |
Invisibly returns 'NULL'. The PDF is written to 'path'.
if (getRversion() >= "4.6") { result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_pdf_report(result, tempfile(fileext = ".pdf")) }if (getRversion() >= "4.6") { result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_pdf_report(result, tempfile(fileext = ".pdf")) }
Mirrors the React webapp's "Export Region Summary" button + Python's 'RegionResult.to_region_summary_tsv()' byte-for-byte.
to_region_summary_tsv(result, path) ## S4 method for signature 'RegionResult' to_region_summary_tsv(result, path)to_region_summary_tsv(result, path) ## S4 method for signature 'RegionResult' to_region_summary_tsv(result, path)
result |
A ['RegionResult-class']. |
path |
Destination file path. |
Columns: Region, Sets, Depth, Exclusive_Count, Inclusive_Count, Exclusive_Pct, Items. Rows: every region (1..2^n - 1). Sorted by (Depth ASC, Region label ASC). Items: semicolon-joined, ordered by 'dataset@item_order'. Cells starting with '='/'+'/'-'/'@' (after optional leading whitespace) are escape-prefixed with a single quote.
Invisibly returns 'path'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_region_summary_tsv(result, tempfile(fileext = ".tsv")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_region_summary_tsv(result, tempfile(fileext = ".tsv"))ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_region_summary_tsv(result, tempfile(fileext = ".tsv")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_region_summary_tsv(result, tempfile(fileext = ".tsv"))
Mirrors the React webapp's "Full Result (JSON)" export (‘exportResultJson', 'packages/core/src/jsonExport.ts') and Python’s 'RegionResult.to_json()' byte-for-byte.
to_result_json(result, path) ## S4 method for signature 'RegionResult' to_result_json(result, path)to_result_json(result, path) ## S4 method for signature 'RegionResult' to_result_json(result, path)
result |
A ['RegionResult-class']. |
path |
Destination file path. |
Schema (key order PINNED):
{
"schemaVersion": "1",
"model": "<model id>",
"setNames": { "A": "...", ... },
"universeSize": <int>,
"regions": [
{ "label", "sets": [...], "depth": <int>,
"exclusiveCount": <int>, "inclusiveCount": <int>,
"exclusiveItems": [...] }, ...
],
"setSizes": { "A": <int>, ... },
"statistics": [
{ "a", "b", "jaccard", "dice", "overlapCoeff",
"intersection", "union", "expected", "foldEnrichment",
"pValue", "fdr", "bonferroni", "pTwoSided",
"significant": "***" | "**" | "*" | "ns" }, ...
]
}
'regions' covers all '2^n - 1' non-empty subsets, sorted by depth ascending then label ascending (ASCII); 'exclusiveItems' preserves the dataset item order. 'statistics' is sorted by p-value ascending, with 'significant' rendered as the FDR star label. Every number is emitted through a shared number-rendering rule (fixed 6-decimal, trailing zeros stripped, never scientific) so the bytes match the webapp and Python exports. No trailing newline is written.
Invisibly returns 'path'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_result_json(result, tempfile(fileext = ".json")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_result_json(result, tempfile(fileext = ".json"))ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_result_json(result, tempfile(fileext = ".json")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_result_json(result, tempfile(fileext = ".json"))
Mirrors the React webapp's DataSummaryPanel "Export Statistics" button + Python's 'RegionResult.to_statistics_tsv()' byte-for-byte.
to_statistics_tsv(result, path) ## S4 method for signature 'RegionResult' to_statistics_tsv(result, path)to_statistics_tsv(result, path) ## S4 method for signature 'RegionResult' to_statistics_tsv(result, path)
result |
A ['RegionResult-class']. |
path |
Destination file path. |
Columns: Set_A, Set_B, Name_A, Name_B, Size_A, Size_B, Intersection, Union, Jaccard, Overlap_Coeff, Dice, Expected, Fold_Enrichment, P_value, FDR, Bonferroni, P_two_sided, Jaccard_CI_low, Jaccard_CI_high, Dice_CI_low, Dice_CI_high, FE_CI_low, FE_CI_high, Significant. Float formatting: * Jaccard / Overlap_Coeff / Dice: 4 decimals via [.js_to_fixed()] * Expected: 2 decimals * Fold_Enrichment: 3 decimals * P_value / FDR / Bonferroni / P_two_sided: scientific (JS toExponential(2)) if '< 0.001', else 6 decimals * Jaccard_CI_low/high, Dice_CI_low/high, FE_CI_low/high: 4 decimals * Significant: one of '"***"', '"**"', '"*"', '"ns"' keyed off FDR thresholds (0.001, 0.01, 0.05).
Rows are sorted by P_value ascending (matches the underlying StatisticsResult).
Invisibly returns 'path'.
ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_statistics_tsv(result, tempfile(fileext = ".tsv")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_statistics_tsv(result, tempfile(fileext = ".tsv"))ds <- methods::new("VennDataset", set_names = c("A", "B"), items = list(A = c("x", "y"), B = c("y", "z")), item_order = c("x", "y", "z"), universe_size = 10L, source_path = NULL, format = "csv") result <- analyze(ds) to_statistics_tsv(result, tempfile(fileext = ".tsv")) result <- analyze(load_sample("dataset_real_cancer_drivers_4")) to_statistics_tsv(result, tempfile(fileext = ".tsv"))
Bundles the multi-page PDF report alongside the supporting SVGs (Venn,
UpSet, Network, Share Distribution), TSVs (Region Summary, Item Matrix,
Statistics), the 3-sheet xlsx workbook, and a README.txt provenance
header into a single ZIP. Mirrors the webtool's *Download Everything*
button and Python's vdl report zip.
to_zip_report(result, path, include_share = TRUE, include_cluster = FALSE)to_zip_report(result, path, include_share = TRUE, include_cluster = FALSE)
result |
A ['RegionResult-class'] from [analyze()]. |
path |
Output '.zip' file path. |
include_share |
Passed through to [to_pdf_report()] (default 'TRUE'). |
include_cluster |
Passed through to [to_pdf_report()] (default 'FALSE'). |
Invisibly returns 'NULL'. The ZIP is written to 'path'.
if (getRversion() >= "4.6") { ds <- load_sample("dataset_real_cancer_drivers_4") res <- analyze(ds) to_zip_report(res, tempfile(fileext = ".zip")) }if (getRversion() >= "4.6") { ds <- load_sample("dataset_real_cancer_drivers_4") res <- analyze(ds) to_zip_report(res, tempfile(fileext = ".zip")) }
Returns items that appear in ANY of the sets listed in 'sets'. Equivalent to 'unique(c(items_in_A, items_in_B, ...))'.
union_items(result, sets)union_items(result, sets)
result |
A ['RegionResult-class'] from [analyze()]. |
sets |
Character vector of set letters ('"A"', '"B"', ...) or display names (values from 'result@dataset@set_names'). May mix both. |
A character vector of item IDs (deduplicated, first-seen order).
ds <- methods::new("VennDataset", set_names = c("A", "B", "C"), items = list(A = c("x", "y"), B = c("y", "z"), C = c("z", "w")), item_order = c("x", "y", "z", "w"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) union_items(res, c("A", "B")) # "x", "y", "z"ds <- methods::new("VennDataset", set_names = c("A", "B", "C"), items = list(A = c("x", "y"), B = c("y", "z"), C = c("z", "w")), item_order = c("x", "y", "z", "w"), universe_size = 10L, source_path = NULL, format = "csv") res <- analyze(ds) union_items(res, c("A", "B")) # "x", "y", "z"
Convenience wrapper around ['analyze_data_quality()'] that reads and parses a file the same way ['load_csv()'] does (auto-detecting the delimiter unless overridden), **without** building a 'VennDataset'. This is the opt-in surface for data-quality feedback: ['load_csv()'] / ['load_tsv()'] themselves never emit warnings and are unchanged by this function's existence.
validate_dataset( path, mode = c("binary", "aggregated"), delimiter = NULL, prefix_cols = 1L, warn = TRUE )validate_dataset( path, mode = c("binary", "aggregated"), delimiter = NULL, prefix_cols = 1L, warn = TRUE )
path |
Path to the file. |
mode |
'"binary"' (default) or '"aggregated"'. |
delimiter |
Explicit delimiter override. 'NULL' auto-detects, same as ['load_csv()']. |
prefix_cols |
Number of leading metadata columns in binary mode (default 1). Only column 1 is ever read as the item identifier, matching '.binary_columns_to_dataset()'. Ignored when 'mode = "aggregated"'. |
warn |
If 'TRUE' (default) and the report has any findings, emits a single 'warning()' summarizing the counts. Set 'FALSE' to only get the returned report silently. |
The 'analyze_data_quality()' report list, returned in addition to (not instead of) any 'warning()' raised.
tmp <- tempfile(fileext = ".csv") writeLines(c("Gene,SetA,SetB", "G1,1,0", "G1,1,1", "G2,0,1"), tmp) report <- validate_dataset(tmp, mode = "binary") report$has_warningstmp <- tempfile(fileext = ".csv") writeLines(c("Gene,SetA,SetB", "G1,1,0", "G1,1,1", "G2,0,1"), tmp) report <- validate_dataset(tmp, mode = "binary") report$has_warnings
Returns the installed version of vennDiagramLab as a character string.
This trivial function exists so the Phase 0 skeleton has one public
export; Phase 1 introduces the real analyze() / load_*() API.
vdl_version()vdl_version()
Character string, the package version (e.g. "2.0.0").
vdl_version()vdl_version()
Returned by the 'load_*()' family and consumed by [analyze()]. Holds the deduplicated set members, first-seen item ordering for byte-equivalent TSV output, and source metadata (path, format, optional hypergeometric universe size).
set_namesOrdered character vector of set identifiers (length 2-9).
itemsNamed list ('names(items) == set_names') of character vectors, each containing the deduplicated members of the corresponding set.
item_orderFirst-seen insertion order of all items across all sets, matching JS Set/Map semantics. Used by TSV writers (Phase 2) for byte-equivalent output to the web tool.
universe_sizeHypergeometric universe N (population size) from the source file, when known. Binary CSV/TSV loaders set this to the row count (matching the web tool's 'csv.rows.length'); other formats leave it 'NULL', signaling "compute as length(item_order)" downstream.
source_pathOriginal file path if loaded from disk; 'NULL' for in-memory datasets.
formatSource format: one of '"csv"', '"tsv"', '"gmt"', '"gmx"'.