SmartIterator*

Supplementary material — appendices, screenshots of the three scenarios, and the browser demonstrator. Paper: arXiv:2605.28219.

A framework for researchers, recommendations for practitioners, a notebook for students, and instructions for teachers.

▶ Demonstrator Preprint ⬇ Student notebook

Forty-two clusterings later, the elbow is still a matter of opinion.

DBC · densityPBC · partitionTM · topicsCD · community detection click the counter if you feel the urge to re-run everything

Mock panel: an elbow plot with three candidate elbows that three experts read differently. quality metrics elbow? elbow! elbow… three experts, three elbows, one deadline
Mock panel: a transition diagram in which half the items swap groups after one step in k. transitions one step in k later, half the items changed their minds
Mock panel: a small graph whose three communities merge into one as the resolution is lowered. community structure γ one big community everyone is in the same community if you lower the resolution enough

The paper

SmartIterator: Visual Analytics Workflows for Supervising Unsupervised Data Grouping

Gennady Andrienko and Natalia Andrienko — Fraunhofer IAIS, Sankt Augustin, Germany · City, University of London, UK

Currently under review in IEEE TVCG

The paper is currently under review in IEEE Transactions on Visualization and Computer Graphics (IEEE TVCG), 2026. A preprint is available on arXiv; this site collects all material referenced in the appendices.

Read the preprint — arXiv:2605.28219 PDF Online demo

How to cite

@misc{andrienko2026smartiterator,
  title         = {SmartIterator: Visual Analytics Workflows for Supervising
                   Unsupervised Data Grouping},
  author        = {Andrienko, Gennady and Andrienko, Natalia},
  year          = {2026},
  note          = {Under review in IEEE Transactions on Visualization and
                   Computer Graphics},
  eprint        = {2605.28219},
  archivePrefix = {arXiv},
  url           = {https://arxiv.org/abs/2605.28219}
}

Supplementary

Supplementary Appendices and Notebooks

Each appendix provides full-resolution figures and detailed analysis steps for one demonstration from the paper. The corresponding Google Colab notebooks implement key parts of the computational pipeline (parameter sweeps, quality metrics, archetype detection, embedding computation, word cloud generation) in reproducible Python code.

Note: The notebooks implement the computational engine described in the paper (the section on computational components). The IteraScope visual display is a separate Java application within the V-Analytics environment; the notebooks produce the data files that IS consumes, and include standalone visualizations for exploration without IS.
  • Appendix A — Density-Based Clustering (VAST Challenge 2011)

    Simulated microblog messages from the fictional city of Vastopolis; the analysis clusters the 59,761 outbreak-related messages. A contamination event caused spatially concentrated health complaints that vary substantially in density—from tight hospital clusters to elongated, diffuse wind- and water-dispersed patterns. The workflow sweeps DBSCAN parameters (ε and min_samples) across three progressive rounds, using map and space-time cube views for domain validation against the known event geography.

    Highlights: Multi-round progressive refinement; transition-class propagation to isolate borderline members; temporal layering revealed in space-time cube; validation against ground truth.

  • Appendix B — Partition-Based Clustering (EU NUTS-3 Population)

    Demographic indicators (gender and age structure) for ~1,500 European NUTS-3 regions from Eurostat. The workflow sweeps the number of K-means clusters (K = 3…50), compares candidate configurations through violin plots and transition-class propagation, validates geographic coherence on choropleth maps, and verifies robustness through a 30-seed stability sweep.

    Highlights: Violin-based confidence comparison between K = 20 and K = 24; transition decomposition revealing peripheral losses; seed-stability verification; parallel coordinates for demographic profiling.

  • Appendix C — Topic Modeling (IEEE VIS Papers, NMF)

    ~3,800 IEEE VIS papers (1990–2024) with titles and abstracts. The workflow begins with data cleaning (removal of encoding artifacts), sweeps the number of NMF topics (5–25), diagnoses a “wastebasket” topic at ntopics = 16 through Sankey transition analysis, investigates the progressive differentiation of the “time” topic, and validates the final 15-topic solution through 34-year temporal prevalence charts.

    Highlights: data cleaning (a preliminary step) via artifact detection; wastebasket diagnosis through multi-parent Sankey pattern; term-level transition word clouds; temporal prevalence alignment with known community evolution (VAST track founding, growth of evaluation culture).

Notebook Contents Overview

Each notebook implements key computational components from the paper, including:

  • Iterative parameter sweep with parallel execution via ProcessPoolExecutor
  • Per-item uncertainty measures (assignment confidence, outlier score) for each method family
  • Per-iteration quality metrics (silhouette, coherence, Davies–Bouldin, noise %, etc.)
  • HDBSCAN archetype detection on pooled group-level feature vectors with iterative threshold sweep
  • 1D and 2D group embeddings (t-SNE, UMAP, PaCMAP, LocalMAP)
  • MDS-based color assignment ensuring consistency across iterations and threshold changes
  • Word cloud generation (frequency- and TF-IDF-weighted; transition word clouds with gained/lost terms)
  • Temporal prevalence charts (stacked area, line; absolute/proportional; raw/smoothed)

Note: The notebooks do not implement the full IteraScope interactive display (Sankey rendering, violin plots, hover/click interactions, domain-view linking). These are part of the Java-based V-Analytics environment. The notebooks produce the input data files for IS and provide standalone exploratory visualizations.

For researchers

The Framework

SmartIterator (SI) is a visual analytics approach that treats the full sequence of unsupervised grouping results across a parameter sweep as a first-class analytical object. Rather than seeking a single “optimal” parameter configuration, SI guides the analyst through systematic exploration of how data structure emerges, persists, and transforms across configurations—supporting cumulative understanding of data structure along the way.

The approach is operationalized through IteraScope (IS), a coordinated visual display that combines:

  • A quality-metrics chart with semantic color encoding (warm = higher-is-better, cool = lower-is-better)
  • A 1D group embedding with Sankey-style transition flows showing splits, merges, and member movements
  • Violin plots of assignment confidence and outlier scores (globally normalized for cross-group comparison)
  • A 2D group embedding with HDBSCAN-detected recurrent patterns and interactive threshold control
  • Word clouds and term-level transition tooltips (for text corpora)
  • Domain-linked views (maps, space-time cubes, parallel coordinates, temporal prevalence charts)

The iteration workflow

Three method-specific workflows are provided—for density-based clustering, partition-based clustering, and NMF topic modeling—each following a common six-step structure:

StepWhat happensWhat you get
1 · ConfigureDefine the parameter ranges to be explored for the chosen method.A sweep plan
2 · IterateRun the method once per configuration, keeping all intermediate results.A family of groupings
3 · EvaluateCompute internal quality measures per run and compare them across the sweep.Metric profiles
4 · CompareTrack how group memberships change between neighbouring configurations.Transition structure
5 · InterpretInspect content and context in domain-linked views; identify recurring structures and discard single-setting artefacts.Defensible groupings
6 · DecideAccept or refine: adopt the candidate configuration(s), or narrow the ranges and return to step 1.A decision — or the next round
Step 1: Metric Overview & Sweep Configuration
↓
Step 2: Iteration over the Parameter Range
↓
Step 3: Quality-Metric Assessment
↓
Step 4: Transition Assessment (Sankey flows) & Confidence Evaluation (violin plots)
↓
Step 5: Content & Context Inspection (domain views)
↓
Step 6: Decide — accept or refine  ⤻ back to Step 1

Key insight: Each step yields evidence about the data structure. In our demonstrations, studying the transitions between configurations—which groups persist, which split, what vocabulary migrates, where boundaries lie—surfaced observations beyond the final parameter choice. Whether this improves analysts’ understanding or decisions has yet to be tested in a user study; the demonstrations illustrate how the workflows can be used.

Supported scenarios

ScenarioMethod familyKey parametersDemonstration dataset
DBCDensity-based clustering (DBSCAN)ε, min_samplesVAST Challenge 2011 microblogs
PBCPartition-based clustering (K-means)number of clusters K, random seedEU NUTS-3 population structure
TMTopic modeling (NMF)number of topics, vocabulary pruningIEEE VIS papers 1990–2024
CDCommunity detectionresolution γ, random seedAdditional worked example (demo only)

The paper discusses the three scenarios DBC, PBC and TM in detail; community detection is included here as an additional worked example in the demonstrator.

Try it · learn it · teach it

Demonstrator and Educational Materials

Everything below is openly accessible and needs no account. The demonstrator runs entirely in the browser; the student package is self-contained and runs locally or in Colab; the teaching material consists of the fully executed notebook and separate instructor notes.

Why numbers differ between the implementations. The Java IteraScope, the Colab notebooks A–C, the browser demonstrator and the student notebook are separate implementations. They use different libraries, random seeds, preprocessing and, in places, different definitions (for example how the distance between two locations is computed). Results are therefore comparable in kind but not identical, and they are not expected to match exactly.
  • Online demo

    Interactive demonstrator

    Explore precomputed parameter sweeps in IteraScope: quality-metric profiles, Sankey transitions, confidence violins, group embeddings and the linked domain views (maps, space-time cubes, profiles, calendars, word clouds) — for all example datasets, including the cherry blossom data used in the student notebook. Explore… runs your own sweeps in the browser, and you can add your own data. Density-based clustering uses the real (great-circle) distance in km. The caption of the demonstrator shows its release time, so you can check that you are not looking at a cached copy.

  • For students

    Hands-on notebook package

    A guided practical in three parts: density-based clustering of ~9,700 geolocated cherry blossom photos (real distance in km, space-time cubes, quality indicators), K-means on weekly regional photo counts, and a closing exercise in auditing over-confident claims about a single clustering run. Predict-then-reveal checkpoints and interactive sliders throughout.

    Contains the notebook, both datasets, the base map, requirements.txt and a README with local and Colab setup instructions.

  • For teachers

    Executed notebook and instructor notes

    The complete student notebook with every cell executed — all figures, tables and printed results in place — so you can preview the expected outcome of each stage, project it in class, or recover from a failing environment without running anything.

    The instructor notes add learning objectives, suggested timing per stage, the findings students should arrive at, typical misconceptions, discussion prompts and answers to the exercises.

Student feedback

Evaluation

Students used the notebook and could try the web demonstrator. Twenty of them answered a voluntary anonymous questionnaire. The sample is small and self-selected, and the summary reports counts only.

Questionnaire (Appendix D) Summary of responses (Appendix E)

For practitioners

Practical Recommendations

The following recommendations generalize from our experience applying SmartIterator across three method families and diverse datasets. They are intended as actionable guidance for analysts beginning their own parameter-supervision workflows.

At a glance

#RecommendationPrimary evidence
1Start coarse, refine progressivelyMetrics chart over a wide sweep
2Let Sankey bands, not metrics alone, define stabilityTransition flows between neighbouring iterations
3Use domain views to break metric tiesMaps, space-time cubes, word clouds, parallel coordinates
4Inspect what changes, not only what persistsTransition-class propagation of losses
5Treat archetype completeness as necessary, not sufficient2D embedding + HDBSCAN threshold sweep
6Verify seed robustness for partition-based methods20–30 seed sweep: silhouette spread and agreement between seeds
7Document rejections explicitlyNotes from all workflow steps
8When in doubt, keep multiple candidatesComparison of coarse and fine-grained lenses

Start Coarse, Refine Progressively

Begin with a wide parameter sweep at coarse resolution (e.g., K = 3…50 with step 1, or ε = 0.05…1.0 with step 0.05) to identify the region of interest. Examine the metrics chart for elbows, peaks, and plateaus; note where complete iterations cluster. Then narrow the range and reduce the step size for a second round. Two to three rounds typically suffice—each informed by the findings of the previous one. This avoids wasting computation on irrelevant regions and gives early orientation before committing to detailed inspection.

Let Sankey Bands, Not Metrics Alone, Define Stability

A silhouette peak or coherence plateau narrows the candidate range, but the definitive stability evidence comes from transition flows. A “good” configuration is one where the groups at the selected parameter persist with minimal change at neighboring values—visible as wide, horizontal Sankey bands connecting the same vertical positions across consecutive iterations. Specifically:

  • Persistent wide bands: The group is stable—it neither splits nor absorbs neighbors.
  • A band splitting into two: Potential meaningful sub-structure emerging at finer granularity. Inspect both children in domain views.
  • Multiple thin bands converging into one new group: Possible wastebasket—a group collecting heterogeneous members from multiple sources without a unifying identity.
  • A band thinning progressively: The group is dissolving under stricter parameters—its members are borderline.

If a group splits at the very next parameter step, it may be an artifact of the current granularity rather than genuine structure.

Use Domain Views to Break Metric Ties

When multiple configurations score similarly on quality metrics, propagate each to domain-linked views and compare. Domain coherence frequently discriminates between statistically equivalent alternatives:

  • Spatial data: Do clusters form geographically contiguous regions, or are they scattered? Contiguity is a powerful external validator.
  • Temporal data: Do groups exhibit temporal coherence—emerging at specific times, persisting over defined periods?
  • Text data: Do word clouds reveal interpretable themes, or are top terms generic and overlapping?
  • Multivariate data: Do parallel-coordinates profiles show clearly distinct patterns, or do cluster profiles overlap substantially?

The domain view often reveals the “right” answer instantly when metrics are ambiguous.

Inspect What Changes, Not Only What Persists

Transition-class propagation is most informative when applied to understand losses: which members leave a group at the next parameter step, and where do they go? The spatial, temporal, or semantic distribution of lost members reveals the nature of the transition:

  • Losses at cluster edges (spatially coherent): The finer configuration is trimming genuine boundary members—the core structure is preserved.
  • Losses scattered randomly: The configuration change may be over-fitting to noise.
  • Losses forming a coherent sub-group: A genuine sub-structure is emerging—consider whether the finer granularity captures meaningful differentiation.
  • Losses with distinctive vocabulary (topic modeling): A sub-theme is separating out—examine whether it merits its own topic.

This “what changes” perspective often generates more domain insight than examining static group composition at a single configuration.

Treat Archetype Completeness as Necessary, Not Sufficient

A “complete” iteration (containing representatives of all HDBSCAN-detected archetypes) captures the full diversity of recurrent patterns—making it a strong candidate. However:

  • Completeness alone does not guarantee interpretability or confidence. Always verify through the transition, confidence and domain-inspection steps.
  • An iteration missing one archetype may still be preferable if domain context explains the absence (e.g., a noise archetype capturing only preprocessing artifacts, or a rare pattern that only appears under extreme parameter settings).
  • If no iteration is complete, consider whether the archetype threshold is set too aggressively. Lower the min_cluster_size to allow more archetypes—some of which may represent genuine but infrequent patterns.
  • Use the HDBSCAN threshold sweep chart to find a stability plateau where small changes do not alter the archetype count.

Verify Seed Robustness for Partition-Based Methods

K-means and other partition-based methods depend on random initialization. Once a promising K is identified, run 20–30 seeds at that K and look at the score and at the groups:

  • Silhouette spread: a large spread across seeds suggests instability, but a small spread does not prove that the groups are stable.
  • Agreement between seeds: in the Sankey view, bands that run horizontally without fanning out mean that the same items stay together; bands that fan out mean that individual items change groups between seeds. Quantify the agreement if you can (for example with the adjusted Rand index between the partitions of different seeds).
  • 2D embedding: tight archetype clusters show that the group profiles recur, even when single items change groups.
  • If one seed produces a structurally different result (visible as crossed Sankey bands), investigate whether it represents a legitimate alternative interpretation or an inferior local minimum.

Example (EU population data, K = 20, 30 seeds): the silhouette varied only between 0.18 and 0.19, and the group profiles recur, yet partitions of different seeds agreed only moderately (median adjusted Rand index 0.53). The result is stable in quality and in group profiles, but not in the membership of single regions.

For topic modeling (NMF), seed sensitivity is typically lower due to the non-negative constraint, but verification remains good practice.

Document Rejections Explicitly

When an alternative configuration is rejected, record:

  • Which step provided the discriminating evidence (metrics? transitions? violins? domain views?).
  • What specific observation led to rejection (boundary ambiguity? wastebasket pattern? spatial fragmentation?).
  • What the rejection reveals about data structure (e.g., “K=24 rejected because the additional clusters shave off geographic periphery without introducing new demographic archetypes—confirming that Europe's demographic typology is adequately captured at K=20”).

Documented rejections serve two purposes: they strengthen confidence in the final selection (by demonstrating that alternatives were considered and found wanting), and they contribute to cumulative understanding (by revealing what the data does not support).

When in Doubt, Keep Multiple Candidates

The SI workflow does not require converging to a single “winner.” If two configurations offer complementary views of the data—e.g., a coarse typology (K=7) and a fine-grained one (K=20)—both may be worth retaining as analytical lenses for different purposes. The knowledge gained from understanding how the coarse groups differentiate into fine-grained ones is itself a valuable analytical product.