Skip to contents

A Note about the Vignettes

Brian Muchmore

2026-07-14

Source: vignettes/articles/A-Note-about-the-Vignettes.Rmd
A-Note-about-the-Vignettes.Rmd

“A short story is confined to one mood, to which everything in the story pertains. Characters, setting, time, events, are all subject to the mood. And you can try more ephemeral, more fleeting things in a story - you can work more by suggestion - than in a novel. Less is resolved, more is suggested, perhaps.”

-Eudora Welty, Conversations with Eudora Welty, p 86

A matrix is a matrix is a matrix

PreciseDist is an instrument for epistemic hygiene in unsupervised analysis. Its argument is simple: the distance or similarity metric you choose is not a throwaway preprocessing detail — it is the structure you are about to analyse. So don’t assume your metric. Build many, test how much they agree, fuse the ones worth trusting, project the result to a graph, and see the structure before you believe it.

Because that argument is data-source-agnostic, PreciseDist treats every input the same way: a matrix is a matrix is a matrix. What it will not do is guess what your numbers mean. Every matrix carries an explicit type (distance or similarity); the package never infers type from values and never silently converts one into the other. Staying aware of how the relationships in your data are numerically defined is the whole point.

One typed workflow

PreciseDist owns four computational tiers. PreciseViz consumes their typed output as the final visual step without importing the core package:

idx <- c(1:5, 61:65, 121:125)
x <- as.matrix(data_cell_cycle[idx, -1])[, 1:50]
storage.mode(x) <- "double"
rownames(x) <- paste0("obs_", seq_len(nrow(x)))

d <- precise_dist(x, dists = c("euclidean", "manhattan", "canberra"),
                  verbose = FALSE)
d <- precise_transform(d, to = "distance")
f <- precise_fusion(d, methods = "mean", verbose = FALSE)
g <- precise_graph(f, methods = "knn", verbose = FALSE)
v <- precise_viz(g, views = "graph_layout", verbose = FALSE)

precise_correlations() measures how much your metrics agree, precise_graphml() exports a graph for Gephi, and precise_trellis() browses a panel tibble with trelliscope. precise_stability() is an optional side-layer for asking whether a fused consensus is sensitive to the candidate matrices you selected.

The vignettes

  • Example Workflow — the whole spine end to end on the bundled cell-cycle data: precise_dist() → precise_transform() → precise_fusion() → precise_graph() → precise_viz(), with precise_correlations() along the way.
  • A Similarity Graph of Distances — treat each metric as an object of study: measure agreement between many distances with precise_correlations(), view it with precise_viz(views = "agreement"), and decide which distances to fuse.
  • Typed Transforms and Graphs — the typed conversion rules of precise_transform() (including why to = "similarity" is deliberately not offered yet) and the four graph constructors of precise_graph().
  • All Available Views — a gallery of every precise_viz() view: heatmap, graph_layout, embedding, and agreement.
  • Viewing Results with Gephi — export any relatedness matrix to GraphML with precise_graphml() and open it in Gephi.
  • Fighting Overfit with PreciseDist — resample the candidate matrix set and ask whether the fused consensus is sensitive to individual metrics.
  • A Parallel Future — run PreciseDist across many cores via the future / doFuture / foreach stack.

“The first principle is that you must not fool yourself — and you are the easiest person to fool.” — Richard Feynman

Found a bug or have a question? Please open an issue at the PreciseDist issues page.