Audit reproducibility of continuous SOM representations — audit_som

Computes scope-specific representation diagnostics and compares the topology induced by prespecified pairs of SOM fits. Pairwise evidence uses shortest-hop distances on each SOM grid, so no node labels or map orientations are forced into correspondence. All calculations are exact under explicit fit-pair and sample-pair budgets.

Usage

audit_som_representation(
  ensemble,
  scope = c("analysis", "assessment"),
  neighbourhood_size = NULL,
  pairs = NULL,
  max_pairwise_comparisons = 10000L,
  max_sample_pairs = 1000000L,
  fail_fast = FALSE
)

Arguments

ensemble: A fitted som_ensemble object. Retained kohonen model objects are not required.
scope: Rows compared within each fit: "analysis" or "assessment".
neighbourhood_size: Optional positive integer q for exact local sample-neighbourhood Jaccard. All samples tied at the q-th shortest-hop distance are included. No scientific default is supplied.
pairs: Optional prespecified data frame with fit_a and fit_b columns. The default compares all successful fits.
max_pairwise_comparisons: Maximum number of fit pairs. The function stops before dense topology calculations when this budget is exceeded.
max_sample_pairs: Maximum total number of unordered jointly mapped sample pairs across all requested fit comparisons.
fail_fast: Whether to stop at the first metric-computation error.

Value

A som_representation_audit object with fit metrics, pairwise topology reproducibility, optional sample-neighbourhood records, descriptive summaries, computation budgets, provenance, warnings and failures. Sample pairs and fit pairs are not treated as independent inferential replicates.

Details

This experimental audit concerns continuous representation, not the defensibility of a hard partition. It supplies no score, ranking, automatic threshold or decision status and is not accepted by assess_defensibility().

Examples

data <- simulate_som_scenario("gradient", n = 45, p = 3, seed = 21)
ensemble <- fit_som_ensemble(
  data,
  som_spec(c(3, 2), seeds = 22:23, rlen = 10, k = 2),
  keep_models = FALSE
)
audit_som_representation(ensemble, neighbourhood_size = 5)
#> <som_representation_audit> (experimental)
#>   scope             : analysis 
#>   fit metrics       : 2 of 2 
#>   topology pairs    : 1 of 1 
#>   sample-pair budget: 990 of 1000000 
#>   interpretation    : representation evidence, not a class decision