Skip to contents

A Note about the Vignettes

Brian Muchmore

2026-08-13

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

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.

That argument does not care where your data came from, so 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, which is distance, similarity, correlation, or affinity. The package never infers type from values and never silently converts one into another. Staying aware of how the relationships in your data are numerically defined is the whole point.

One workflow

PreciseDist computes. PreciseViz displays the result as the final visual step, without importing the core package:

cells <- c(1:4, 60:63, 118:121)
cell_cycle <- as.matrix(data_cell_cycle[cells, 2:41])
rownames(cell_cycle) <- paste0(data_cell_cycle$Cell_cycle[cells], "_", cells)

d <- precise_dist(cell_cycle, 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_diagnostics() summarizes each matrix with numbers, precise_correlations() measures how much your metrics agree, precise_stability() asks whether a fused consensus depends on one member of the set, precise_graphml() exports a graph for Gephi, and precise_trellis() browses a panel tibble with Trelliscope.

The vignettes

  • Example Workflow — the whole workflow end to end on the bundled cell-cycle data: precise_dist() → precise_transform() → precise_diagnostics() → 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 conversion rules of precise_transform() in both directions, and the graph constructors and normalizations of precise_graph().
  • All Available Views — a gallery of every precise_viz() view: heatmap, embedding, graph_layout, and agreement.
  • Function Factory and Parameter Sweeps — use precise_func_fact() when the question is a family of related metrics rather than one named metric.
  • Metric Set Stability — use precise_stability() to ask whether the metric set you chose is fragile.
  • Minkowski Parameter Neighborhood — a local sweep around Minkowski p = 0.5, then graph normalization before fusion.
  • Viewing Results with Gephi — export any graph matrix to GraphML with precise_graphml() and open it in Gephi.
  • Fighting Overfit with PreciseDist — drop one metric at a time and ask whether the fused consensus was resting on it.
  • 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.