Embedding-based models¶
These models start from document (and sometimes word) vectors the user supplies
from any embedder, rather than from word counts. They present the same
topic_word (φ) / doc_topic (θ) surface as the count-based models, so the
diagnostic, labeling, and reporting tools apply to them unchanged. See the
embedding topics guide for a worked walkthrough.
BERTopic and Top2Vec cluster the embeddings; ETM and FASTopic are
generative models that factor topics through the embedding space. None require
PyTorch: fit takes the vectors you pass in.
topica.BERTopic ¶
BERTopic: the same reduce/cluster pipeline as Top2Vec, but topics are
defined by class-based TF-IDF over their documents' words, so no word
embeddings are needed. nr_topics merges the most similar topics down to a
target count; doc_topic is the approximate distribution (a sliding window's
c-TF-IDF compared to each topic) — except with clusterer="gmm" (and no
nr_topics), where it is the GMM's soft posterior membership. You bring the
document embeddings.
No embedder of your own? topica.llm_embed(texts, model=...) builds the
matrix (OpenAI, or offline sentence-transformers).
__doc__
class-attribute
¶
__doc__ = 'BERTopic: the same reduce/cluster pipeline as `Top2Vec`, but topics are\ndefined by class-based TF-IDF over their documents\' words, so no word\nembeddings are needed. `nr_topics` merges the most similar topics down to a\ntarget count; `doc_topic` is the approximate distribution (a sliding window\'s\nc-TF-IDF compared to each topic) — except with `clusterer="gmm"` (and no\n`nr_topics`), where it is the GMM\'s soft posterior membership. You bring the\ndocument embeddings.\n\nNo embedder of your own? `topica.llm_embed(texts, model=...)` builds the\nmatrix (OpenAI, or offline `sentence-transformers`).'
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
__module__
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
converged
property
¶
BERTopic is not an iterative sampler (UMAP + clustering); converged is always None.
settings
property
¶
The constructor configuration as a JSON-serialisable dict, keyword-named
to match __init__ (issue #400). Internal flags are reported under
their public names (reducer, metric); values are the effective
ones actually in force (e.g. window/stride after their .max(1)
floor, min_samples after its min_cluster_size default).
__new__
builtin
¶
Create and return a new object. See help(type) for accurate signature.
approximate_distribution
method descriptor
¶
The soft topic distribution for data (Corpus or token lists), as
(num_docs, num_topics). Words outside the fitted vocabulary are dropped;
window/stride default to the values set on the model.
coherence
method descriptor
¶
UMass coherence for each topic's top-n words, over the training corpus.
fit
method descriptor
¶
Fit on data (a Corpus or list of token lists) with doc_embeddings
((num_docs, E)), one row per document. No word embeddings are needed.
fit_transform
method descriptor
¶
Fit, then return the document-topic distribution (fit_transform).
doc_embeddings is the (num_docs, embedding_dim) embedding matrix,
one row per document in corpus order.
merge_topics
method descriptor
¶
Merge groups of topics into single topics, e.g. [[3, 7], [1, 2]],
rebuilding the c-TF-IDF representation and the document-topic distribution.
reduce_outliers
method descriptor
¶
Reassign noise documents (label -1) to their nearest topic by c-TF-IDF
fit and rebuild. Returns how many documents were reassigned.
save
method descriptor
¶
Save the fitted model to path (topica's binary format), so a discovered
fit can be reloaded and reused without refitting (useful with the stochastic
reducer="umap" discovery).
top_words
method descriptor
¶
Top n words of topic (or every topic when None) by c-TF-IDF weight.
transform
method descriptor
¶
Soft topic distribution for new documents (the approximate distribution
over their words). BERTopic reads topics from text; doc_embeddings is
accepted but not used (for API consistency with the other embedding
models). Returns (num_docs, num_topics).
topica.Top2Vec ¶
Top2Vec: topics by clustering document embeddings. We reduce the document embeddings (randomized PCA), density-cluster them (HDBSCAN), and read each topic off its cluster: the topic vector is the mean of its documents' embeddings, and its words are the vocabulary terms nearest that vector.
You bring the embeddings. fit(data, doc_embeddings) needs one embedding row
per document; pass word_embeddings with the aligned vocabulary (same
space) to also get topic_neighbors. The topic count is discovered, not set.
Top2Vec and BERTopic share the class-based TF-IDF topic_word matrix, so
their topic_word / topic_table are the same given the same clusters. What
makes Top2Vec distinct is the centroid representation — the vocabulary
nearest the cluster centroid in embedding space — which top_words returns by
default when word_embeddings are present (pass representation="c-tf-idf"
for the shared view, or read it from topic_neighbors).
No embedder of your own? topica.llm_embed(texts, model=...) builds the
matrix (OpenAI, or offline sentence-transformers).
__doc__
class-attribute
¶
__doc__ = 'Top2Vec: topics by clustering document embeddings. We reduce the document\nembeddings (randomized PCA), density-cluster them (HDBSCAN), and read each\ntopic off its cluster: the topic vector is the mean of its documents\'\nembeddings, and its words are the vocabulary terms nearest that vector.\n\nYou bring the embeddings. `fit(data, doc_embeddings)` needs one embedding row\nper document; pass `word_embeddings` with the aligned `vocabulary` (same\nspace) to also get `topic_neighbors`. The topic count is discovered, not set.\n\n`Top2Vec` and `BERTopic` share the class-based TF-IDF `topic_word` matrix, so\ntheir `topic_word` / `topic_table` are the same given the same clusters. What\nmakes Top2Vec distinct is the **centroid** representation — the vocabulary\nnearest the cluster centroid in embedding space — which `top_words` returns by\ndefault when `word_embeddings` are present (pass `representation="c-tf-idf"`\nfor the shared view, or read it from `topic_neighbors`).\n\nNo embedder of your own? `topica.llm_embed(texts, model=...)` builds the\nmatrix (OpenAI, or offline `sentence-transformers`).'
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
__module__
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
converged
property
¶
Top2Vec is not an iterative sampler (UMAP + clustering); converged is always None.
doc_topic
property
¶
Soft document-topic membership ((num_docs, num_topics)), rows sum to one.
labels
property
¶
Hard cluster assignment per document; -1 is a noise document with no topic.
settings
property
¶
The constructor configuration as a JSON-serialisable dict, keyword-named
to match __init__ (issue #400). Internal flags are reported under
their public names (reducer, metric); values are the effective
ones actually in force (e.g. min_samples after its
min_cluster_size default).
topic_vectors
property
¶
Each topic's vector in the embedding space ((num_topics, E)).
topic_word
property
¶
Topic-word distribution from class-based TF-IDF, row-normalized
((num_topics, vocab)).
__new__
builtin
¶
Create and return a new object. See help(type) for accurate signature.
coherence
method descriptor
¶
Soft topic membership for new documents from their embeddings (cosine to
each topic vector, normalized). data is accepted for API symmetry but
Top2Vec assigns by embedding only. Returns (num_docs, num_topics).
UMass topic coherence per topic, shape (num_topics,). n is the number
of top words per topic scored.
fit
method descriptor
¶
Fit on data (a Corpus or list of token lists) with doc_embeddings
((num_docs, E)), one row per document. Pass word_embeddings
((len(vocabulary), E)) and vocabulary together to enable
topic_neighbors; the word embeddings are realigned to topica's vocabulary.
fit_transform
method descriptor
¶
Fit, then return the document-topic proportions (fit_transform).
doc_embeddings and word_embeddings are the (num_docs, E) and
(len(vocabulary), E) dense embedding matrices; vocabulary lists the
word strings aligned to the rows of word_embeddings.
merge_topics
method descriptor
¶
Merge groups of topics into single topics, e.g. [[3, 7], [1, 2]]. The
topic vectors, document-topic, and topic-word are rebuilt and topic ids
renumbered to a dense range.
reduce_outliers
method descriptor
¶
Reassign noise documents (label -1) to their nearest topic and rebuild
the topic-word matrix. Returns how many documents were reassigned.
save
method descriptor
¶
Save the fitted model to path (topica's binary format), so a discovered
fit can be reloaded and reused without refitting (useful with the stochastic
reducer="umap" discovery).
top_words
method descriptor
¶
Top n words of topic (or every topic when topic is None) by
class-TF-IDF weight, as (word, weight) pairs.
Top words per topic. Top2Vec's distinctive view is the centroid
representation: the vocabulary words nearest the cluster centroid in
embedding space. When fit with word_embeddings, top_words returns that
by default (so summary/top_words show Top2Vec's identity, not just the
class-based TF-IDF it shares with BERTopic). Pass
representation="c-tf-idf" for the c-TF-IDF words, or "centroid"
explicitly. topic_word and topic_table always stay c-TF-IDF.
topic_neighbors
method descriptor
¶
The n vocabulary words whose embeddings are nearest topic's vector by
cosine, as (word, cosine) pairs. Requires fitting with word_embeddings.
topic is the first argument, so topic_neighbors(0, n=8) reads naturally.
transform
method descriptor
¶
Assign new documents to the nearest topic by cosine distance.
doc_embeddings is the (num_docs, embedding_dim) embedding matrix,
one row per document.
topica.ETM ¶
Embedded Topic Model: LDA with the topic-word matrix factored through
embeddings, beta_{k,v} = softmax_v(rho_v . alpha_k), and a logistic-normal
document prior. You bring the word embeddings rho; topica fits the topic
embeddings alpha and the prior by the same variational EM as CTM (no
VAE, no PyTorch). Semantically related words share topic mass even when a
topic never saw them.
No embedder of your own? topica.llm_embed(vocabulary, model=...) builds the
word embeddings rho (OpenAI, or offline sentence-transformers).
__doc__
class-attribute
¶
__doc__ = 'Embedded Topic Model: LDA with the topic-word matrix factored through\nembeddings, ``beta_{k,v} = softmax_v(rho_v . alpha_k)``, and a logistic-normal\ndocument prior. You bring the word embeddings ``rho``; topica fits the topic\nembeddings ``alpha`` and the prior by the same variational EM as ``CTM`` (no\nVAE, no PyTorch). Semantically related words share topic mass even when a\ntopic never saw them.\n\nNo embedder of your own? `topica.llm_embed(vocabulary, model=...)` builds the\nword embeddings `rho` (OpenAI, or offline `sentence-transformers`).'
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
__module__
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
fit_history
property
¶
Uniform convergence trace: (iteration, bound) pairs, one per EM or
VAE epoch. The objective is the variational ELBO. Empty after
:meth:load (bound_history is not persisted in the saved state).
settings
property
¶
The constructor configuration as a JSON-serialisable dict, keyword-named
to match __init__ (issue #400). inference/prior are reported under
their public strings; convergence_tol is the effective tolerance in force
(the deprecated em_tol alias is folded into it and reported as None).
topic_word
property
¶
Topic-word matrix beta (num_topics, vocab), each row a distribution.
__new__
builtin
¶
Create and return a new object. See help(type) for accurate signature.
coherence
method descriptor
¶
UMass coherence for each topic's top-n words, over the training corpus.
fit
method descriptor
¶
Fit on data (a Corpus or list of token lists) with word_embeddings
((len(vocabulary), E)) and the aligned vocabulary. The vocabulary
defines the word ids; tokens outside it are dropped.
iters sets the number of training iterations (EM iterations or VAE epochs).
convergence_tol overrides the constructor value for this run (when given).
fit_transform
method descriptor
¶
Fit, then return the document-topic proportions (fit_transform).
word_embeddings is the (len(vocabulary), E) dense embedding matrix
aligned to vocabulary, the list of word strings; tokens outside it are
dropped. iters is the number of training iterations (EM iterations or VAE
epochs).
top_words
method descriptor
¶
Top n words per topic as (word, probability) pairs.
Returns a list of n-length lists (one per topic), or — when topic
is given — just that topic's list.
transform
method descriptor
¶
Held-out topic proportions for new documents. For the EM path this is the
logistic-normal E-step with the fitted beta and prior held fixed; for the
VAE path it is a single encoder forward pass (theta = softmax(mu)). Tokens
outside the vocabulary are dropped. doc_embeddings is accepted but not
used (for API consistency with the other embedding models). Returns
(num_docs, num_topics).
topica.FASTopic ¶
FASTopic (Wu et al. 2024): a topic model with no encoder and no neural
network. The topic proportions theta and the topic-word matrix beta are
read off two entropic optimal-transport plans between embedding sets. You bring
the document embeddings D; topica learns the topic embeddings, the word
embeddings (in the same space), and the transport marginals, minimizing a
bag-of-words reconstruction plus the two transport costs. New documents are
mapped to topics by a distance-softmax over the fitted topic embeddings, so
transform needs only their embeddings.
No embedder of your own? topica.llm_embed(texts, model=...) builds the
matrix (OpenAI, or offline sentence-transformers).
__doc__
class-attribute
¶
__doc__ = 'FASTopic (Wu et al. 2024): a topic model with no encoder and no neural\nnetwork. The topic proportions ``theta`` and the topic-word matrix ``beta`` are\nread off two entropic optimal-transport plans between embedding sets. You bring\nthe document embeddings ``D``; topica learns the topic embeddings, the word\nembeddings (in the same space), and the transport marginals, minimizing a\nbag-of-words reconstruction plus the two transport costs. New documents are\nmapped to topics by a distance-softmax over the fitted topic embeddings, so\n``transform`` needs only their embeddings.\n\nNo embedder of your own? `topica.llm_embed(texts, model=...)` builds the\nmatrix (OpenAI, or offline `sentence-transformers`).'
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
__module__
class-attribute
¶
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.
fit_history
property
¶
Uniform convergence trace: (epoch, negative_loss) pairs. The
objective is the negated OT loss (so higher = better), indexed from 1.
settings
property
¶
The constructor configuration as a JSON-serialisable dict, keyword-named
to match __init__ (issue #400). em_tol is a deprecated alias for
convergence_tol, folded at construction, so it reports None here.
topic_embeddings
property
¶
Topic embeddings (num_topics, E), the learned topic points.
topic_word
property
¶
Topic-word matrix beta (num_topics, vocab), each row a distribution.
word_embeddings
property
¶
Word embeddings (vocab, E), learned in the document-embedding space.
__new__
builtin
¶
Create and return a new object. See help(type) for accurate signature.
coherence
method descriptor
¶
UMass coherence for each topic's top-n words, over the training corpus.
fit
method descriptor
¶
Fit on data (a Corpus or list of token lists) with doc_embeddings
((num_docs, E)), one frozen row per document. The vocabulary is taken from
the corpus; FASTopic learns the word embeddings itself, so none are passed.
iters sets the number of training epochs (default 200).
convergence_tol overrides the constructor value for this run (when given).
fit_transform
method descriptor
¶
Fit, then return the document-topic proportions (fit_transform).
doc_embeddings is the (num_docs, E) matrix of frozen document
embeddings, one row per document; FASTopic learns the word embeddings
itself.
top_words
method descriptor
¶
Top n words per topic as (word, probability) pairs.
Returns a list of n-length lists (one per topic), or — when topic
is given — just that topic's list.
transform
method descriptor
¶
Held-out topic proportions for new documents from their embeddings
((n, E)): the reference's distance-softmax over the fitted topic
embeddings, normalized by the training documents. data is accepted but
not used (for API consistency with the other embedding models);
doc_embeddings is required. Returns (n, num_topics).