Returns one row of scalar summaries per input matrix. Matrix type must be
declared and is not inferred from values.
Usage
precise_diagnostics(
data,
labels = NULL,
k = c(5, 10, 15),
type = NULL,
verbose = TRUE
)Arguments
- data
A tibble from
precise_dist(),precise_transform(),precise_graph(),precise_fusion(), orprecise_stability(), or a named list of matrices withtype=declared. Every matrix must index the same observations in the same order.- labels
Optional vector or factor of known groups for the matrix rows. Named labels are matched to row names. Unnamed labels must already be in matrix order.
- k
Positive whole numbers of neighbours for the graph diagnostics. The default
c(5, 10, 15)is trimmed to fit a small matrix. Akyou supply yourself must satisfy1 <= k < nor it is an error.- type
Only for bare-list input.
"distance"or"similarity". Must be omitted for tibble input.- verbose
TRUEorFALSE. Report start and finish.
Value
A tibble with one row per input matrix and one column per diagnostic,
keyed by distance. The label_* columns are always present and
are NA when labels is not supplied. The knn_k<k>_* columns
depend on k, so the column set varies with k alone.
Output columns
The first four columns identify the row: distance, metric, type, and
n, the number of observations. The remaining columns are computed on the
off-diagonal values.
The value_* columns describe the value distribution: value_min,
value_q25, value_median, value_q75, value_max, value_iqr,
value_sd, and value_cv (standard deviation over the absolute mean, NA
when the mean is zero). value_unique counts distinct off-diagonal values,
value_prop_tied is 1 - value_unique / choose(n, 2), value_prop_zero is
the proportion of off-diagonal values within 1e-12 of zero, and
diag_max_abs is the largest absolute diagonal entry.
The nn_* columns describe nearest neighbours. nn_best_median is the median
relatedness to the closest other observation. nn_contrast_median and
nn_contrast_mean summarize the gap between the closest and second closest
neighbour, oriented so that larger means better separated for either type.
The knn_k<k>_* columns come from a k-nearest-neighbour graph built at each
requested k and symmetrized by union: edges (undirected edge count),
density (edges / choose(n, 2)), components (connected components),
isolated (vertices with no edge), hubness_max (largest in-degree over the
directed neighbour matrix), and hubness_gini (Gini coefficient of that
in-degree distribution).
The label_* columns are NA unless labels is supplied. They are
label_n_classes, label_within_median, label_between_median, their ratio
label_within_between_ratio, label_silhouette (mean silhouette width over
observations), and label_pair_auc, the probability that a random
within-class pair is closer than a random between-class pair. Each k also
gets knn_k<k>_label_agreement, the mean over observations of the share of
an observation's own k nearest neighbours carrying its label. Similarity
input is converted to a dissimilarity as max(offdiag) - s for these
calculations only.
Labels are not used to compute any matrix and are a post hoc check.
See also
precise_correlations() for agreement between matrices, and
precise_run_report() for measures that produced no matrix.
Examples
data(data_cell_cycle, package = "PreciseDist")
cells <- c(1:6, 60:65, 118:123)
cell_cycle <- as.matrix(data_cell_cycle[cells, 2:41])
rownames(cell_cycle) <- paste0(data_cell_cycle$Cell_cycle[cells], "_", cells)
groups <- data_cell_cycle$Cell_cycle[cells]
distances <- precise_dist(
cell_cycle,
dists = c("euclidean", "manhattan", "canberra"),
verbose = FALSE
)
diagnostics <- precise_diagnostics(
distances,
labels = groups,
k = 3,
verbose = FALSE
)
diagnostics[, c("distance", "value_prop_tied", "knn_k3_components",
"label_pair_auc", "knn_k3_label_agreement")]
#> # A tibble: 3 × 5
#> distance value_prop_tied knn_k3_components label_pair_auc
#> <chr> <dbl> <int> <dbl>
#> 1 euclidean 0 1 0.598
#> 2 manhattan 0 1 0.622
#> 3 canberra 0 1 0.586
#> # ℹ 1 more variable: knn_k3_label_agreement <dbl>