Skip to contents

Changelog

Source: NEWS.md

songR (development version)

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

songR 0.1.0

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