Package 'SOMevidence'

Description

In addition to analyst-defined thresholds, the assessment checks that every source partition and the consensus retain the requested k, and that all requested cross-model fits succeeded. Missing audit evidence produces an uncertain result rather than being treated as a pass.

Usage

assess_defensibility(
  audit,
  partitions = NULL,
  k = NULL,
  gate = NULL,
  consensus = NULL,
  cross_model = NULL
)

Arguments

Details

A "supported" status means only that the analyst-specified evidence requirements and structural completeness checks were met for the stated data, analysis design, preprocessing, model budget and candidate k. It does not demonstrate that discrete ecological types exist, identify a causal mechanism, or establish ecological truth.

A representation audit alone cannot support a hard partition. A supported decision also requires traceable comparative partition evidence and at least one prespecified partition-quality requirement. Missing evidence or a representation-only gate produces an "uncertain" result.

Value

A som_defensibility object containing evidence and reasons.

Description

Audit representation quality across a SOM ensemble

Usage

audit_som(ensemble)

Arguments

Value

A som_audit object containing fit-level metrics and summaries.

Examples

data <- simulate_som_scenario("clusters", n = 45, p = 3, seed = 1)
specification <- som_spec(c(3, 2), seeds = 1:2, rlen = 10, k = 2)
audit_som(fit_som_ensemble(data, specification, keep_models = FALSE))

Description

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

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().

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.

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)

Description

For each successful fit with assessment rows, the function contrasts mapping error in the analysis and assessment sets and records the fraction of held- out samples mapped to units unoccupied during training. These quantities describe domain shift; they do not establish ecological transferability on their own.

Usage

audit_transfer(ensemble)

Arguments

Value

A som_transfer_audit object with fit-level transfer diagnostics.

Examples

data <- simulate_som_scenario("gradient", n = 60, p = 3, seed = 7)
splits <- som_resamples(data, method = "leave_domain_out")
specification <- som_spec(c(3, 2), seeds = 1, rlen = 10, k = 2)
ensemble <- fit_som_ensemble(data, specification, splits)
audit_transfer(ensemble)

Description

Compare SOM partitions with controlled cross-model references

Usage

compare_cross_models(
  partitions,
  cross_models,
  scope = c("analysis", "assessment", "all")
)

Arguments

Value

A som_cross_comparison containing ARI and AMI effect sizes, summaries, reference-fit success rates, source-partition completeness and source-partition provenance. Neither agreement metric is reported as accuracy.

Examples

data <- simulate_som_scenario("clusters", n = 45, p = 3, seed = 5)
specification <- som_spec(c(3, 2), seeds = 1:2, rlen = 10, k = 2)
ensemble <- fit_som_ensemble(data, specification, keep_models = FALSE)
partitions <- partition_som(ensemble)
references <- fit_cross_models(ensemble, methods = "ward")
compare_cross_models(partitions, references)

Description

Partitions with the same k are compared through sample co-assignment. Labels are aligned to the consensus partition only after fitting. This label alignment does not align SOM nodes and must not be used to force maps with different grids into a common node geometry.

Usage

consensus_som(
  partitions,
  k,
  linkage = "average",
  method = c("auto", "coassignment", "aligned_vote"),
  max_coassignment_n = 5000L
)

Arguments

Value

A som_consensus object containing aligned assignments, partition-assignment, consensus-label and replicated coverage, membership support, assignment entropy and clusterwise Jaccard values. The object also records whether the consensus itself retains all requested clusters and retains the originating partition method as provenance. For co-assignment consensus, coassignment and tree contain the dense matrix and its hierarchical clustering; both are NULL for aligned voting. Aligned voting avoids quadratic growth in sample count, but alignment and upstream partition auditing can still grow quadratically in the number of ensemble members.

Examples

data <- simulate_som_scenario("clusters", n = 45, p = 3, seed = 3)
specification <- som_spec(c(3, 2), seeds = 1:2, rlen = 10, k = 2)
ensemble <- fit_som_ensemble(data, specification, keep_models = FALSE)
consensus_som(partition_som(ensemble), k = 2)

Description

External labels are evaluated only after SOM fitting and consensus construction. ARI and AMI quantify agreement; neither is called accuracy, and agreement does not make the external labels ecological ground truth.

Usage

evaluate_external_labels(
  consensus,
  labels = NULL,
  exclude = NULL,
  label_ids = NULL,
  match_by = c("auto", "id", "position")
)

Arguments

Value

A som_external_assessment object containing the contingency table, long-form cluster composition, ARI, AMI, resolved matching information and mutually exclusive sample-omission accounting.

Examples

data <- simulate_som_scenario("clusters", n = 45, p = 3, seed = 9)
ensemble <- fit_som_ensemble(
  data, som_spec(c(3, 2), seeds = 10:11, rlen = 10, k = 2)
)
consensus <- consensus_som(partition_som(ensemble), k = 2)
labels <- stats::setNames(
  data$metadata$external_label,
  data$metadata$id
)
evaluate_external_labels(consensus, labels[sample(names(labels))])

Description

Expand an ensemble specification into its model budget

Usage

expand_som_spec(spec)

Arguments

Value

A data frame with one row per grid and random seed.

Examples

expand_som_spec(som_spec(c(4, 3), seeds = 1:3, rlen = 20, k = 2:3))

Description

K-means, Ward.D2 and Gaussian mixture models use the same data object, resampling indices and leakage-safe preprocessing as a fitted SOM ensemble. The function creates reference partitions for triangulation; it does not rank algorithms or define any method as ground truth.

Usage

fit_cross_models(
  ensemble,
  methods = c("kmeans", "ward"),
  k = ensemble$spec$k,
  kmeans_seeds = 1L,
  kmeans_nstart = 50L,
  kmeans_iter_max = 100L,
  gmm_model_names = NULL,
  keep_models = FALSE,
  fail_fast = FALSE,
  gmm_seed = 1L
)

Arguments

Value

A som_cross_models object with partitions, warnings and explicit failures.

Examples

data <- simulate_som_scenario("clusters", n = 45, p = 3, seed = 4)
specification <- som_spec(c(3, 2), seeds = 1:2, rlen = 10, k = 2)
ensemble <- fit_som_ensemble(data, specification, keep_models = FALSE)
fit_cross_models(ensemble, methods = c("kmeans", "ward"))

Description

Every model receives preprocessing parameters estimated only from its own analysis rows. Failures are recorded instead of silently discarded. Topographic error is computed during fitting so duplicate full processed matrices need not be retained in every ensemble member.

Usage

fit_som_ensemble(
  data,
  spec,
  resamples = NULL,
  preprocess = som_preprocess(),
  keep_models = TRUE,
  fail_fast = FALSE,
  parallel = FALSE
)

Arguments

Value

A som_ensemble object.

Examples

data <- simulate_som_scenario("clusters", n = 45, p = 3, seed = 1)
specification <- som_spec(c(3, 2), seeds = 1:2, rlen = 10, k = 2)
ensemble <- fit_som_ensemble(data, specification, keep_models = FALSE)
ensemble

Description

The Shiny interface exposes a compact subset of the package workflow for teaching and exploratory configuration. Every completed run can export its exact R script and a YAML configuration snapshot. Version 1.1.x cannot import that snapshot to restore GUI controls. The exported script, not the GUI session or snapshot, is the executable analysis record. The interface is designed for a local R session, and SOMevidence sends no telemetry. In a local session, selected files remain on the local computer. A remotely deployed Shiny application transfers selected files to its host, whose operator is responsible for access controls and data handling.

Usage

launch_som_app()

Value

A shiny.appobj. Pass it to shiny::runApp() or print it in an interactive R session. The application does not return an analysis result; users can export the executable R script for a configured run.

Lifecycle

Experimental. The interface and its exported configuration snapshot schema may change after independent usability testing. The ordinary R API remains the authoritative analysis interface.

Description

Every ensemble member applies only the transformations, centering, scaling and layer geometry learned from its own analysis split. The function reports best-matching units and mapping distances separately by fit; it does not align nodes across different grids or call the result prediction accuracy.

Usage

map_som_ensemble(ensemble, new_data, fail_fast = FALSE)

Arguments

Value

A som_newdata_mapping object with sample-by-fit records, fit-level distance and occupancy summaries, failures and new-data metadata.

Examples

data <- simulate_som_scenario("clusters", n = 45, p = 3, seed = 8)
specification <- som_spec(c(3, 2), seeds = 1, rlen = 10, k = 2)
ensemble <- fit_som_ensemble(data, specification, keep_models = TRUE)
new_data <- som_data(layers = list(
  environment = data$layers$environment[1:3, , drop = FALSE]
))
map_som_ensemble(ensemble, new_data)

Description

The registry records provenance, version, licence, implementation status and the intended role of each external dataset. Only records marked implemented are used by a current package tutorial. Candidate records are governed prospects, not claims of completed package validation. The function returns metadata only; it never downloads data or changes the user's files.

Usage

open_data_registry(role = NULL, domain = NULL)

Arguments

Value

A data frame with one row per governed external dataset.

Examples

open_data_registry(role = "quickstart")

Description

When x is a som_audit, fit-level metrics are directly comparable only when every successful fit uses the same analysis rows. To preserve the established interface, an audit with distinct analysis sets still returns its exploratory fit-level frontier, but emits a warning and marks the result with attr(result, "comparison_scope") == "distinct_analysis_sets". Such a frontier must not be used to choose a configuration. Instead, construct prespecified configuration-level summaries over identical successful split and seed coverage, then pass that justified comparable data frame.

Usage

pareto_candidates(
  x,
  metrics = c(quantization_error = "min", topographic_error = "min", empty_unit_rate =
    "min")
)

Arguments

Value

The non-dominated rows, with a pareto column. Results derived from a som_audit also carry a comparison_scope attribute.

Description

Form and compare candidate hard partitions of SOM units

Usage

partition_som(
  ensemble,
  k = ensemble$spec$k,
  method = "ward.D2",
  scope = c("analysis", "all"),
  max_pairwise_comparisons = 1000000L
)

Arguments

Value

A som_partitions object. Agreement is reported as ARI and AMI, not accuracy. AMI is chance-adjusted and normalized by the arithmetic mean of the two partition entropies.

Examples

data <- simulate_som_scenario("clusters", n = 45, p = 3, seed = 2)
specification <- som_spec(c(3, 2), seeds = 1:2, rlen = 10, k = 2)
ensemble <- fit_som_ensemble(data, specification, keep_models = FALSE)
partition_som(ensemble)

Description

This function deliberately plots a named ensemble member instead of silently treating one fitted map as representative of the ensemble. Component values are on the processed scale used for training.

Usage

plot_som_plane(
  x,
  type = c("component", "occupancy", "neighbour_distance"),
  fit_id = NULL,
  layer = NULL,
  variables = NULL
)

Arguments

Value

An editable ggplot object.

Description

Plot SOM audit trade-offs

Usage

## S3 method for class 'som_audit'
plot(x, ...)

Arguments

Value

A ggplot object.

Description

Plot sample-level consensus evidence

Usage

## S3 method for class 'som_consensus'
plot(
  x,
  type = c("support", "heatmap"),
  samples = NULL,
  max_samples = 500L,
  ...
)

Arguments

Value

A ggplot object.

Description

Plot cross-model agreement without ranking methods

Usage

## S3 method for class 'som_cross_comparison'
plot(x, ...)

Arguments

Value

A faceted ggplot object showing ARI and AMI distributions.

Description

Plot new-data mapping shift across an ensemble

Usage

## S3 method for class 'som_newdata_mapping'
plot(x, ...)

Arguments

Value

An editable ggplot object.

Description

Plot partition reproducibility across candidate class counts

Usage

## S3 method for class 'som_partitions'
plot(x, ...)

Arguments

Value

A faceted ggplot object with ensemble agreement intervals.

Description

Each point represents one sample at one candidate k. The horizontal axis conditions cluster-member sets on jointly evaluable shared samples and therefore isolates repartitioning. The vertical axis also includes eligible members unique to either scenario and therefore combines data coverage with repartitioning. Values are medians across evaluable contrasts. Membership sets are compared directly, so the plot is invariant to arbitrary cluster-label permutations. It describes sensitivity to the scenarios that were supplied, not a probability that a cluster assignment is correct.

Usage

## S3 method for class 'som_sensitivity'
plot(x, k = NULL, ...)

Arguments

Value

An editable ggplot object.

Description

Plot mapping shift in held-out domains

Usage

## S3 method for class 'som_transfer_audit'
plot(x, ...)

Arguments

Value

A ggplot object.

Description

Each named scenario must provide data and spec, and may provide resamples, preprocess and k. Scenarios may represent alternative variable modules, transformations, layer weights, grids or data-coverage rules. Results remain separate by scenario and evidence stream; the function creates no aggregate ranking.

Usage

run_som_sensitivity(
  scenarios,
  cross_models = c("kmeans", "ward"),
  cross_model_control = list(),
  consensus_method = "auto",
  max_coassignment_n = 5000L,
  max_pairwise_comparisons = 1000000L,
  sample_profiles = TRUE,
  keep_workflows = TRUE,
  fail_fast = FALSE
)

Arguments

Value

A som_sensitivity object with tidy evidence tables, shared-sample comparisons between scenario consensus partitions, sample-level membership-set comparisons, scenario failures and optionally full workflows. Scenario agreement uses only samples assigned by at least two ensemble members in both scenarios, and at least two jointly evaluable samples are required before co-membership can be compared. For each focal sample, membership_jaccard_shared conditions on the jointly evaluable sample universe and isolates repartitioning, whereas membership_jaccard_all also includes eligible members unique to either scenario and therefore combines coverage and repartitioning effects. Neither requires aligning arbitrary cluster labels. sample_summary reports both distributions and distinguishes coverage of all planned contrasts from coverage conditional on globally comparable contrasts. These are sensitivity diagnostics, not confidence probabilities. Comparisons across different data objects require supplied identifiers or explicit row names; unsafe default identifiers, failed scenarios, unavailable consensus and absent common k values remain visible through comparison_status rather than being silently omitted. Legacy objects without identifier provenance must be reconstructed with an explicit id argument before cross-object comparison. Candidate k values are read exactly from each scenario or its specification; malformed values are not coerced. A failed scenario without a valid candidate set remains visible with k = NA but cannot contribute to a candidate-specific contrast denominator.

Lifecycle

Experimental. The scenario-list interface may change after independent usability testing. Individual workflow functions and their evidence tables are the candidate-stable interfaces.

Description

The workflow preserves representation quality, partition stability, sample-level consensus and cross-model agreement as separate evidence streams. It does not combine them into a score or select a winning k.

Usage

run_som_workflow(
  data,
  spec,
  resamples = NULL,
  preprocess = som_preprocess(),
  k = spec$k,
  cross_models = c("kmeans", "ward"),
  cross_model_control = list(),
  consensus_method = "auto",
  max_coassignment_n = 5000L,
  keep_models = FALSE,
  fail_fast = FALSE,
  parallel = FALSE,
  max_pairwise_comparisons = 1000000L
)

Arguments

Value

A som_workflow object containing each evidence stream and explicit failure logs.

Examples

data <- simulate_som_scenario("clusters", n = 60, p = 4, seed = 6)
specification <- som_spec(c(3, 2), seeds = 1:2, rlen = 10, k = 2:3)
workflow <- run_som_workflow(
  data, specification, cross_models = c("kmeans", "ward")
)
summary(workflow)

Description

Simulate known-structure data for SOM validation

Usage

simulate_som_scenario(
  scenario = c("gradient", "clusters", "overlap", "grouped_pseudoreplication",
    "multilayer_conflict"),
  n = 180L,
  p = 6L,
  seed = 1L,
  noise_sd = 1,
  class_probs = c(1, 1, 1),
  n_groups = NULL,
  group_icc = 0.7,
  n_domains = 3L,
  domain_shift = 0,
  missing_rate = 0,
  missing_mechanism = c("none", "mcar", "domain"),
  id = NULL
)

Arguments

Value

A som_data object with additional truth and simulation_spec components. Known latent variables and labels are never included in the training layers. Discrete labels are also copied to external_label for post hoc agreement assessment.

Lifecycle

Experimental. Existing scenario names are retained within the 1.x series, while new scenarios and scenario-specific controls may be added in minor releases.

Examples

simulated <- simulate_som_scenario(
  "gradient", n = 60, p = 4, seed = 1, domain_shift = 0.5
)
simulated

Description

Construct a design-explicit SOM data object

Usage

som_data(
  x = NULL,
  layers = NULL,
  id = NULL,
  group = NULL,
  time = NULL,
  domain = NULL,
  weight = NULL,
  external_label = NULL
)

Arguments

Value

An object of class som_data. Named multi-layer inputs are aligned to the first layer by row name when all layers provide row names; incompatible or partly named layers are rejected. An explicit id vector is always interpreted positionally against the first layer and never changes its row order. If no layers have usable row names, their existing row order is treated as authoritative. The scalar id_source records whether sample identifiers were supplied, taken from explicit non-positional row names or generated locally. Stable identifiers are required to compare different data-coverage scenarios.

Examples

x <- data.frame(temperature = 10:14, oxygen = c(9, 8, 8, 7, 6))
data <- som_data(x, id = paste0("sample_", seq_len(nrow(x))))
data

Description

No universal thresholds are supplied. A gate records the analyst's prespecified requirements.

Usage

som_gate(
  max_topographic_error = NULL,
  max_empty_unit_rate = NULL,
  min_median_ari = NULL,
  min_median_ami = NULL,
  min_pairwise_coverage = NULL,
  min_cluster_jaccard = NULL,
  min_consensus_coverage = NULL,
  min_replicated_coverage = NULL,
  min_membership_support = NULL,
  max_assignment_entropy = NULL,
  min_cross_model_ari = NULL,
  min_cross_model_methods = NULL,
  min_success_rate = NULL
)

Arguments

Value

A som_gate object.

Examples

som_gate(min_success_rate = 0.95, min_cluster_jaccard = 0.75)

Description

Define leakage-safe SOM preprocessing

Usage

som_preprocess(
  transform = "identity",
  center = TRUE,
  scale = TRUE,
  zero_replacement = NULL
)

Arguments

Value

A preprocessing specification of class som_preprocess.

Examples

som_preprocess(transform = c("log", "identity"))

Description

Construct design-aware resamples

Usage

som_resamples(
  data,
  method = c("full", "subsample", "group_subsample", "block_subsample",
    "leave_domain_out", "custom"),
  repeats = 50L,
  prop = 0.8,
  seed = 1L,
  unit = "group",
  domain = "domain",
  splits = NULL
)

Arguments

Value

A som_resamples object. The object records the number of distinct analysis sets in n_unique_analysis_splits and identifies repeated sets in duplicate_analysis_splits.

Examples

x <- matrix(seq_len(120), nrow = 30)
data <- som_data(x, group = rep(paste0("site_", 1:10), each = 3))
som_resamples(data, method = "group_subsample", repeats = 2, seed = 1)

Description

Specify a reproducible SOM ensemble

Usage

som_spec(
  grids = data.frame(xdim = 7L, ydim = 5L),
  seeds = 1:10,
  rlen = 500L,
  alpha = c(0.05, 0.01),
  radius = NULL,
  topology = c("hexagonal", "rectangular"),
  neighbourhood = c("gaussian", "bubble"),
  toroidal = FALSE,
  mode = c("batch", "online", "pbatch"),
  k = 2:8,
  max_na_fraction = 0,
  layer_weights = NULL,
  normalize_layers = TRUE,
  cores = 1L
)

Arguments

Value

A som_spec object.

Examples

specification <- som_spec(
  grids = list(c(4, 3), c(5, 4)), seeds = 1:2, rlen = 50, k = 2:4
)
expand_som_spec(specification)

Description

Summarize workflow quality assurance and model outcomes

Usage

## S3 method for class 'som_workflow'
summary(object, ...)

Arguments

Value

A summary.som_workflow object containing fit, consensus, cross-model and provenance summaries plus the original failure tables.

Description

Upgrades a supported public SOMevidence object to the current structural contract using only deterministic, non-analytical migrations. The function never refits a model or fabricates scientific evidence. If a required field cannot be reconstructed, it asks the user to recompute the affected result.

Usage

upgrade_som_object(x)

Arguments

Details

Contract versions describe object structure, not the package or algorithm version that generated an analysis. Retain som_workflow$provenance and sessionInfo() for that purpose.

Value

A validated object under the current contract. The input is not modified in place. Repeated upgrades are idempotent.

Examples

data <- som_data(matrix(seq_len(18), nrow = 6))
legacy <- data
attr(legacy, "som_contract_version") <- NULL
upgrade_som_object(legacy)