Package 'songR'

Autoplot Method for SONG Models

Description

Creates a ggplot2 plot of a "song_model" object. Requires ggplot2 to be installed.

Usage

autoplot.song_model(
  object,
  type = c("embedding", "codebook", "graph"),
  color_by = NULL,
  ...
)

Arguments

object	A "song_model" object.
type	Character. One of "embedding", "codebook", or "graph".
color_by	Optional vector for coloring points.
...	Ignored.

Value

A ggplot object.

References

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

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  model <- song(as.matrix(iris[, 1:4]), epochs = 5L, seed = 42)
  # Use songR::autoplot.song_model(model, color_by = iris$Species)
  # or ensure songR is loaded with library(songR) for dispatch
}

---

Plot a SONG Model

Description

Visualize a "song_model" as a scatter plot of the embedding, the codebook, or the codebook graph with edges.

Usage

## S3 method for class 'song_model'
plot(x, type = c("embedding", "codebook", "graph"), color_by = NULL, ...)

Arguments

x	A "song_model" object.
type	Character. One of "embedding" (all input points in embedding space), "codebook" (coding vectors only), or "graph" (coding vectors with edges drawn). Default: "embedding".
color_by	Optional vector (factor or numeric) of length equal to the number of input points (for "embedding") or coding vectors (for "codebook" and "graph") used to color the points.
...	Additional arguments passed to plot.

Value

Invisible NULL.

References

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

See Also

song, autoplot.song_model

Examples

model <- song(as.matrix(iris[, 1:4]), epochs = 5L, seed = 42)
plot(model, color_by = iris$Species)

---

Project New Points into a SONG Embedding

Description

Maps new data points into an existing SONG embedding by assigning each point to its nearest coding vector and returning that coding vector's embedding coordinates. This does not train or mutate the model. Multiple points assigned to one prototype have identical coordinates; these coordinates are not physical locations or evidence of contact.

Usage

## S3 method for class 'song_model'
predict(object, newdata, ..., feature_manifest = NULL)

Arguments

object	A trained "song_model" object.
newdata	Numeric matrix of new data (n_new x D).
...	Ignored.
feature_manifest	The unchanged manifest supplied at training, if any. Named features must follow training order. See song() for the contract.

Value

A numeric matrix (n_new x d) of embedding coordinates.

References

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

See Also

song, update.song_model

Examples

model <- song(as.matrix(iris[1:120, 1:4]), epochs = 5L, seed = 42)
new_coords <- predict(model, newdata = as.matrix(iris[121:150, 1:4]))

---

Print a SONG Model

Description

Prints a concise summary of a "song_model" object.

Usage

## S3 method for class 'song_model'
print(x, ...)

Arguments

x	A "song_model" object.
...	Ignored.

Value

Invisible x.

References

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

Examples

model <- song(as.matrix(iris[, 1:4]), epochs = 5L, seed = 42)
print(model)

---

Launch Interactive Comparison App

Description

Opens a Shiny application that compares SONG, t-SNE, and UMAP visualizations side-by-side on user-supplied or example data. The app features a dark mode toggle (persisted via localStorage), uses the viridis plasma color scale for all plots, and supports uploading custom CSV/RDS data, tuning SONG hyperparameters, running incremental updates, and exporting embeddings.

Usage

run_songR_app(launch.browser = TRUE)

Arguments

launch.browser

Logical. Whether to open the app in the browser (default: TRUE).

Value

Invisible NULL. The function is called for its side effect of launching the Shiny app.

References

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

Examples

if (interactive()) {
  run_songR_app()
}

---

Fit a SONG Model for Dimensionality Reduction

Description

Performs nonlinear dimensionality reduction using the Self-Organizing Nebulous Growths (SONG) algorithm. SONG builds a codebook of coding vectors connected by a topology-preserving graph, then maps the graph into a low-dimensional embedding space. Unlike t-SNE and UMAP, the resulting model supports incremental updates with new data via update.song_model.

Usage

song(
  X,
  d = 2L,
  k = 3L,
  epsilon = 0.9,
  epochs = 50L,
  alpha = 1,
  a = 1.577,
  b = 0.895,
  spread_factor = 0.5,
  neg_sample_rate = 5L,
  max_age = 3L,
  e_min = NULL,
  max_prototypes = NULL,
  lr_sigma = 5,
  dispersion = TRUE,
  seed = NULL,
  verbose = TRUE,
  feature_manifest = NULL
)

Arguments

X	Numeric matrix of input data (n x D), or a data.frame with all numeric columns (will be coerced to matrix).
d	Integer. Output dimensionality (default: 2).
k	Integer. Neighborhood size for the coding-vector graph. Corresponds to dim + n_neighbors in the Python reference. Must be >= d + 1 (default: 3, which matches Python's n_neighbors = 1 with dim = 2).
epsilon	Numeric. Edge decay rate, in (0, 1) (default: 0.9). Lower values produce sparser, faster-pruning graphs.
epochs	Integer. Number of self-organisation iterations (default: 50, matching Python's so_steps).
alpha	Numeric. Initial SO learning rate (default: 1.0).
a	Numeric. Rational-quadratic kernel parameter (default: 1.577, from find_spread_tightness(spread=1, min_dist=0.1)).
b	Numeric. Rational-quadratic kernel parameter (default: 0.895).
spread_factor	Numeric. Controls growth threshold $\theta = -\ln(D) \cdot \ln(\mathrm{sf})$; higher values produce more coding vectors. In (0, 1) (default: 0.5).
neg_sample_rate	Integer. Number of negative samples per positive edge during repulsion (default: 5).
max_age	Integer. Controls automatic edge pruning: edges weaker than epsilon^(d + max_age) are removed (default: 3).
e_min	Numeric or NULL. Minimum edge strength below which edges are pruned. NULL (default) auto-computes as epsilon^(d + max_age), matching the Python reference.
max_prototypes	Integer or NULL. Maximum number of coding vectors. NULL (default) auto-computes as floor(exp(log(n) / 1.5)), matching the Python reference.
lr_sigma	Numeric. Decay constant for the SO learning-rate schedule: so_lr = alpha * exp(-lr_sigma * (epoch/epochs)^2). Default: 5.0 (matches Python).
dispersion	Logical. If TRUE (default) and uwot is available, runs a short UMAP refinement step initialised from the SONG embedding. This matches the Python reference implementation's transform() method and dramatically improves visual cluster separation.
seed	Integer or NULL. Random seed for reproducibility.
verbose	Logical. Whether to print progress per epoch (default: TRUE).
feature_manifest	Optional data frame with exactly these character columns, in order: feature, compartment, statistic, unit, transform, normalization. Rows must follow the named input columns. Describe complete externally applied transform/normalization recipes, including parameters or a versioned reference identifier; use "identity"/"none" when applicable. The manifest records declarations; it does not apply transformations or establish that supplied measurements have the declared physical meaning.

Details

Named training columns are bound in exact order and must also be named in prediction and updates. An explicit manifest must be supplied again, unchanged, to predict or update a model trained with one. Missing/nonfinite measurements are rejected; no feature is silently reordered or imputed. Unnamed training data retains positional compatibility and cannot verify feature semantics. Legacy models without a contract also retain positional behavior.

Value

An S3 object of class "song_model" containing:

Y

Embedding coordinates of coding vectors (n_coding x d).

C

Coding vectors (n_coding x D).

E

Directed adjacency matrix (n_coding x n_coding).

E_s

Symmetric adjacency matrix.

assignments

Integer vector of length n: nearest CV index.

embedding

Embedding coordinates for all input points (n x d).

parameters

List of all hyperparameters used.

feature_contract

Versioned feature order, declared metadata and missing-value policy.

lineage

Projection version, parent identifier and reprojection policy.

n_epochs

Number of epochs actually run.

References

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

See Also

update.song_model, predict.song_model, plot.song_model

Examples

model <- song(as.matrix(iris[, 1:4]), epochs = 5L, seed = 42)
plot(model, color_by = iris$Species)

---

Simulated Gaussian Blobs Dataset

Description

A list containing a simulated dataset of 1600 points in 20 dimensions, organized into 8 Gaussian clusters. Designed for benchmarking and demonstrating dimensionality reduction methods.

Usage

songR_blobs

Format

A list with three elements:

data

Numeric matrix (1600 x 20) of simulated features.

labels

Factor of length 1600 indicating cluster membership.

description

Character string describing the dataset.

Source

Simulated data inspired by the experimental setup in Senanayake et al. (2021) doi:10.1109/TNNLS.2020.3023941.

Examples

data(songR_blobs)
str(songR_blobs)

---

Summarize a SONG Model

Description

Provides a detailed summary of a "song_model" object, including quantization error and edge statistics.

Usage

## S3 method for class 'song_model'
summary(object, ...)

Arguments

object	A "song_model" object.
...	Ignored.

Value

Invisible object.

References

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

Examples

model <- song(as.matrix(iris[, 1:4]), epochs = 5L, seed = 42)
summary(model)

---

Incrementally Update a SONG Model with New Data

Description

Adds new data to an existing SONG model. This is the key differentiator of SONG over t-SNE and UMAP: training continues from the existing model. Coding vectors, edges and embedding positions may change. The supplied object is unchanged; use predict.song_model() for frozen projection.

Usage

## S3 method for class 'song_model'
update(
  object,
  X_new,
  epochs = 50L,
  alpha = NULL,
  verbose = TRUE,
  ...,
  feature_manifest = NULL,
  seed = NULL
)

Arguments

object	A "song_model" object to update.
X_new	Numeric matrix of new data (n_new x D). Must have the same number of columns as the original training data.
epochs	Integer. Number of additional training epochs (default: 50).
alpha	Numeric or NULL. Initial learning rate for the update. If NULL, uses the original learning rate (default: NULL).
verbose	Logical. Whether to print progress (default: TRUE).
...	Ignored.
feature_manifest	The unchanged manifest supplied at training, if any. Named features must follow training order. See song() for the contract.
seed	Optional integer seed for update training. NULL preserves the existing random-stream behavior; the original fit seed is not reused.

Details

lineage schema 1.0.0 records a revision, a deterministic SHA-256 model identifier and its parent identifier. Identifiers bind the ordered projection codebook, coordinates, feature contract and revision ancestry, not the full training history or authenticity of a manually modified object. Each update requires reprojection of all earlier observations with the new model before combining coordinates. Earlier input rows are not retained or automatically reprojected. Initial revisions start at 1. Updates to legacy models start a new revision history at 1 with parent_history set to legacy_unversioned and a parent projection fingerprint. Save the model together with any exported projection to retain its version. Coincident embedding positions reflect prototype assignment; they do not establish cell contact or physical spatial distance.

Value

An updated "song_model" object with grown codebook incorporating the new data. embedding and assignments describe only X_new; n_input counts all training rows across updates.

References

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

See Also

song, predict.song_model

Examples

model <- song(as.matrix(iris[1:100, 1:4]), epochs = 5L, seed = 42)
model <- update(model, as.matrix(iris[101:150, 1:4]), epochs = 5L)

---