create_data_nuggets: Create data nuggets from a data matrix

In MosaiClusteR: An Umbrella Framework for Multi-Source and Multi-Omics Clustering

Create data nuggets from a data matrix

Description

create_data_nuggets compresses n observations into M <= n representative "nuggets". Each nugget stores a centre (location), a weight (the number of member observations) and a scale (within-nugget variability). Data nuggets preserve the covariance structure of the data - including the periphery - far better than a random sub-sample, which makes them a robust, memory-light surrogate for the full data set when clustering or computing feature weights.

Usage

create_data_nuggets(
  x,
  max_nuggets = NULL,
  min_size = 1L,
  engine = c("native", "datanugget"),
  scale_features = TRUE,
  seed = NULL,
  ...
)

Arguments

x	A numeric matrix or data frame with observations in the rows and variables in the columns.
max_nuggets	Target (maximum) number of nuggets M. Defaults to a data-driven value (see Details). Ignored when engine = "datanugget".
min_size	Minimum number of observations per nugget (native engine only). Defaults to 1.
engine	Either "native" (a self-contained k-means based partition, no extra dependencies) or "datanugget" (delegates to the datanugget package via datanugget::create.DN / datanugget::refine.DN when it is installed).
scale_features	Logical; if TRUE (default) the partition is computed on standardised features so that no single high-variance variable dominates the nugget assignment. Centres and scales are always reported on the original scale.
seed	Optional integer seed for reproducible partitioning.
...	Additional arguments forwarded to datanugget::create.DN when engine = "datanugget".

Details

With the native engine the number of nuggets defaults to min(nrow(x), max(2, floor(nrow(x) / 10))) when n > 50, and to n otherwise (in which case every observation is its own nugget and the nugget-weighted variance reduces to the ordinary variance - a safe fallback for small samples). The partition is obtained with stats::kmeans; missing values are mean-imputed for the partition step only.

Value

An object of class "data_nugget": a list with elements

centers	M \times p matrix of nugget centres.
weights	Length-M integer vector of nugget sizes n_i.
scales	M \times p matrix of within-nugget variances.
membership	Length-n integer vector mapping each observation to its nugget.
x_scale	Length-M vector of total within-nugget variability \mathrm{tr}(\mathrm{Cov}).
engine	The engine used.

References

\insertRef

Cherasia2023MosaiClusteR

\insertRef

WCluster2025MosaiClusteR

See Also

nugget_feature_weights, M_ABC

Examples

set.seed(1)
x <- rbind(matrix(rnorm(200 * 5,  0), ncol = 5),
           matrix(rnorm(200 * 5,  4), ncol = 5))
dn <- create_data_nuggets(x, max_nuggets = 40)
dn

MosaiClusteR documentation built on Oct. 25, 2026, 1:08 a.m.