% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/semantic_analysis.R
\name{cluster_embeddings}
\alias{cluster_embeddings}
\title{Embedding-based Document Clustering}
\usage{
cluster_embeddings(
  data_matrix,
  method = "kmeans",
  n_clusters = 0,
  umap_neighbors = 15,
  umap_min_dist = 0.1,
  umap_n_components = 10,
  umap_metric = "cosine",
  dbscan_eps = 0,
  dbscan_min_samples = NULL,
  reduce_outliers = TRUE,
  outlier_strategy = "centroid",
  outlier_threshold = 0,
  seed = 123,
  verbose = TRUE
)
}
\arguments{
\item{data_matrix}{A numeric matrix where rows represent documents and
columns represent features.}

\item{method}{The clustering method. Options: "kmeans", "hierarchical",
"umap_dbscan".}

\item{n_clusters}{The number of clusters (for k-means and hierarchical).
If 0, optimal number is determined automatically.}

\item{umap_neighbors}{The number of neighbors for UMAP (default: 15).}

\item{umap_min_dist}{The minimum distance for UMAP (default: 0.1).}

\item{umap_n_components}{The number of UMAP components (default: 10).}

\item{umap_metric}{The metric for UMAP (default: "cosine").}

\item{dbscan_eps}{The eps parameter for DBSCAN. If 0, optimal value is determined automatically.}

\item{dbscan_min_samples}{The minimum samples for DBSCAN. Default NULL sets
\code{umap_n_components + 1} (dimensions-plus-one rule of thumb).}

\item{reduce_outliers}{Logical, if TRUE, reassigns noise points (cluster 0) to nearest cluster (default: TRUE).
Set FALSE to keep density-based noise labels.}

\item{outlier_strategy}{Strategy for outlier reduction: "centroid" (default,
Euclidean nearest-centroid in UMAP space; package-specific heuristic) or
"embeddings" (cosine similarity to cluster mean in original embedding
space, matching the BERTopic "embeddings" strategy).}

\item{outlier_threshold}{Minimum similarity for reassigning a noise point
(default: 0, reassign all). For "embeddings" this is cosine similarity;
for "centroid" it applies to 1 / (1 + euclidean distance). Points below
the threshold keep cluster label 0.}

\item{seed}{Random seed for reproducibility (default: 123).}

\item{verbose}{Logical, if TRUE, prints progress messages.}
}
\value{
A list containing cluster assignments, method used, and quality metrics.
For \code{method = "umap_dbscan"} with \code{reduce_outliers = TRUE}, the list
also reports how noise points were reassigned: \code{outlier_strategy}
("embeddings" or "centroid"), \code{outlier_metric} ("cosine" or "euclidean"),
\code{outlier_space} ("original embedding space" or "UMAP space"), and
\code{outliers_reassigned} (count).
}
\description{
This function performs clustering analysis using various methods, ordered
from simple to detailed:
k-means (simplest), hierarchical (intermediate), and UMAP+DBSCAN
(most detailed).
}
\examples{
if (interactive()) {
  mydata <- TextAnalysisR::SpecialEduTech

  united_tbl <- TextAnalysisR::unite_cols(
    mydata,
    listed_vars = c("title", "keyword", "abstract")
  )

  tokens <- TextAnalysisR::prep_texts(united_tbl, text_field = "united_texts")

  dfm_object <- quanteda::dfm(tokens)

  data_matrix <- as.matrix(dfm_object)

  kmeans_result <- TextAnalysisR::cluster_embeddings(
    data_matrix,
    method = "kmeans",
    n_clusters = 5
  )
  print(kmeans_result)

  hierarchical_result <- TextAnalysisR::cluster_embeddings(
    data_matrix,
    method = "hierarchical",
    n_clusters = 5
  )
  print(hierarchical_result)

  umap_dbscan_result <- TextAnalysisR::cluster_embeddings(
    data_matrix,
    method = "umap_dbscan",
    umap_neighbors = 15,
    umap_min_dist = 0.1
  )
  print(umap_dbscan_result)
}
}
\concept{semantic}
