NEWS

---

songR 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.