Overview
songR is a SONG-inspired dimensionality-reduction tool for R. It implements the Self-Organizing Nebulous Growths (SONG) algorithm of Senanayake et al. (2021) natively in R and C++ (no Python or reticulate), staying as close to the reference implementation as is feasible.
SONG’s key advantages over t-SNE and UMAP:
| Feature | SONG | t-SNE | UMAP |
|---|---|---|---|
| Incremental updates | Yes | No | No |
| Parametric model | Yes (codebook) | No | Optional |
| Noise robustness | High | Low | Medium |
| Global structure | Good | Poor | Good |
New data can be incorporated by continuing training from an existing model, making SONG useful for growing datasets and experiments where data arrives in batches. Updating can move the prototypes and their coordinates. Use predict() with the unchanged model when coordinates must remain in a frozen projection.
Fidelity to the reference implementation
songR is validated against the original Python SONG with a tiered set of golden-fixture parity tests. The honest, layer-by-layer picture:
-
Deterministic components (distances, nearest-coding-vector assignment, the rational-quadratic kernel
(a, b), growth thresholds) reproduce the reference to ≤ 1e-5 (the float32-vs-double floor). -
The core SONG embedding (
dispersion = FALSE) is statistically identical to the reference — e.g. AMI 0.949 = 0.949. -
The default visualization (
dispersion = TRUE) uses a stronger UMAP refinement than the reference’s gentle one. songR’s raw embedding is more collapsed on hard, multi-class data, so the stronger refinement is needed to use the full plane — and it matches or beats the reference’s AMI on every benchmarked dataset (MNIST, Fashion-MNIST, COIL-20, Samusik, Wong), while staying competitive with t-SNE and UMAP.
Bit-identical embeddings are neither targeted nor achievable (the reference is float32 + numba fastmath + two PRNG streams). See the reference-parity summary and the parity tests (tests/testthat/test-reference-parity.R) for the evidence.
Installation
# Install from CRAN (when available)
install.packages("songR")
# Or install the development version from GitHub
# install.packages("devtools")
devtools::install_github("cttir/songR")Key Features
Incremental Visualization
Train on an initial batch, then continue training with new data without initializing from scratch. An update creates a new model revision; reproject earlier observations with that revision before combining their coordinates:
# Train on first batch
model <- song(batch1, epochs = 20L, seed = 42)
# Add second batch -- prototype positions may change
model <- update(model, batch2, epochs = 20L)
# Get embedding for ALL points
emb <- predict(model, newdata = rbind(batch1, batch2))After an update, model$embedding and model$assignments describe the new batch only; model$n_input is the cumulative number of training observations. Plot colours for batch observations must follow the current batch, or supply one colour per prototype for a codebook plot. Save the model and its lineage with each exported projection.
Parametric Projection
Once trained, a SONG model can project unseen data without retraining:
new_coords <- predict(model, newdata = held_out_data)Bundled Dataset
songR ships with songR_blobs, a synthetic 8-cluster dataset in 20 dimensions for quick benchmarking:
When to Use SONG
- Incremental/streaming data: Data arrives in batches and you need a stable, growing visualization.
- Heterogeneous increments: New data may contain classes or structures not present in the original data.
- Noisy or mixed clusters: SONG is more tolerant to noise and cluster overlap than t-SNE.
- Parametric mapping: SONG retains a codebook model that can project new points without retraining.
- Large-scale cytometry/single-cell: SONG handles 1M+ cells incrementally with stable embeddings (see tutorials).
Vignettes and Tutorials
CRAN Vignettes
- Introduction to songR – Full overview of the API with iris and songR_blobs examples
- Getting Started with songR – Quick-start guide covering fitting, updating, predicting, and tuning
pkgdown Articles
- Reproducing Paper Figures – Reproduces key experiments from Senanayake et al. (2021) using songR (heterogeneous/homogeneous increments, CDY stability, noise tolerance, topology preservation, AMI scores)
- Interactive Shiny App – Guide to the built-in comparison app with dark mode
Full-Scale Tutorial Scripts
The tutorials/ directory contains scripts for full-scale reproduction of all paper figures and tables on real datasets (MNIST, Fashion-MNIST, Wong CyTOF 1.27M cells, COIL-20, Samusik):
| Script | Paper Figure | Dataset |
|---|---|---|
02_fig3_fashion_mnist_heterogeneous.R |
Fig. 3 | Fashion-MNIST (70k) |
03_fig4_mnist_heterogeneous.R |
Fig. 4 | MNIST (70k) |
04_fig5_wong_homogeneous.R |
Fig. 5 | Wong CyTOF (1.27M) |
05_fig6_cdy_lines.R |
Fig. 6 | Multiple |
06_fig7_table_IV_noise_tolerance.R |
Fig. 7 / Table IV | Gaussian blobs |
07_fig8_coil20_topology.R |
Fig. 8 | COIL-20 (1440) |
08_table_II_heterogeneous_ami.R |
Table II | Multiple |
09_table_III_homogeneous_ami.R |
Table III | Multiple |
11_extra_static_benchmark.R |
– | All datasets |
12_extra_hyperparam_sensitivity.R |
– | songR_blobs |
13_extra_runtime_benchmark.R |
– | Scaling test |
Run all tutorials:
Key Parameters
| Parameter | Default | Effect |
|---|---|---|
epochs |
50 | More = better convergence, slower |
epsilon |
0.9 | Edge decay rate (0–1); lower = sparser graph |
spread_factor |
0.5 | Growth threshold; higher = more coding vectors |
k |
3 | Neighborhood size for graph construction |
dispersion |
TRUE | UMAP refinement step for visual quality |
alpha |
1.0 | Initial learning rate |
Citation
If you use songR in published research, please cite both this R package and the underlying SONG algorithm:
R package:
Heller, R. (2026). songR: Self-Organizing Nebulous Growths for Dimensionality Reduction. R package version 1.0.0. https://github.com/cttir/songR
Underlying algorithm:
Senanayake, D. A., Wang, W., Naik, S. H., & Halgamuge, S. (2021). Self-Organizing Nebulous Growths for Robust and Incremental Data Visualization. IEEE Transactions on Neural Networks and Learning Systems, 32(10), 4588-4602. doi:10.1109/TNNLS.2020.3023941
citation("songR")Acknowledgments
This package is an independent R/C++ re-implementation of the SONG algorithm using RcppArmadillo. The original algorithm was developed by Damith Senanayake, Wei Wang, Shalin Naik, and Saman Halgamuge at the University of Melbourne. The original Python implementation is available at github.com/damithsenanayake/SONG.
License
MIT (c) Raban Heller
The SONG algorithm implemented here is derived from the reference implementation of Senanayake et al., which is licensed under the BSD 3-Clause License (© 2020 Damith A. Senanayake). The upstream copyright notice and license are reproduced verbatim in inst/COPYRIGHTS.
Use of LLM tools
Where applicable, LLM tools were used for narrowly defined, non-authorial tasks: copyediting, prose refinement, Markdown/LaTeX formatting, boilerplate scaffolding (such as CI configurations and build scripts), and code refactoring. Tools included Chat AI, the KISSKI (GWDG) service, and self-hosted Mistral Small (24B, Apache-2.0) served through a local vLLM architecture on an Ubuntu Linux workstation with Intel processors and NVIDIA GPUs. Self-hosted use also includes models that were further trained (fine-tuned) or weight-edited in-house for specific tasks. All self-hosted models ran locally, with no data sent to third parties.
All scientific claims, methodological choices, analyses, interpretations and conclusions remain the authors’ own. Where applicable, LLM-generated material must be reviewed and revised before inclusion, and references must be verified against their DOI, arXiv ID or ISBN.
Local software setup: vLLM with Python/PyTorch, plus R and RStudio.
Branding
Editable R artwork and regeneration instructions are in tools/branding.
