% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utilities.R
\name{aggregate_to_symbolic}
\alias{aggregate_to_symbolic}
\title{Aggregate Tabular Data to Symbolic Data}
\usage{
aggregate_to_symbolic(x, type = "int", group_by = "kmeans",
  stratify_var = NULL, K = 5, interval = "range",
  quantile_probs = c(0.05, 0.95), bins = 10, nK = NULL,
  zero_width = c("keep", "remove", "regenerate", "adjust"), epsilon = 1e-07)
}
\arguments{
\item{x}{A data.frame with n rows and p columns. May contain non-numeric
columns used for grouping or stratification; only numeric columns are
aggregated.}

\item{type}{Output symbolic type: \code{"int"} for interval data or
\code{"hist"} for histogram data.}

\item{group_by}{Grouping mechanism. One of:
\describe{
  \item{\code{"kmeans"}}{Partition the data into \code{K} groups using
    k-means clustering.}
  \item{\code{"hclust"}}{Partition the data into \code{K} groups using
    hierarchical clustering.}
  \item{\code{"resampling"}}{Generate \code{K} concepts by randomly
    sampling \code{nK} observations with replacement, repeated \code{K}
    times.}
  \item{A column name or column index}{Use the specified categorical
    variable to define groups.}
}}

\item{stratify_var}{Optional column name or index for a stratification
variable. When provided, grouping and aggregation are performed
independently within each level. Default is \code{NULL}.}

\item{K}{Number of groups for clustering (\code{group_by = "kmeans"} or
\code{"hclust"}) or resampling (\code{group_by = "resampling"}).
Ignored when \code{group_by} is a variable. Default is 5.}

\item{interval}{Interval construction method when \code{type = "int"}:
\code{"range"} uses min/max; \code{"quantile"} uses quantiles given by
\code{quantile_probs}. Default is \code{"range"}.}

\item{quantile_probs}{Numeric vector of length 2 giving the lower and upper
quantile probabilities for \code{interval = "quantile"}.
Default is \code{c(0.05, 0.95)}.}

\item{bins}{Number of histogram bins when \code{type = "hist"}.
Default is 10.}

\item{nK}{Number of observations to sample per group when
\code{group_by = "resampling"}. Default is \code{floor(n / K)}.}

\item{zero_width}{How to handle zero-width intervals (\code{min == max})
produced when \code{type = "int"}. Such degenerate intervals break
downstream tools that divide by interval width (e.g.
\code{ggInterval::ggInterval_indexImage()}). One of:
\describe{
  \item{\code{"keep"}}{(default) Leave the aggregated output unchanged;
    zero-width intervals are returned as-is and no action is taken. Use
    \code{\link{check_zero_width_intervals}} to screen the result.}
  \item{\code{"remove"}}{Drop every concept (row) that contains
    at least one zero-width interval.}
  \item{\code{"regenerate"}}{Re-run the aggregation (re-clustering or
    re-sampling) until no zero-width interval remains. Only effective for
    stochastic \code{group_by} (\code{"kmeans"}, \code{"resampling"});
    for deterministic grouping (a variable or \code{"hclust"}) the result
    cannot change, so an error is raised suggesting another option.}
  \item{\code{"adjust"}}{Add a small amount \code{epsilon} to the upper
    endpoint of each zero-width interval.}
}
Ignored when \code{type = "hist"}.}

\item{epsilon}{Positive amount added to the upper endpoint of each
zero-width interval when \code{zero_width = "adjust"}. Default is
\code{1e-07}.}
}
\value{
\itemize{
  \item For \code{type = "int"}: a \code{symbolic_tbl} (RSDA format) with
    a label column followed by \code{symbolic_interval} columns for each
    numeric variable (K rows, 1 + p columns).
  \item For \code{type = "hist"}: a \code{\link[HistDAWass]{MatH}} object
    (K rows by p columns of histogram-valued data).
}
}
\description{
Aggregate tabular numerical data (n by p) into interval-valued
or histogram-valued symbolic data (K by p) based on a grouping mechanism.
}
\details{
The function aggregates classical tabular data into symbolic data by:
\enumerate{
  \item Partitioning observations into groups via \code{group_by}
    (clustering, resampling, or a categorical variable).
  \item Within each group, summarizing each numeric variable as an
    interval (min/max or quantiles) or a histogram.
}

When \code{stratify_var} is provided, grouping and aggregation are performed
within each level of the stratification variable. Label values are prefixed
by the stratum name (e.g., \code{"setosa.cluster_1"}).

For \code{type = "hist"}, bin boundaries are computed from the global data
range to ensure comparability across groups.

Non-numeric columns (other than those used for grouping or stratification)
are silently excluded from aggregation.
}
\examples{
# Group by a categorical variable -> interval data
res1 <- aggregate_to_symbolic(iris, type = "int", group_by = "Species")
res1

# K-means clustering -> interval data
res2 <- aggregate_to_symbolic(iris[, 1:4], type = "int",
                               group_by = "kmeans", K = 3)

# Quantile-based intervals
res3 <- aggregate_to_symbolic(iris[, 1:4], type = "int",
                               group_by = "kmeans", K = 3,
                               interval = "quantile",
                               quantile_probs = c(0.1, 0.9))

# Resampling -> interval data
set.seed(42)
res4 <- aggregate_to_symbolic(iris[, 1:4], type = "int",
                               group_by = "resampling", K = 5, nK = 30)

# Histogram aggregation
res5 <- aggregate_to_symbolic(iris, type = "hist",
                               group_by = "Species", bins = 5)

# Hierarchical clustering -> interval data
res6 <- aggregate_to_symbolic(iris[, 1:4], type = "int",
                               group_by = "hclust", K = 3)

# Stratified aggregation
res7 <- aggregate_to_symbolic(iris, type = "int",
                               group_by = "kmeans", K = 2,
                               stratify_var = "Species")

}
