% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic_modeling.R
\name{fit_embedding_model}
\alias{fit_embedding_model}
\title{Fit Embedding-based Topic Model}
\usage{
fit_embedding_model(
  texts,
  method = "umap_hdbscan",
  n_topics = 10,
  embedding_model = "all-MiniLM-L6-v2",
  backend = "auto",
  clustering_method = "kmeans",
  similarity_threshold = 0.7,
  min_topic_size = 10,
  min_cluster_size = NULL,
  cluster_selection_method = "eom",
  umap_neighbors = 15,
  umap_min_dist = 0,
  umap_n_components = 5,
  umap_metric = "cosine",
  tsne_perplexity = 30,
  pca_dims = 50,
  dbscan_eps = 0.5,
  dbscan_minpts = 5,
  representation_method = "c-tfidf",
  diversity = 0.5,
  reduce_outliers = TRUE,
  outlier_strategy = "probabilities",
  outlier_threshold = 0,
  seed = 123,
  verbose = TRUE,
  precomputed_embeddings = NULL
)
}
\arguments{
\item{texts}{A character vector of texts to analyze.}

\item{method}{The topic modeling method:
\itemize{
\item For Python backend: "umap_hdbscan" (uses BERTopic)
\item For R backend: "umap_dbscan", "umap_kmeans", "umap_hierarchical",
"tsne_dbscan", "tsne_kmeans", "pca_kmeans", "pca_hierarchical"
\item For both: "embedding_clustering", "hierarchical_semantic"
}}

\item{n_topics}{The number of topics to identify. For UMAP+HDBSCAN, use NULL or "auto" for automatic determination, or specify an integer.}

\item{embedding_model}{The embedding model to use (default: "all-MiniLM-L6-v2").}

\item{backend}{The backend to use: "auto" (default, tries Python then R),
"python" (requires BERTopic), or "r" (R-native packages only).}

\item{clustering_method}{The clustering method for embedding-based approach: "kmeans", "hierarchical", "dbscan", "hdbscan".}

\item{similarity_threshold}{The similarity threshold for topic assignment (default: 0.7).}

\item{min_topic_size}{The minimum number of documents per topic (default: 3).}

\item{min_cluster_size}{HDBSCAN density threshold (default \code{NULL} falls back to \code{min_topic_size}). Setting this independently lets fine-grained clusters merge into broader topics.}

\item{cluster_selection_method}{HDBSCAN cluster selection method: "eom" (Excess of Mass, default) or "leaf" (finer-grained topics).}

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

\item{umap_min_dist}{The minimum distance for UMAP (default: 0.0). Use 0.0 for tight, well-separated clusters. Use 0.1+ for visualization purposes. Range: 0.0-0.99.}

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

\item{umap_metric}{Distance metric for UMAP: "cosine" (recommended for text) or "euclidean" (default: "cosine").}

\item{tsne_perplexity}{Perplexity parameter for t-SNE (default: 30). Only used when method includes "tsne"; t-SNE output is 2-dimensional.}

\item{pca_dims}{Number of PCA components kept for clustering (default: 50). Only used when method includes "pca".}

\item{dbscan_eps}{Epsilon parameter for DBSCAN (default: 0.5). Neighborhood size for density-based clustering.}

\item{dbscan_minpts}{Minimum points for DBSCAN core points (default: 5).}

\item{representation_method}{The method for topic representation: "c-tfidf", "tfidf", "mmr", "frequency" (default: "c-tfidf").
Applies only to the R fallback backend and the "embedding_clustering",
"semantic_lda", and "hierarchical_semantic" methods; the Python BERTopic
backend ("umap_hdbscan") uses BERTopic's native c-TF-IDF representation.}

\item{diversity}{Diversity weight between 0 and 1 for the "mmr"
representation (default: 0.5). Higher values penalize redundant terms
more strongly. Applies to the R backend; ignored by the Python BERTopic
backend.}

\item{reduce_outliers}{Logical, if TRUE, reduces outliers in HDBSCAN clustering (default: TRUE).}

\item{outlier_strategy}{Strategy for outlier reduction using BERTopic:
"probabilities" (default, uses topic probabilities), "c-tf-idf" (uses
c-TF-IDF similarity), "embeddings" (uses cosine similarity in embedding
space), or "distributions" (uses topic distributions). Ignored if
reduce_outliers = FALSE.}

\item{outlier_threshold}{Minimum threshold for outlier reassignment (default: 0.0).
Higher values require stronger evidence for reassignment.}

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

\item{verbose}{Logical, if TRUE, prints progress messages.}

\item{precomputed_embeddings}{Optional matrix of pre-computed document embeddings.
If provided, skips embedding generation for improved performance. Must have
the same number of rows as the length of texts.}
}
\value{
A list containing topic assignments, topic keywords, and quality metrics.
}
\description{
This function performs embedding-based topic modeling using transformer embeddings
and specialized clustering techniques. Supports two backends:
\itemize{
\item \strong{Python backend} (default): Uses BERTopic library which combines transformer
embeddings with UMAP dimensionality reduction and HDBSCAN clustering for optimal
topic discovery.
\item \strong{R backend}: Uses R-native packages (umap, dbscan, Rtsne) for users without
Python/BERTopic installed. Provides similar functionality with c-TF-IDF keyword
extraction.
}
}
\examples{
if (interactive()) {
  mydata <- TextAnalysisR::SpecialEduTech
  united_tbl <- TextAnalysisR::unite_cols(
    mydata,
    listed_vars = c("title", "keyword", "abstract")
  )
  texts <- united_tbl$united_texts

  # Embedding-based topic modeling (powered by BERTopic)
  result <- TextAnalysisR::fit_embedding_model(
    texts = texts,
    method = "umap_hdbscan",
    n_topics = 8,
    min_topic_size = 3
  )

  print(result$topic_assignments)
  print(result$topic_keywords)
}
}
\seealso{
\code{\link[=get_best_embeddings]{get_best_embeddings()}} to supply precomputed embeddings; \code{\link[=generate_topic_labels]{generate_topic_labels()}} for AI-suggested topic names; \code{\link[=find_optimal_k]{find_optimal_k()}} for an STM-based alternative
}
\concept{topic-modeling}
