Quantitative diagnostics for typed relatedness matrices

precise_diagnostics() gives a compact, numeric readout for each distance or similarity matrix. It is meant to sit beside visual inspection: it reports matrix spread, degeneracy, nearest-neighbour contrast, hubness, graph fragmentation at selected k values, and, when labels are supplied, how well local relatedness respects those labels.

Usage

precise_diagnostics(
  data,
  labels = NULL,
  k = c(5, 10, 15),
  type = NULL,
  verbose = TRUE
)

Arguments

data

A typed tibble from precise_dist, precise_transform, precise_graph, precise_fusion, or precise_stability, or a named list of matrices with type= declared.

labels

Optional vector or factor of known groups/classes for the matrix rows. Named labels are matched to row names; unnamed labels must already be in matrix order.

k

Positive whole-number neighbour counts for k-nearest-neighbour diagnostics. The default c(5, 10, 15) is truncated for small matrices; explicitly supplied invalid k values error.

type

Only for bare-list input: "distance" or "similarity". Must be omitted for typed tibble input.

verbose

TRUE or FALSE.

Value

A tibble with one row per input matrix. The first columns identify the input (distance, metric, type, n); remaining columns are scalar diagnostics suitable for sorting, filtering, or prompting an LLM to inspect specific matrices. Visualization packages may attach these diagnostics to panels by matching distance.

Details

This function does not cluster, rank, or choose a "best" matrix. It never touches raw input data and never infers whether a matrix is a distance or similarity from its values; type must come from a typed PreciseDist object or from the explicit type= argument for bare-list input.

Examples

x <- replicate(5, rnorm(30))
rownames(x) <- paste0("r", seq_len(nrow(x)))
labels <- rep(c("a", "b"), each = 15)

d <- precise_dist(x, dists = c("euclidean", "manhattan"), verbose = FALSE)
precise_diagnostics(d, labels = labels, k = c(3, 5), verbose = FALSE)
#> # A tibble: 2 × 39
#>   distance  metric    type         n value_min value_q25 value_median value_q75
#>   <chr>     <chr>     <chr>    <int>     <dbl>     <dbl>        <dbl>     <dbl>
#> 1 euclidean euclidean distance    30     0.757      2.56         3.27      3.98
#> 2 manhattan manhattan distance    30     1.44       4.69         5.96      7.54
#> # ℹ 31 more variables: value_max <dbl>, value_iqr <dbl>, value_sd <dbl>,
#> #   value_cv <dbl>, value_unique <int>, value_prop_tied <dbl>,
#> #   value_prop_zero <dbl>, diag_max_abs <dbl>, nn_best_median <dbl>,
#> #   nn_contrast_median <dbl>, nn_contrast_mean <dbl>, label_n_classes <int>,
#> #   label_within_median <dbl>, label_between_median <dbl>,
#> #   label_within_between_ratio <dbl>, label_silhouette <dbl>,
#> #   label_pair_auc <dbl>, knn_k3_edges <int>, knn_k3_density <dbl>, …