Skip to contents

Visualize typed relatedness matrices

Source: R/precise_viz.R
precise_viz.Rd

precise_viz() is a producer-neutral typed visualization router. It accepts a tabular object with matrix, type, and distance or method columns, or a matrix/list with explicit type=, and returns one panel artifact per input matrix and requested view.

Usage

precise_viz(
  data,
  views = "heatmap",
  type = NULL,
  params = list(),
  diagnostics = NULL,
  agreement = NULL,
  parallel = FALSE,
  verbose = TRUE
)

Arguments

data

A typed tabular object, a named list of matrices with type=, or a single bare matrix with type=. Unnamed list elements are labelled matrix_<n>.

views

Character vector of view names (unique); one row per input matrix per view (agreement contributes exactly two rows).

type

Only for bare list/matrix input: "distance" or "similarity".

params

Named list of per-view parameter lists keyed by view name, e.g. params = list(heatmap = list(cluster = FALSE)) or params = list(embedding = list(method = "umap", n_neighbors = 15, min_dist = 0.01, spread = 1, dimensions = 3, engine = "plotly", seed = 42, color = labels, colors = c(A = "#377eb8", B = "#e41a1c"), show_labels = FALSE)). For t-SNE use params = list(embedding = list(method = "tsne", dimensions = 3, perplexity = 15, theta = 0.5, max_iter = 1000, eta = 200, exaggeration_factor = 12)). Graph-layout and embedding seeds default to 42 for stable coordinates. Seeded rendering restores the caller's random-number state before returning.

diagnostics

Optional data frame containing a unique distance key and scalar diagnostic columns. When supplied, those columns are attached to every per-matrix panel by matching input. These columns then become Trelliscope cognostics automatically when the panel tibble is passed to precise_trellis.

agreement

Optional precomputed agreement result corresponding exactly to the matrices in data. Required when views contains "agreement"; otherwise it must be NULL. The object must contain statistic and signif matrices and may contain a parameters list with method, permutations, seed, and input type.

parallel

TRUE or FALSE. Views are deterministic, so parallel output is identical to sequential.

verbose

TRUE or FALSE.

Value

A tibble with one row per panel. The core columns are first: panel_id ("input__view", display-only, never parsed), input, view, input_type, panel (the ggplot/htmlwidget object), panel_class, data (the plotted numbers), parameters, meta and time_taken_seconds. When typed input carries scalar provenance columns such as metric or graph_method, those columns are preserved after the core columns. When diagnostics= is supplied, scalar diagnostic columns are also appended.

Details

Purity rule: precise_viz() never silently creates new relatedness matrices, graph projections, fusions, or transformed types, and never infers type from values. It computes only the visualization data each view declares: dendrogram orderings (heatmap), layout coordinates (graph_layout), embedding coordinates (embedding), and heatmaps of agreement results computed elsewhere (agreement).

Views (accepted_input):

  • heatmap (both): tile map with type-aware hierarchical ordering (cluster = TRUE, method passed to hclust unaltered – case-sensitive); cluster = FALSE browses the matrix in input order. engine = "ggplot2" (default) or "plotly" controls the renderer. meta carries the cophenetic correlation.

  • graph_layout (similarity): igraph layout of an adjacency/similarity matrix. Supported layouts are "mds" (default), "kk", "fr", "drl", "nicely", "sphere", "gem", "graphopt", "lgl", and "dh". Stochastic layouts use the explicit seed. dimensions = 2 (default) or 3 controls the layout dimensionality; 2-D-only igraph layouts are rendered as flat z = 0 layouts when dimensions = 3. render = "graph" draws retained edges; render = "scatter" shows only the vertex layout. engine = "ggplot2" (2-D default), "plotly" (2-D or 3-D), or "threejs" (3-D, requires the suggested threejs) controls the renderer. interactive = TRUE returns a 2-D visNetwork widget (requires the suggested visNetwork).

  • embedding (distance): 2-D or 3-D coordinates via method = "umap" (default, seeded with uwot), "mds" (dependency-free stats::cmdscale fallback), or "tsne" (requires the suggested Rtsne). UMAP exposes n_neighbors, min_dist, and spread. t-SNE exposes perplexity, theta, max_iter, eta, exaggeration_factor, and check_duplicates; perplexity = NULL chooses a safe value from the number of observations. engine = "ggplot2" (2-D default), "plotly" (2-D or 3-D), or "threejs" (3-D, requires the suggested threejs) controls the renderer. color may be a vector or a named vector aligned by observation names; colors may provide a custom palette; and show_labels = TRUE prints observation labels. Similarity input is refused because embedding methods require declared distance input.

  • agreement (collection): renders a precomputed agreement= object as TWO rows – a statistic heatmap and a significance heatmap sharing one clustered metric order. engine = "ggplot2" (default) or "plotly" controls the renderer. PreciseViz does not calculate matrix agreement inside the visualization router.

Author

Brian Muchmore

Examples

x <- matrix(rnorm(24), nrow = 6)
rownames(x) <- paste0("item_", seq_len(nrow(x)))
d <- as.matrix(stats::dist(x))
typed <- tibble::tibble(
  distance = "example",
  matrix = list(d),
  type = "distance"
)
panels <- precise_viz(typed, views = "heatmap", verbose = FALSE)

panels$panel_id
#> [1] "example__heatmap"
panels$panel[[1]]   # a ggplot object