---
title: "Visualizing SOM structure and uncertainty"
author: "Shaowen Ye"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Visualizing SOM structure and uncertainty}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

## A map is one member of an ensemble

Component planes are useful for interpreting a fitted self-organizing map,
but one visually appealing map cannot represent variation across grids,
random starts and resampled data. `SOMevidence` therefore identifies the exact
ensemble member in every map subtitle and requires `fit_id` whenever more than
one successful map is available.

```{r fit}
library(SOMevidence)

dat <- simulate_som_scenario("clusters", n = 120, p = 6, seed = 201)
resamples <- som_resamples(dat, method = "subsample", repeats = 3, seed = 202)
spec <- som_spec(
  grids = list(c(4, 3), c(5, 4)),
  seeds = c(203, 204),
  rlen = 50,
  k = 2:5
)
workflow <- run_som_workflow(
  dat, spec, resamples,
  cross_models = c("kmeans", "ward")
)
fit_id <- workflow$ensemble$fits[[1]]$id
```

```{r component-plane, fig.width = 8, fig.height = 4.5}
plot_som_plane(
  workflow$ensemble,
  fit_id = fit_id,
  variables = colnames(dat$layers$environment)[1:4]
)
```

The fill scale represents codebook values after the transformations,
centering and scaling fitted within that member's analysis split. Occupancy
and adjacent-codebook distance provide complementary views.

```{r map-diagnostics, fig.width = 8, fig.height = 3.8}
plot_som_plane(workflow$ensemble, type = "occupancy", fit_id = fit_id)
plot_som_plane(
  workflow$ensemble,
  type = "neighbour_distance",
  fit_id = fit_id
)
```

## Ensemble evidence belongs beside the map

The representation audit shows the trade-off among quantization, topology and
unused units. The partition profile then shows how much hard classifications
change across the ensemble for each candidate `k`.

```{r audit-plots, fig.width = 7, fig.height = 4}
plot(workflow$audit)
plot(workflow$partitions)
```

For one candidate partition, sample support and normalized assignment entropy
show where a consensus is clear and where assignments remain ambiguous.

```{r consensus, fig.width = 6, fig.height = 4}
consensus <- workflow$consensus$k3
plot(consensus)
consensus$cluster_summary
```

Cross-model agreement is displayed as a distribution for every reference
method and candidate `k`. The plot does not assign ranks or convert agreement
into accuracy.

```{r cross-model, fig.width = 7, fig.height = 4}
plot(workflow$cross_comparison)
```

Together these views separate three questions: what one map looks like, what
the representation diagnostics show, and whether a hard partition is
defensible. They should not be replaced by a single composite score.