% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nuggets.R
\name{create_data_nuggets}
\alias{create_data_nuggets}
\title{Create data nuggets from a data matrix}
\usage{
create_data_nuggets(
  x,
  max_nuggets = NULL,
  min_size = 1L,
  engine = c("native", "datanugget"),
  scale_features = TRUE,
  seed = NULL,
  ...
)
}
\arguments{
\item{x}{A numeric matrix or data frame with observations in the \emph{rows}
and variables in the \emph{columns}.}

\item{max_nuggets}{Target (maximum) number of nuggets \eqn{M}. Defaults to a
data-driven value (see Details). Ignored when \code{engine = "datanugget"}.}

\item{min_size}{Minimum number of observations per nugget (native engine
only). Defaults to \code{1}.}

\item{engine}{Either \code{"native"} (a self-contained k-means based
partition, no extra dependencies) or \code{"datanugget"} (delegates to the
\pkg{datanugget} package via \code{datanugget::create.DN} /
\code{datanugget::refine.DN} when it is installed).}

\item{scale_features}{Logical; if \code{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.}

\item{seed}{Optional integer seed for reproducible partitioning.}

\item{...}{Additional arguments forwarded to
\code{datanugget::create.DN} when \code{engine = "datanugget"}.}
}
\value{
An object of class \code{"data_nugget"}: a list with elements
\item{centers}{\eqn{M \times p} matrix of nugget centres.}
\item{weights}{Length-\eqn{M} integer vector of nugget sizes \eqn{n_i}.}
\item{scales}{\eqn{M \times p} matrix of within-nugget variances.}
\item{membership}{Length-\eqn{n} integer vector mapping each observation to
its nugget.}
\item{x_scale}{Length-\eqn{M} vector of total within-nugget variability
\eqn{\mathrm{tr}(\mathrm{Cov})}.}
\item{engine}{The engine used.}
}
\description{
\code{create_data_nuggets} compresses \code{n} observations into
\code{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.
}
\details{
With the native engine the number of nuggets defaults to
\code{min(nrow(x), max(2, floor(nrow(x) / 10)))} when \code{n > 50}, and to
\code{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 \code{stats::kmeans};
missing values are mean-imputed for the partition step only.
}
\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
}
\references{
\insertRef{Cherasia2023}{MosaiClusteR}

\insertRef{WCluster2025}{MosaiClusteR}
}
\seealso{
\code{\link{nugget_feature_weights}}, \code{\link{M_ABCpp}}
}
