Changes in version 0.1.0                        

Feature contracts

  - Bind named training features and optional declared measurement
    metadata to models; prediction and updates reject incompatible
    feature order or metadata. Unnamed and legacy models retain
    positional compatibility.

Performance

  - Faster core training: the per-sample k-nearest-coding-vector search
    now reuses the distances already computed for the quantization step
    instead of recomputing them and copying the active codebook on every
    sample. Embeddings are unchanged (bit-identical).
  - predict() and the codebook-graph plotting paths (plot() /
    autoplot()) are vectorized.

Bug fixes

  - autoplot() no longer errors for type = "codebook" or type = "graph"
    when color_by has input-point length; like plot(), it now maps the
    labels to coding vectors.
  - The UMAP dispersion step now winsorizes the embedding before
    building the UMAP init, so a single drifted coding vector can no
    longer dominate the min-max scaling and strand its points as a far
    outlier. This removes occasional outliers and improves cluster
    separation (e.g. Fashion-MNIST reproduction AMI 0.50 -> 0.55). Only
    the dispersion = TRUE path is affected; the core SONG embedding is
    unchanged.
  - The UMAP dispersion now uses a stronger refinement (200 epochs,
    learning rate 1.0, min_dist = 0.1) instead of the reference's very
    gentle 11-epoch step. songR's raw embedding is more collapsed than
    the reference's on hard, multi-class data, and the gentle step left
    it stranded near one axis; the stronger refinement makes the
    embedding use the full plane and, in benchmarks, improves AMI on
    every tested dataset (MNIST, Fashion-MNIST, COIL-20, Samusik, Wong).
    Only the dispersion = TRUE visualization changes; the core SONG
    embedding stays frozen.
  - The Shiny comparison app no longer claims SONG stops training early,
    and its documented k and epochs defaults match the implementation.

Robustness

  - song() validates max_age and max_prototypes.
  - All user-facing messages now use cli, with errors signalled at the
    calling function for clearer tracebacks. Messages and behavior are
    otherwise unchanged.

Verification

  - Added reference-parity tests against the original Python
    implementation (tests/testthat/test-reference-parity.R), covering
    deterministic kernels (Tier A, ≤ 1e-5) and clustering equivalence
    (Tier B, AMI).

Core Features

  - Core SONG algorithm implemented in C++ via RcppArmadillo.
  - Incremental data visualization via update().
  - Projection of new points via predict().
  - Base R plot() and optional ggplot2::autoplot() methods.
  - Supports 2D and 3D output embeddings.
  - print() and summary() methods with codebook and graph statistics.

Data and Visualization

  - Bundled songR_blobs dataset: 8-cluster, 20D synthetic data (1600
    points).
  - Viridis plasma color scale used throughout vignettes and tutorials.
  - All paper figures (Senanayake et al., 2021) reproducible via
    tutorial scripts.

Interactive App

  - Interactive Shiny app (run_songR_app()) for comparing SONG, t-SNE,
    and UMAP side-by-side.
  - Dark mode toggle with localStorage persistence.
  - Upload custom CSV/RDS data or use built-in datasets.
  - Full hyperparameter control, incremental update mode, and export
    options.

Vignettes and Tutorials

  - Two CRAN vignettes: "Introduction to songR" and "Getting Started
    with songR".
  - pkgdown articles: "Reproducing Paper Figures" and "Interactive Shiny
    App".
  - 13 tutorial scripts reproducing all figures and tables from
    Senanayake et al. (2021) on MNIST, Fashion-MNIST, Wong CyTOF (1.27M
    cells), COIL-20, and Samusik datasets.
  - Extra benchmarks: static AMI comparison, hyperparameter sensitivity
    sweeps, and runtime scaling analysis.