BERTopic

BERTopic is a topic modeling technique that leverages BERT embeddings and c-TF-IDF to create dense clusters allowing for easily interpretable topics whilst keeping important words in the topic descriptions.

The default embedding model is the text model of google/embeddinggemma-2, which supports 100+ languages. To also model images, audio or video, pass embedding_model="google/embeddinggemma-2".

TODO: Update docstrings

Attributes: topics_ (list[int]) : The topics that are generated for each document after training or updating the topic model. The most recent topics are tracked. probabilities_ (list[float]): The probability of the assigned topic per document. These are only calculated if a HDBSCAN model is used for the clustering step. When calculate_probabilities=True, then it is the probabilities of all topics per document. topic_sizes_ (dict[int, int]) : The size of each topic. topic_representations_ (dict[int, tuple[int, float]]) : The top n terms per topic and their respective c-TF-IDF values. c_tf_idf_ (csr_matrix) : The topic-term matrix as calculated through c-TF-IDF. To access its respective words, run .vectorizer_model.get_feature_names() or .vectorizer_model.get_feature_names_out() topic_labels_ (dict[int, str]) : The default labels for each topic. custom_labels_ (list[str]) : Custom labels for each topic. topic_embeddings_ (np.ndarray) : The embeddings for each topic. They are calculated by taking the centroid embedding of each cluster. representative_docs_ (dict[int, str]) : The representative documents for each topic.

Examples:

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups

docs = fetch_20newsgroups(subset='all')['data']
topic_model = BERTopic()
topics, probabilities = topic_model.fit_transform(docs)

If you want to use your own embedding model, use it as follows:

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups

docs = fetch_20newsgroups(subset='all')['data']
topic_model = BERTopic(embedding_model="google/embeddinggemma-2")

Due to the stochastic nature of UMAP, the results from BERTopic might differ and the quality can degrade. Using your own embeddings allows you to try out BERTopic several times until you find the topics that suit you best.

Source code in bertopic\_bertopic.py

class BERTopic:
    """BERTopic is a topic modeling technique that leverages BERT embeddings and
    c-TF-IDF to create dense clusters allowing for easily interpretable topics
    whilst keeping important words in the topic descriptions.

    The default embedding model is the text model of `google/embeddinggemma-2`, which supports 100+ languages.
    To also model images, audio or video, pass `embedding_model="google/embeddinggemma-2"`.

    # TODO: Update docstrings
    Attributes:
        topics_ (list[int]) : The topics that are generated for each document after training or updating
                              the topic model. The most recent topics are tracked.
        probabilities_ (list[float]): The probability of the assigned topic per document. These are
                                      only calculated if a HDBSCAN model is used for the clustering step.
                                      When `calculate_probabilities=True`, then it is the probabilities
                                      of all topics per document.
        topic_sizes_ (dict[int, int]) : The size of each topic.
        topic_representations_ (dict[int, tuple[int, float]]) : The top n terms per topic and their respective
                                                                   c-TF-IDF values.
        c_tf_idf_ (csr_matrix) : The topic-term matrix as calculated through c-TF-IDF. To access its respective
                                 words, run `.vectorizer_model.get_feature_names()`  or
                                 `.vectorizer_model.get_feature_names_out()`
        topic_labels_ (dict[int, str]) : The default labels for each topic.
        custom_labels_ (list[str]) : Custom labels for each topic.
        topic_embeddings_ (np.ndarray) : The embeddings for each topic. They are calculated by taking the
                                         centroid embedding of each cluster.
        representative_docs_ (dict[int, str]) : The representative documents for each topic.

    Examples:
    ```python
    from bertopic import BERTopic
    from sklearn.datasets import fetch_20newsgroups

    docs = fetch_20newsgroups(subset='all')['data']
    topic_model = BERTopic()
    topics, probabilities = topic_model.fit_transform(docs)
    ```

    If you want to use your own embedding model, use it as follows:

    ```python
    from bertopic import BERTopic
    from sklearn.datasets import fetch_20newsgroups

    docs = fetch_20newsgroups(subset='all')['data']
    topic_model = BERTopic(embedding_model="google/embeddinggemma-2")
    ```

    Due to the stochastic nature of UMAP, the results from BERTopic might differ
    and the quality can degrade. Using your own embeddings allows you to
    try out BERTopic several times until you find the topics that suit
    you best.
    """

    def __init__(
        self,
        language: str = "english",
        top_n_words: int = 10,
        n_gram_range: tuple[int, int] = (1, 1),
        min_topic_size: int = 10,
        nr_topics: int | str | None = None,
        low_memory: bool = False,
        calculate_probabilities: bool = False,
        seed_topic_list: list[list[str]] | None = None,
        zeroshot_topic_list: list[str] | None = None,
        zeroshot_min_similarity: float = 0.7,
        embedding_model=None,
        umap_model=None,
        hdbscan_model=None,
        vectorizer_model: CountVectorizer = None,
        ctfidf_model: TfidfTransformer = None,
        representation_model: BaseRepresentation = None,
        verbose: bool = False,
    ):
        """BERTopic initialization.

        Arguments:
            language: The main language used in your documents, one of bertopic.backend.languages
                      or "multilingual". The default embedding model, EmbeddingGemma 2, supports
                      100+ languages.
            top_n_words: The number of words per topic to extract. Setting this
                         too high can negatively impact topic embeddings as topics
                         are typically best represented by at most 10 words.
            n_gram_range: The n-gram range for the CountVectorizer.
                          Advised to keep high values between 1 and 3.
                          More would likely lead to memory issues.
                          NOTE: This param will not be used if you pass in your own
                          CountVectorizer.
            min_topic_size: The minimum size of the topic. Increasing this value will lead
                            to a lower number of clusters/topics and vice versa.
                            It is the same parameter as `min_cluster_size` in HDBSCAN.
                            NOTE: This param will not be used if you are using `hdbscan_model`.
            nr_topics: Specifying the number of topics will reduce the initial
                       number of topics to the value specified. This reduction can take
                       a while as each reduction in topics (-1) activates a c-TF-IDF
                       calculation. If this is set to None, no reduction is applied. Use
                       "auto" to automatically reduce topics using HDBSCAN. Zero-shot topics
                       are never merged.
                       NOTE: Controlling the number of topics is best done by adjusting
                       `min_topic_size` first before adjusting this parameter.
            low_memory: Sets UMAP low memory to True to make sure less memory is used.
                        NOTE: This is only used in UMAP. For example, if you use PCA instead of UMAP
                        this parameter will not be used.
            calculate_probabilities: Calculate the probabilities of all topics
                                     per document instead of the probability of the assigned
                                     topic per document. This could slow down the extraction
                                     of topics if you have many documents (> 100_000).
                                     NOTE: If false you cannot use the corresponding
                                     visualization method `visualize_probabilities`.
                                     NOTE: This is an approximation of topic probabilities
                                     as used in HDBSCAN and not an exact representation.
            seed_topic_list: A list of seed words per topic to converge around
            zeroshot_topic_list: A list of topic names to use for zero-shot classification
            zeroshot_min_similarity: The minimum similarity between a zero-shot topic and
                                     a document for assignment. The higher this value, the more
                                     confident the model needs to be to assign a zero-shot topic to a document.
            verbose: Changes the verbosity of the model, Set to True if you want
                     to track the stages of the model.
            embedding_model: Use a custom embedding model.
                             The following backends are currently supported
                               * SentenceTransformers
                               * Flair
                               * Spacy
                               * Gensim
                               * USE (TF-Hub)
                             You can also pass in a string that points to one of the following
                             sentence-transformers models:
                               * https://www.sbert.net/docs/pretrained_models.html
            umap_model: Pass in a UMAP model to be used instead of the default.
                        NOTE: You can also pass in any dimensionality reduction algorithm as long
                        as it has `.fit` and `.transform` functions.
            hdbscan_model: Pass in a hdbscan.HDBSCAN model to be used instead of the default
                           NOTE: You can also pass in any clustering algorithm as long as it has
                           `.fit` and `.predict` functions along with the `.labels_` variable.
            vectorizer_model: Pass in a custom `CountVectorizer` instead of the default model.
            ctfidf_model: Pass in a custom ClassTfidfTransformer instead of the default model.
            representation_model: Pass in a model that fine-tunes the topic representations
                                  calculated through c-TF-IDF. Models from `bertopic.representation`
                                  are supported.
        """
        # Topic-based parameters
        if top_n_words > 100:
            logger.warning(
                "Note that extracting more than 100 words from a sparse can slow down computation quite a bit."
            )

        self.top_n_words = top_n_words
        self.min_topic_size = min_topic_size
        self.nr_topics = nr_topics
        self.low_memory = low_memory
        self.calculate_probabilities = calculate_probabilities
        self.verbose = verbose
        self.seed_topic_list = seed_topic_list
        self.zeroshot_topic_list = zeroshot_topic_list
        self.zeroshot_min_similarity = zeroshot_min_similarity

        # Embedding model
        self.language = language if not embedding_model else None
        self.embedding_model = embedding_model

        # Vectorizer
        self.n_gram_range = n_gram_range
        self.vectorizer_model = vectorizer_model or CountVectorizer(ngram_range=self.n_gram_range)
        self.ctfidf_model = ctfidf_model or ClassTfidfTransformer()

        # Representation model
        self.representation_model = representation_model

        # UMAP or another algorithm that has .fit and .transform functions
        if umap_model is not None:
            self.umap_model = umap_model
        else:
            try:
                from umap import UMAP

                self.umap_model = UMAP(
                    n_neighbors=15,
                    n_components=5,
                    min_dist=0.0,
                    metric="cosine",
                    low_memory=self.low_memory,
                )
            except (ImportError, ModuleNotFoundError):
                self.umap_model = PCA(n_components=5)

        # HDBSCAN or another clustering algorithm that has .fit and .predict functions and
        # the .labels_ variable to extract the labels

        if hdbscan_model is not None:
            self.hdbscan_model = hdbscan_model
        elif HAS_HDBSCAN:
            self.hdbscan_model = HDBSCAN(
                min_cluster_size=self.min_topic_size,
                metric="euclidean",
                cluster_selection_method="eom",
                prediction_data=True,
            )
        else:
            self.hdbscan_model = SK_HDBSCAN(
                min_cluster_size=self.min_topic_size,
                metric="euclidean",
                cluster_selection_method="eom",
                n_jobs=-1,
            )

        # Track topics complete with metadata
        self._topics: Topics = Topics()
        self._hierarchy: TopicHierarchy | None = None

        if verbose:
            logger.set_level("DEBUG")
        else:
            logger.set_level("WARNING")

    @property
    def hierarchy_(self) -> IntoDataFrame | None:
        """Get the TopicHierarchy object that contains all hierarchical topic information."""
        return self._hierarchy.to_dataframe() if self._hierarchy is not None else None

    @property
    def topics(self) -> Topics:
        """Get the Topics object that contains all topic information."""
        return self._topics

    @property
    def topics_(self) -> list[int]:
        """For backwards compatibility."""
        return self._topics.predictions

    @property
    def probabilities_(self) -> list[int]:
        """For backwards compatibility."""
        return self._topics.probabilities

    @property
    def topic_representations_(self) -> dict[int, list[tuple[str, float]]]:
        """For backwards compatibility."""
        return {topic.id: topic.representations["Main"].word_scores for topic in self._topics} or None

    @property
    def topic_aspects_(self) -> dict[int, dict[str, list[tuple[str, float]]]]:
        """For backwards compatibility."""
        first_topic = next(iter(self._topics), None)
        aspects = first_topic.representations if first_topic else []
        return {
            name: {topic.id: topic.representations[name].word_scores for topic in self._topics}
            for name in aspects
            if name != "Main"
        }

    @property
    def topic_sizes_(self) -> dict[int, int]:
        """For backwards compatibility."""
        return {topic.id: topic.nr_documents for topic in self._topics}

    @property
    def c_tf_idf_(self) -> csr_matrix | None:
        """For backwards compatibility."""
        c_tf_idf = self._topics.c_tf_idf
        return c_tf_idf if c_tf_idf.shape[1] > 0 else None

    @property
    def topic_embeddings_(self) -> np.ndarray:
        """For backwards compatibility."""
        return self._topics.embeddings

    @property
    def topic_labels_(self) -> dict[int, str]:
        """For backwards compatibility."""
        return self._topics.labels

    @property
    def custom_labels_(self) -> list[str] | None:
        """For backwards compatibility. None until `set_topic_labels` is called."""
        return self._topics.custom_labels

    @property
    def representative_docs_(self) -> dict[int, str]:
        """For backwards compatibility."""
        return {
            topic.id: topic.representative_documents
            for topic in self._topics
            if topic.representative_documents
        }

    @property
    def representative_images_(self) -> dict[int, Any]:
        """For backwards compatibility."""
        return {
            topic.id: topic.media.collage
            for topic in self._topics
            if topic.media is not None and topic.media.collage is not None
        }

    @property
    def representative_items_(self) -> dict[int, list]:
        """The media that represent each topic, whatever their modality."""
        return {topic.id: topic.representative_items for topic in self._topics if topic.representative_items}

    @property
    def _outliers(self) -> int:
        """Some algorithms have outlier labels (-1) that can be tricky to work
        with if you are slicing data based on that labels. Therefore, we
        track if there are outlier labels and act accordingly when slicing.

        Returns:
            An integer indicating whether outliers are present in the topic model
        """
        return 1 if self._topics.outlier_exists else 0

    def fit_transform(
        self,
        documents: list[str] | None = None,
        embeddings: np.ndarray | None = None,
        images: list | None = None,
        y: list[int] | np.ndarray | None = None,
        *,
        audio: list | None = None,
        video: list | None = None,
        code: list[str] | None = None,
    ) -> tuple[list[int], np.ndarray | None]:
        """Fit the models on a collection of documents, generate topics,
        and return the probabilities and topic per document.

        Note that the inline docstrings follow the standard pipeline of BERTopic:

        * 1. Embed documents
        * 2. Dimensionality reduction
        * 3. Cluster Documents
        * 4. Bag-of-words
        * 5. Topic representation
        * 6. (Optional) Fine-tune Topic representation

        Arguments:
            documents: A list of documents to fit on
            embeddings: Pre-trained document embeddings. These can be used
                        instead of the sentence-transformer model
            images: A list of paths to the images to fit on, or the images themselves
            audio: A list of paths to the audio to fit on, or the clips themselves
            video: A list of paths to the video to fit on, or the clips themselves
            code: A list of source code snippets to fit on
            y: The target class for (semi)-supervised modeling. Use -1 if no class for a
               specific instance is specified.

        Returns:
            predictions: Topic predictions for each documents
            probabilities: The probability of the assigned topic per document.
                           If `calculate_probabilities` in BERTopic is set to True, then
                           it calculates the probabilities of all topics across all documents
                           instead of only the assigned topic. This, however, slows down
                           computation and may increase memory usage.

        Examples:
        ```python
        from bertopic import BERTopic
        from sklearn.datasets import fetch_20newsgroups

        docs = fetch_20newsgroups(subset='all')['data']
        topic_model = BERTopic()
        topics, probs = topic_model.fit_transform(docs)
        ```

        If you want to use your own embeddings, use it as follows:

        ```python
        from bertopic import BERTopic
        from sklearn.datasets import fetch_20newsgroups
        from sentence_transformers import SentenceTransformer

        # Create embeddings
        docs = fetch_20newsgroups(subset='all')['data']
        sentence_model = SentenceTransformer("google/embeddinggemma-2", default_prompt_name="Clustering")
        sentence_model.max_seq_length = 1024
        embeddings = sentence_model.encode(docs, show_progress_bar=True)

        # Create topic model
        topic_model = BERTopic()
        topics, probs = topic_model.fit_transform(docs, embeddings)
        ```
        """
        corpus = Corpus.from_inputs(
            documents=documents,
            images=images,
            audio=audio,
            video=video,
            code=code,
            embeddings=embeddings,
            y=y,
        )

        # 1. Extract embeddings
        if corpus.embeddings is None or (corpus.embeddings is not None and self.embedding_model is not None):
            self.embedding_model = select_backend(
                embedding_model=self.embedding_model, language=self.language, verbose=self.verbose
            )

        if corpus.embeddings is None:
            corpus.embeddings = self._embed_corpus(corpus, verbose=self.verbose)

        # Guided Topic Modeling
        corpus = guided.guided_tm(self, corpus)

        # 2) Reduce dimensionality and fit UMAP model
        corpus = self._reduce_dimensionality(corpus)

        # Zero-shot Topic Modeling
        corpus, zeroshot_docs = zeroshot.zeroshot_tm(self, corpus)

        # 3) Cluster reduced embeddings
        corpus = self._cluster_embeddings(corpus)

        # Combine zero-shot topics with clustered topics
        corpus = zeroshot.combine_zeroshot_topics(self, corpus, zeroshot_docs)

        # Let converters describe their own modality in text, since c-TF-IDF needs words
        corpus = self._convert_media_to_text(corpus)

        # 4/5/6) Process text documents
        self._extract_representations(corpus, verbose=self.verbose, fine_tune=not self.nr_topics)
        corpus = self._reduce_topics(corpus)
        self._save_representative_docs(corpus)

        # With zero-shot topics, probability will come from cosine similarity, and the HDBSCAN model will be removed
        corpus = zeroshot.update_probabilities(topic_model=self, corpus=corpus, zeroshot_docs=zeroshot_docs)

        # Assign to public attributes
        self._data = corpus

        return self._topics.predictions, self._topics.probabilities

    def fit(
        self,
        documents: list[str] | None = None,
        embeddings: np.ndarray = None,
        images: list | None = None,
        y: list[int] | np.ndarray = None,
        *,
        audio: list | None = None,
        video: list | None = None,
        code: list[str] | None = None,
    ) -> "BERTopic":
        """Fit the models on a collection of documents and generate topics.

        Arguments:
            documents: A list of documents to fit on
            embeddings: Pre-trained document embeddings. These can be used
                        instead of the sentence-transformer model
            images: A list of paths to the images to fit on, or the images themselves
            audio: A list of paths to the audio to fit on, or the clips themselves
            video: A list of paths to the video to fit on, or the clips themselves
            code: A list of source code snippets to fit on
            y: The target class for (semi)-supervised modeling. Use -1 if no class for a
               specific instance is specified.

        Examples:
        ```python
        from bertopic import BERTopic
        from sklearn.datasets import fetch_20newsgroups

        docs = fetch_20newsgroups(subset='all')['data']
        topic_model = BERTopic().fit(docs)
        ```

        If you want to use your own embeddings, use it as follows:

        ```python
        from bertopic import BERTopic
        from sklearn.datasets import fetch_20newsgroups
        from sentence_transformers import SentenceTransformer

        # Create embeddings
        docs = fetch_20newsgroups(subset='all')['data']
        sentence_model = SentenceTransformer("google/embeddinggemma-2", default_prompt_name="Clustering")
        sentence_model.max_seq_length = 1024
        embeddings = sentence_model.encode(docs, show_progress_bar=True)

        # Create topic model
        topic_model = BERTopic().fit(docs, embeddings)
        ```
        """
        self.fit_transform(
            documents=documents,
            embeddings=embeddings,
            y=y,
            images=images,
            audio=audio,
            video=video,
            code=code,
        )
        return self

    def transform(
        self,
        documents: str | list[str] | None = None,
        embeddings: np.ndarray = None,
        images: list | None = None,
        *,
        audio: list | None = None,
        video: list | None = None,
        code: list[str] | None = None,
    ) -> tuple[list[int], np.ndarray]:
        """After having fit a model, use transform to predict new instances.

        Arguments:
            documents: A single document or a list of documents to predict on
            embeddings: Pre-trained document embeddings. These can be used
                        instead of the sentence-transformer model.
            images: A list of paths to the images to predict on, or the images themselves
            audio: A list of paths to the audio to predict on, or the clips themselves
            video: A list of paths to the video to predict on, or the clips themselves
            code: A list of source code snippets to predict on

        Returns:
            predictions: Topic predictions for each documents
            probabilities: The topic probability distribution which is returned by default.
                           If `calculate_probabilities` in BERTopic is set to False, then the
                           probabilities are not calculated to speed up computation and
                           decrease memory usage.

        Examples:
        ```python
        from bertopic import BERTopic
        from sklearn.datasets import fetch_20newsgroups

        docs = fetch_20newsgroups(subset='all')['data']
        topic_model = BERTopic().fit(docs)
        topics, probs = topic_model.transform(docs)
        ```

        If you want to use your own embeddings:

        ```python
        from bertopic import BERTopic
        from sklearn.datasets import fetch_20newsgroups
        from sentence_transformers import SentenceTransformer

        # Create embeddings
        docs = fetch_20newsgroups(subset='all')['data']
        sentence_model = SentenceTransformer("google/embeddinggemma-2", default_prompt_name="Clustering")
        sentence_model.max_seq_length = 1024
        embeddings = sentence_model.encode(docs, show_progress_bar=True)

        # Create topic model
        topic_model = BERTopic().fit(docs, embeddings)
        topics, probs = topic_model.transform(docs, embeddings)
        ```
        """
        check_is_fitted(self)

        # A single document may come with its embedding as a 1-D array
        if isinstance(embeddings, np.ndarray) and embeddings.ndim == 1:
            embeddings = embeddings.reshape(1, -1)
        corpus = Corpus.from_inputs(
            documents=documents,
            images=images,
            audio=audio,
            video=video,
            code=code,
            embeddings=embeddings,
        )

        # Extract embeddings
        if corpus.embeddings is None:
            corpus.embeddings = self._embed_corpus(corpus, verbose=self.verbose)

        # Check if an embedding model was found
        if corpus.embeddings is None:
            raise ValueError(
                "No embedding model was found to embed the documents."
                "Make sure when loading in the model using BERTopic.load()"
                "to also specify the embedding model."
            )

        # Transform without hdbscan_model and umap_model using only cosine similarity
        elif type(self.hdbscan_model) is BaseCluster:
            logger.info(
                "Predicting topic assignments through cosine similarity of topic and document embeddings."
            )
            sim_matrix = cosine_similarity(corpus.embeddings, np.array(self.topic_embeddings_))
            predictions = np.argmax(sim_matrix, axis=1) - self._outliers

            if self.calculate_probabilities:
                probabilities = sim_matrix
            else:
                probabilities = np.max(sim_matrix, axis=1)

        # Transform with full pipeline
        else:
            logger.info("Dimensionality - Reducing dimensionality of input embeddings.")
            corpus.umap_embeddings = self.umap_model.transform(corpus.embeddings).astype(np.float32)
            logger.info("Dimensionality - Completed \u2713")

            # Extract predictions and probabilities if it is a HDBSCAN-like model
            logger.info("Clustering - Approximating new points with `hdbscan_model`")
            if is_supported_hdbscan(self.hdbscan_model):
                predictions, probabilities = hdbscan_delegator(
                    self.hdbscan_model, "approximate_predict", corpus.umap_embeddings
                )

                # Calculate probabilities
                if self.calculate_probabilities:
                    logger.info("Probabilities - Start calculation of probabilities with HDBSCAN")
                    probabilities = hdbscan_delegator(
                        self.hdbscan_model, "membership_vector", corpus.umap_embeddings
                    )
                    logger.info("Probabilities - Completed \u2713")
            else:
                predictions = self.hdbscan_model.predict(corpus.umap_embeddings)
                probabilities = None
            logger.info("Cluster - Completed \u2713")

            # Map probabilities and predictions
            predictions = self._topics.map_predictions(predictions)
            probabilities = self._topics.align_probabilities(probabilities)

        return predictions, probabilities

    def partial_fit(
        self,
        documents: List[str],
        embeddings: np.ndarray = None,
        y: Union[List[int], np.ndarray] = None,
    ):
        """Fit BERTopic on a subset of the data and perform online learning
        with batch-like data.

        Online topic modeling in BERTopic is performed by using dimensionality
        reduction and cluster algorithms that support a `partial_fit` method
        in order to incrementally train the topic model.

        Likewise, the `bertopic.vectorizers.OnlineCountVectorizer` is used
        to dynamically update its vocabulary when presented with new data.
        It has several parameters for modeling decay and updating the
        representations.

        In other words, although the main algorithm stays the same, the training
        procedure now works as follows:

        For each subset of the data:

        1. Generate embeddings with a pre-trained language model
        2. Incrementally update the dimensionality reduction algorithm with `partial_fit`
        3. Incrementally update the cluster algorithm with `partial_fit`
        4. Incrementally update the OnlineCountVectorizer and apply some form of decay

        Note that it is advised to use `partial_fit` with batches and
        not single documents for the best performance.

        After fitting, `model.topics_` contains topic IDs for all documents seen
        across all batches (accumulated), and `model._topics` contains the Topics
        object with cumulative document counts per topic.

        Arguments:
            documents: A list of documents to fit on
            embeddings: Pre-trained document embeddings. These can be used
                        instead of the sentence-transformer model
            y: The target class for (semi)-supervised modeling. Use -1 if no class for a
               specific instance is specified.

        Examples:
        ```python
        from sklearn.datasets import fetch_20newsgroups
        from sklearn.cluster import MiniBatchKMeans
        from sklearn.decomposition import IncrementalPCA
        from bertopic.vectorizers import OnlineCountVectorizer
        from bertopic import BERTopic

        # Prepare documents
        docs = fetch_20newsgroups(subset=subset,  remove=('headers', 'footers', 'quotes'))["data"]

        # Prepare sub-models that support online learning
        umap_model = IncrementalPCA(n_components=5)
        cluster_model = MiniBatchKMeans(n_clusters=50, random_state=0)
        vectorizer_model = OnlineCountVectorizer(stop_words="english", decay=.01)

        topic_model = BERTopic(umap_model=umap_model,
                               hdbscan_model=cluster_model,
                               vectorizer_model=vectorizer_model)

        # Incrementally fit the topic model by training on 1000 documents at a time
        for index in range(0, len(docs), 1000):
            topic_model.partial_fit(docs[index: index+1000])
        ```
        """
        if not hasattr(self.hdbscan_model, "partial_fit"):
            raise ValueError(
                "In order to use `.partial_fit`, the cluster model should have a `.partial_fit` function."
            )

        # Embed documents
        corpus = Corpus(documents=documents, embeddings=embeddings, y=y)
        is_first_fit = self._topics is None or len(self._topics) == 0

        if is_first_fit and (corpus.embeddings is None or self.embedding_model is not None):
            self.embedding_model = select_backend(
                self.embedding_model, language=self.language, verbose=self.verbose
            )

        if corpus.embeddings is None:
            corpus.embeddings = self._embed_corpus(corpus, verbose=self.verbose)

        # Guided Topic Modeling
        if self.seed_topic_list is not None and self.embedding_model is not None:
            corpus = guided.guided_tm(self, corpus)

        # Reduce dimensionality and cluster
        corpus = self._reduce_dimensionality(corpus, partial_fit=True)
        corpus = self._cluster_embeddings(corpus, partial_fit=True)

        # Use cluster labels directly as topic IDs
        if is_first_fit:
            self._topics = Topics().initialize(corpus.topics)

        # Add new topics and accumulate predictions/counts
        else:
            new_topic_ids = {int(topic) for topic in corpus.topics} - set(self._topics.topic_ids())

            for topic_id in new_topic_ids:
                self._topics.topics[topic_id] = Topic(id=topic_id, nr_documents=0)

            self._topics.predictions.extend(int(topic) for topic in corpus.topics)

            if corpus.probabilities is not None and self._topics.probabilities is not None:
                self._topics.probabilities = np.concatenate(
                    [self._topics.probabilities, corpus.probabilities]
                )

            for topic_id in set(corpus.topics):
                count = int(np.sum(corpus.topics == topic_id))
                self._topics[topic_id].nr_documents += count

        # Update topic representations. Every topic keeps a row, in topic ID order, including topics
        # missing from this batch
        grouped = corpus.group_documents_by_topic()
        documents_per_topic = {topic_id: grouped.get(topic_id, " ") for topic_id in self._topics.topic_ids()}

        c_tf_idf, words = self._c_tf_idf(documents_per_topic, partial_fit=True)
        self._topics.set_data(c_tf_idf=c_tf_idf)

        topic_representations = self._extract_words_per_topic(
            words=words,
            corpus=Corpus(documents=list(documents_per_topic.values()), topics=list(documents_per_topic)),
            c_tf_idf=c_tf_idf,
            fine_tune=False,
            calculate_aspects=False,
        )
        self._topics.set_data(representations={"Main": topic_representations})
        self._create_topic_vectors(corpus)

        # A hierarchy made earlier describes topics that may no longer exist
        self._hierarchy = None

        return self

    @wraps(variations.topics_over_time)
    def topics_over_time(
        self,
        docs: list[str],
        timestamps: list[str] | list[int],
        topics: list[int] | None = None,
        nr_bins: int | None = None,
        datetime_format: str | None = None,
        evolution_tuning: bool = True,
        global_tuning: bool = True,
        use_representation_model: bool = False,
    ) -> IntoDataFrame:
        return variations.topics_over_time(
            topic_model=self,
            docs=docs,
            timestamps=timestamps,
            topics=topics,
            nr_bins=nr_bins,
            datetime_format=datetime_format,
            evolution_tuning=evolution_tuning,
            global_tuning=global_tuning,
            use_representation_model=use_representation_model,
        )

    @wraps(variations.topics_per_class)
    def topics_per_class(
        self,
        docs: list[str],
        classes: list[int | str],
        global_tuning: bool = True,
        use_representation_model: bool = False,
    ) -> IntoDataFrame:
        return variations.topics_per_class(
            topic_model=self,
            docs=docs,
            classes=classes,
            global_tuning=global_tuning,
            use_representation_model=use_representation_model,
        )

    @wraps(variations.approximate_distribution)
    def approximate_distribution(
        self,
        documents: str | list[str],
        window: int = 4,
        stride: int = 1,
        min_similarity: float = 0.1,
        batch_size: int = 1000,
        padding: bool = False,
        use_embedding_model: bool = False,
        calculate_tokens: bool = False,
        separator: str = " ",
    ) -> tuple[np.ndarray, list[np.ndarray] | None]:
        return variations.approximate_distribution(
            topic_model=self,
            documents=documents,
            window=window,
            stride=stride,
            min_similarity=min_similarity,
            batch_size=batch_size,
            padding=padding,
            use_embedding_model=use_embedding_model,
            calculate_tokens=calculate_tokens,
            separator=separator,
        )

    @wraps(variations.reduce_outliers)
    def reduce_outliers(
        self,
        documents: list[str],
        topics: list[int],
        images: list | None = None,
        strategy: str = "distributions",
        probabilities: np.ndarray = None,
        threshold: float = 0,
        embeddings: np.ndarray = None,
        distributions_params: dict[str, Any] = {},
        *,
        audio: list | None = None,
        video: list | None = None,
        code: list[str] | None = None,
    ) -> list[int]:
        return variations.reduce_outliers(
            topic_model=self,
            documents=documents,
            topics=topics,
            images=images,
            audio=audio,
            video=video,
            code=code,
            strategy=strategy,
            probabilities=probabilities,
            threshold=threshold,
            embeddings=embeddings,
            distributions_params=distributions_params,
        )

    @wraps(variations.hierarchical_topics)
    def hierarchical_topics(
        self,
        docs: list[str],
        use_ctfidf: bool = True,
        linkage_function: Callable[[csr_matrix], np.ndarray] | None = None,
        distance_function: Callable[[csr_matrix], csr_matrix] | None = None,
        use_representation_model: bool | str = False,
    ) -> IntoDataFrame:
        self._hierarchy = variations.hierarchical_topics(
            topic_model=self,
            docs=docs,
            use_ctfidf=use_ctfidf,
            linkage_function=linkage_function,
            distance_function=distance_function,
            use_representation_model=use_representation_model,
        )
        return self._hierarchy.to_dataframe()

    def find_topics(
        self, search_term: str | list[str] | None = None, image: str | None = None, top_n: int = 5
    ) -> tuple[list[int], list[float]]:
        """Find topics most similar to a search_term.

        Creates an embedding for a search query and compares that with
        the topic embeddings. The most similar topics are returned
        along with their similarity values.

        The query is specified using search_term for text queries or image for image queries.

        The search_term can be of any size but since it is compared
        with the topic representation it is advised to keep it
        below 5 words.

        Arguments:
            search_term: the term you want to use to search for topics, or a list of terms whose
                         embeddings are averaged into one query.
            image: path to the image you want to use to search for topics.
            top_n: the number of topics to return

        Returns:
            similar_topics: the most similar topics from high to low
            similarity: the similarity scores from high to low

        Examples:
        You can use the underlying embedding model to find topics that
        best represent the search term:

        ```python
        topics, similarity = topic_model.find_topics("sports", top_n=5)
        ```

        Note that the search query is typically more accurate if the
        search_term consists of a phrase or multiple words.
        """
        if self.embedding_model is None:
            raise Exception("This method can only be used if you did not use custom embeddings.")

        # The outlier topic holds what fits no topic, so it is not a topic to find
        topic_list = self._topics.topic_ids(outliers=False)
        topic_embeddings = self.topic_embeddings_[self._outliers :]

        # Extract search_term embeddings and compare with topic embeddings
        if search_term is not None:
            search_terms = [search_term] if isinstance(search_term, str) else search_term
            search_embedding = self.embedding_model.embed_words(search_terms, verbose=False).mean(axis=0)
        elif image is not None:
            search_embedding = self.embedding_model.embed_media([image], Modality.IMAGE).flatten()
        sims = cosine_similarity(search_embedding.reshape(1, -1), topic_embeddings).flatten()

        # Extract topics most similar to search_term
        ids = np.argsort(sims)[-top_n:]
        similarity = [sims[i] for i in ids][::-1]
        similar_topics = [topic_list[index] for index in ids][::-1]

        return similar_topics, similarity

    def update_topics(
        self,
        docs: list[str],
        images: list | None = None,
        topics: list[int] | None = None,
        top_n_words: int = 10,
        n_gram_range: tuple[int, int] | None = None,
        vectorizer_model: CountVectorizer = None,
        ctfidf_model: ClassTfidfTransformer = None,
        representation_model: BaseRepresentation = None,
        embeddings: np.ndarray | None = None,
        *,
        audio: list | None = None,
        video: list | None = None,
        code: list[str] | None = None,
    ):
        """Updates the topic representation by recalculating c-TF-IDF with the new
        parameters as defined in this function.

        When you have trained a model and viewed the topics and the words that represent them,
        you might not be satisfied with the representation. Perhaps you forgot to remove
        stop_words or you want to try out a different `n_gram_range`. This function allows you
        to update the topic representation after they have been formed. The vectorizer, c-TF-IDF
        and representation models you do not pass are kept as they are.

        Arguments:
            docs: The documents you used when calling either `fit` or `fit_transform`
            images: The images you used when calling either `fit` or `fit_transform`
            audio: The audio you used when calling either `fit` or `fit_transform`
            video: The video you used when calling either `fit` or `fit_transform`
            code: The source code you used when calling either `fit` or `fit_transform`
            topics: A list of topics where each topic is related to a document in `docs`.
                    Use this variable to change or map the topics.
                    NOTE: Using a custom list of topic assignments may lead to errors if
                          topic reduction techniques are used afterwards. Make sure that
                          manually assigning topics is the last step in the pipeline.
                          Number them without gaps (-1 for outliers, then 0, 1, 2, ...);
                          to merge topics, use `merge_topics`.
            top_n_words: The number of words per topic to extract. Setting this
                         too high can negatively impact topic embeddings as topics
                         are typically best represented by at most 10 words.
            n_gram_range: The n-gram range for a new CountVectorizer, replacing the model's own.
            vectorizer_model: Pass in your own CountVectorizer from scikit-learn
            ctfidf_model: Pass in your own c-TF-IDF model to update the representations
            representation_model: Pass in a model that fine-tunes the topic representations
                                  calculated through c-TF-IDF. Models from `bertopic.representation`
                                  are supported.
            embeddings: The document embeddings, to recompute topic embeddings from. Without them,
                        each document counts as the embedding of the topic it was in.

        Examples:
        In order to update the topic representation, you will need to first fit the topic
        model and extract topics from them. Based on these, you can update the representation:

        ```python
        topic_model.update_topics(docs, n_gram_range=(2, 3))
        ```

        You can also use a custom vectorizer to update the representation:

        ```python
        from sklearn.feature_extraction.text import CountVectorizer
        vectorizer_model = CountVectorizer(ngram_range=(1, 2), stop_words="english")
        topic_model.update_topics(docs, vectorizer_model=vectorizer_model)
        ```

        You can also use this function to change or map the topics to something else.
        You can update them as follows:

        ```python
        topic_model.update_topics(docs, topics=my_updated_topics)
        ```
        """
        check_documents_type(docs)
        check_is_fitted(self)

        # Update models
        if top_n_words > 100:
            logger.warning(
                "Note that extracting more than 100 words from a sparse can slow down computation quite a bit."
            )
        self.top_n_words = top_n_words
        if n_gram_range:
            vectorizer_model = vectorizer_model or CountVectorizer(ngram_range=n_gram_range)
        self.vectorizer_model = vectorizer_model or self.vectorizer_model
        self.ctfidf_model = ctfidf_model or self.ctfidf_model
        self.representation_model = representation_model or self.representation_model

        # Without embeddings, approximate each document's embedding by that of its current topic, as
        # merge_topics does, so that topic embeddings follow the documents that change topic. Documents
        # the model was not fitted on have no current topic, so they count as their new one
        fitted = topics is None or len(topics) == len(self.topics_)
        if embeddings is None:
            current_topics = self.topics_ if fitted else topics
            topic_embeddings = {topic.id: topic.embedding for topic in self._topics}
            embeddings = np.array([topic_embeddings[topic_id] for topic_id in current_topics])

        # Determine topic assignments
        topics = [int(topic) for topic in (self.topics_ if topics is None else topics)]
        new_ids, old_ids = set(topics), set(self._topics.topic_ids())
        if new_ids != old_ids:
            logger.warning(
                "Using a custom list of topic assignments may lead to errors if "
                "topic reduction techniques are used afterwards. Make sure that "
                "manually assigning topics is the last step in the pipeline."
            )
            # Missing topics are moved to outliers
            self._topics.mapping.apply(
                {topic_id: topic_id if topic_id in new_ids else -1 for topic_id in old_ids}
            )
            for topic_id in old_ids - new_ids:
                del self._topics.topics[topic_id]
            for topic_id in new_ids - old_ids:
                self._topics.topics[topic_id] = Topic(id=topic_id)
            self._topics.probabilities = None

        # Move documents between topics. Fitted probabilities only describe the documents they were fitted on
        sizes = Counter(topics)
        self._topics.predictions = topics
        if not fitted:
            self._topics.probabilities = None
        for topic in self._topics:
            topic.nr_documents = sizes[topic.id]

        corpus = Corpus.from_inputs(
            documents=docs,
            images=images,
            audio=audio,
            video=video,
            code=code,
            topics=np.array(topics),
            embeddings=embeddings,
        )

        self._extract_representations(corpus, fine_tune=True)
        self._save_representative_docs(corpus)

    def get_topics(self, full: bool = False) -> dict[str, tuple[str, float]]:
        """Return topics with top n words and their c-TF-IDF score.

        Arguments:
            full: If True, returns all different forms of topic representations
                  for each topic, including aspects

        Returns:
            self.topic_representations_: The top n words per topic and the corresponding c-TF-IDF score

        Examples:
        ```python
        all_topics = topic_model.get_topics()
        ```
        """
        check_is_fitted(self)

        if full:
            topic_representations = {"Main": self.topic_representations_}
            topic_representations.update(self.topic_aspects_)
            return topic_representations
        else:
            return self.topic_representations_

    def get_topic(self, topic: int, full: bool = False) -> dict[str, tuple[str, float]] | bool:
        """Return top n words for a specific topic and their c-TF-IDF scores.

        Arguments:
            topic: A specific topic for which you want its representation
            full: If True, returns all different forms of topic representations
                  for a topic, including aspects

        Returns:
            The top n words for a specific word and its respective c-TF-IDF scores

        Examples:
        ```python
        topic = topic_model.get_topic(12)
        ```
        """
        check_is_fitted(self)
        if topic in self.topic_representations_:
            if full:
                representations = {"Main": self.topic_representations_[topic]}
                aspects = {
                    aspect: representations[topic] for aspect, representations in self.topic_aspects_.items()
                }
                representations.update(aspects)
                return representations
            else:
                return self.topic_representations_[topic]
        else:
            return False

    def get_representation(self, topic: int, aspect: str = "Main") -> TopicRepresentation:
        """Return a topic's representation with its structure intact.

        `get_topic` flattens every representation to words and scores, which loses the shape
        of anything richer than keywords, such as the dictionary an LLM returns. This returns
        the representation itself.

        Arguments:
            topic: A specific topic for which you want its representation
            aspect: Which representation to return, defaulting to the main one

        Returns:
            The `TopicRepresentation` for that topic and aspect

        Examples:
        ```python
        representation = topic_model.get_representation(12)
        representation.words
        ```
        """
        check_is_fitted(self)
        return self._topics[topic].representations[aspect]

    def get_topic_info(self, topic: int | None = None) -> IntoDataFrame:
        """Get information about each topic including its ID, frequency, and name.

        Arguments:
            topic: A specific topic for which you want the frequency

        Returns:
            df: A dataframe containing information about each topic

        Examples:
        ```python
        info_df = topic_model.get_topic_info()
        ```
        """
        check_is_fitted(self)
        return self._topics.to_dataframe(topics=topic)

    def get_topic_freq(self, topic: int | None = None) -> IntoDataFrame | int:
        """Return the size of topics (descending order).

        Arguments:
            topic: A specific topic for which you want the frequency

        Returns:
            Either the frequency of a single topic or dataframe with
            the frequencies of all topics

        Examples:
        To extract the frequency of all topics:

        ```python
        frequency = topic_model.get_topic_freq()
        ```

        To get the frequency of a single topic:

        ```python
        frequency = topic_model.get_topic_freq(12)
        ```
        """
        check_is_fitted(self)
        if isinstance(topic, int):
            return self.topic_sizes_[topic]
        else:
            sizes = self.topic_sizes_
            data = {"Topic": list(sizes.keys()), "Count": list(sizes.values())}
            return nw.from_dict(data, backend=get_output()).sort("Count", descending=True).to_native()

    def get_document_info(
        self,
        docs: list[str],
        df: IntoDataFrame | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> IntoDataFrame:
        """Get information about the documents on which the topic was trained
        including the documents themselves, their respective topics, the name
        of each topic, the top n words of each topic, whether it is a
        representative document, and probability of the clustering if the cluster
        model supports it.

        Arguments:
            docs: The documents on which the topic model was trained.
            df: A dataframe with extra columns to include in the output.
            metadata: A dictionary with meta data for each document in the form
                      of column name (key) and the respective values (value).

        Returns:
            document_info: A dataframe with several statistics regarding
                           the documents on which the topic model was trained.

        Examples:
        ```python
        document_info = topic_model.get_document_info(docs)
        ```
        """
        check_documents_type(docs)
        check_is_fitted(self)

        predictions = self.topics_
        topics_lookup = self._topics.topics
        representative_docs = {doc for topic in self._topics for doc in topic.representative_documents or []}

        # Each document gets its topic's row of `get_topic_info`, as in 0.17
        topic_info = nw.from_native(self._topics.to_dataframe(topics=predictions), eager_only=True)
        data: dict[str, list] = {
            "Top_n_words": [
                " - ".join(topics_lookup[tid].representations["Main"].words) for tid in predictions
            ],
        }

        # Probabilities
        if self.probabilities_ is not None:
            if len(self.probabilities_.shape) == 1:
                data["Probability"] = self.probabilities_.tolist()
            else:
                # Column `j` holds topic `topic_ids()[j]`, so the assigned topic's
                # probability is read directly rather than derived
                topic_ids = self._topics.topic_ids()
                data["Probability"] = [
                    float(probabilities[topic_ids.index(topic_id)])
                    for topic_id, probabilities in zip(predictions, self.probabilities_)
                ]

        data["Representative_document"] = [doc in representative_docs for doc in docs]

        # Custom metadata
        if metadata is not None:
            data.update(metadata)

        # The document comes first, then its topic's information and the columns above, which replace any of
        # the same name
        documents = nw.from_dict({"Document": docs}, backend=get_output())
        columns = nw.from_dict(data, backend=get_output())
        topic_info = topic_info.drop(["Count", *data], strict=False)
        result = nw.concat([documents, topic_info, columns], how="horizontal")

        # The caller's own columns come first, in whatever library they used, unless ours replace them
        if df is not None:
            df = nw.from_native(df, eager_only=True)
            result = nw.concat([df.drop(result.columns, strict=False), result], how="horizontal")
        return result.to_native()

    def get_representative_docs(self, topic: int | None = None) -> list[str] | dict[int, list[str]] | None:
        """Extract the best representing documents per topic.

        Arguments:
            topic: A specific topic for which you want
                   the representative documents

        Returns:
            Representative documents of the chosen topic, or a dict
            of all topics to their representative documents if no
            topic is specified.

        Examples:
        To extract the representative docs of all topics:

        ```python
        representative_docs = topic_model.get_representative_docs()
        ```

        To get the representative docs of a single topic:

        ```python
        representative_docs = topic_model.get_representative_docs(12)
        ```
        """
        check_is_fitted(self)
        if isinstance(topic, int):
            selected_topic = self._topics.get(topic)
            if selected_topic and selected_topic.representative_documents:
                return selected_topic.representative_documents
            return None
        else:
            return {t.id: t.representative_documents for t in self._topics if t.representative_documents}

    def get_topic_tree(
        self,
        hier_topics: IntoDataFrame | None = None,
        max_distance: float | None = None,
        tight_layout: bool = False,
    ) -> str:
        """Extract the topic tree such that it can be printed.

        Arguments:
            hier_topics: A dataframe containing the structure of the topic tree.
                         This is the output of `topic_model.hierarchical_topics()`. If None,
                         the hierarchy that it created last is used.
            max_distance: The maximum distance between two topics. Topics merged
                          at distances greater than this are shown as 'O'.
            tight_layout: Whether to use a tight layout (narrow width) for
                          easier readability if you have hundreds of topics.

        Returns:
            A tree that has the following structure when printed:
                .
                .
                └─health_medical_disease_patients_hiv
                    ├─patients_medical_disease_candida_health
                    │    ├─■──candida_yeast_infection_gonorrhea_infections ── Topic: 48
                    │    └─patients_disease_cancer_medical_doctor
                    │         ├─■──hiv_medical_cancer_patients_doctor ── Topic: 34
                    │         └─■──pain_drug_patients_disease_diet ── Topic: 26
                    └─■──health_newsgroup_tobacco_vote_votes ── Topic: 9

            The blocks (■) indicate that the topic is one you can directly access
            from `topic_model.get_topic`. In other words, they are the original un-grouped topics.

        Examples:
        ```python
        # Train model
        from bertopic import BERTopic
        topic_model = BERTopic()
        topics, probs = topic_model.fit_transform(docs)
        hierarchical_topics = topic_model.hierarchical_topics(docs)

        # Print topic tree
        tree = topic_model.get_topic_tree(hierarchical_topics)
        print(tree)
        ```
        """
        if hier_topics is None:
            if self._hierarchy is None:
                raise ValueError(
                    "You need to first create a topic hierarchy through "
                    "`topic_model.hierarchical_topics()` before you can "
                    "extract the topic tree."
                )
            hier_topics = self._hierarchy.to_dataframe()

        # Map each merged topic to its children, and each child to its name and the distance it was merged at
        tree, names, distances = {}, {}, {}
        for row in nw.from_native(hier_topics, eager_only=True).rows(named=True):
            tree[row["Parent_ID"]] = [row["Child_Left_ID"], row["Child_Right_ID"]]
            for side in ["Left", "Right"]:
                names[row[f"Child_{side}_ID"]] = row[f"Child_{side}_Name"][:100]
                distances[row[f"Child_{side}_ID"]] = row["Distance"]
        root = next(topic for topic in tree if topic not in distances)
        max_distance = max(distances.values()) + 1 if max_distance is None else max_distance
        width = 1 if tight_layout else 4

        def _tree(to_print, topic, indent=""):
            """Based on: https://stackoverflow.com/a/51920869/10532563."""
            # An original topic is shown with its ID, unless it was merged beyond `max_distance`
            if topic != root:
                if topic in tree:
                    to_print += names[topic] + "\n"
                elif distances[topic] < max_distance:
                    to_print += "■──" + names[topic] + f" ── Topic: {topic}" + "\n"
                else:
                    to_print += "O \n"

            if topic not in tree:
                return to_print

            for child in tree[topic][:-1]:
                to_print += indent + "├" + "─"
                to_print = _tree(to_print, child, indent + "│" + " " * width)

            child = tree[topic][-1]
            to_print += indent + "└" + "─"
            return _tree(to_print, child, indent + " " * (width + 1))

        return _tree("." + "\n", root)

    def set_topic_labels(self, topic_labels: list[str] | dict[int, str]) -> None:
        """Set custom topic labels in your fitted BERTopic model.

        Labels are stored directly on each `Topic` object via `topic._label`.

        Arguments:
            topic_labels: If a list of topic labels, it should contain the same number
                          of labels as there are topics. This must be ordered
                          from the topic with the lowest ID to the highest ID,
                          including topic -1 if it exists.
                          If a dictionary of `topic ID`: `topic_label`, it can have
                          any number of topics as it will only map the topics found
                          in the dictionary.

        Examples:
        First, we define our topic labels with `.generate_topic_labels` in which
        we can customize our topic labels:

        ```python
        topic_labels = topic_model.generate_topic_labels(
            nr_words=2,
            topic_prefix=True,
            word_length=10,
            separator=", "
        )
        ```

        Then, we pass these `topic_labels` to our topic model which
        can be accessed at any time with `.custom_labels_`:

        ```python
        topic_model.set_topic_labels(topic_labels)
        topic_model.custom_labels_
        ```

        You might want to change only a few topic labels instead of all of them.
        To do so, you can pass a dictionary where the keys are the topic IDs and
        its keys the topic labels:

        ```python
        topic_model.set_topic_labels({0: "Space", 1: "Sports", 2: "Medicine"})
        topic_model.custom_labels_
        ```
        """
        check_is_fitted(self)
        sorted_topics = list(self._topics)  # sorted by ID

        if isinstance(topic_labels, dict):
            for topic_id, label in topic_labels.items():
                selected_topic = self._topics.get(topic_id)
                if selected_topic is not None:
                    selected_topic._label = label

        elif isinstance(topic_labels, list):
            if len(topic_labels) != len(sorted_topics):
                raise ValueError(
                    "Make sure that `topic_labels` contains the same number of labels as there are topics."
                )
            for selected_topic, label in zip(sorted_topics, topic_labels):
                selected_topic._label = label

    def generate_topic_labels(
        self,
        nr_words: int = 3,
        topic_prefix: bool = True,
        word_length: int | None = None,
        separator: str = "_",
        aspect: str | None = None,
    ) -> list[str]:
        """Get labels for each topic in a user-defined format.

        Arguments:
            nr_words: Top `n` words per topic to use
            topic_prefix: Whether to use the topic ID as a prefix.
                          If set to True, the topic ID will be separated
                          using the `separator`
            word_length: The maximum length of each word in the topic label.
                         Some words might be relatively long and setting this
                         value helps to make sure that all labels have relatively
                         similar lengths.
            separator: The string with which the words and topic prefix will be
                       separated. Underscores are the default but a nice alternative
                       is `", "`.
            aspect: The aspect from which to generate topic labels

        Returns:
            topic_labels: A list of topic labels sorted from the lowest topic ID to the highest.
                          If the topic model was trained using HDBSCAN, the lowest topic ID is -1,
                          otherwise it is 0.

        Examples:
        To create our custom topic labels, usage is rather straightforward:

        ```python
        topic_labels = topic_model.generate_topic_labels(nr_words=2, separator=", ")
        ```
        """
        check_is_fitted(self)
        topic_labels = []
        for topic in self._topics:
            representation = topic.representations.get(aspect or "Main")

            # For non-keyword representations (Label, StructuredJSON), use their
            # label directly since word-level operations don't apply.
            if representation and not isinstance(representation, Keywords):
                label = representation.label
                if topic_prefix:
                    topic_label = f"{topic.id}{separator}{label}"
                else:
                    topic_label = label
            else:
                words = representation.words if representation else []

                if word_length:
                    words = [word[:word_length] for word in words][:nr_words]
                else:
                    words = list(words)[:nr_words]

                if topic_prefix:
                    topic_label = f"{topic.id}{separator}" + separator.join(words)
                else:
                    topic_label = separator.join(words)

            topic_labels.append(topic_label)

        return topic_labels

    def merge_topics(
        self,
        docs: list[str],
        topics_to_merge: list[Iterable[int] | int],
        images: list | None = None,
        *,
        audio: list | None = None,
        video: list | None = None,
        code: list[str] | None = None,
    ) -> None:
        """Merge multiple topics into a single topic.

        Arguments:
            docs: The documents you used when calling either `fit` or `fit_transform`
            topics_to_merge: Either a list of topics or a list of list of topics
                             to merge. For example:
                                [1, 2, 3] will merge topics 1, 2 and 3
                                [[1, 2], [3, 4]] will merge topics 1 and 2, and
                                separately merge topics 3 and 4.
            images: A list of paths to the images used when calling either
                    `fit` or `fit_transform`.
            audio: A list of paths to the audio used when calling either
                   `fit` or `fit_transform`.
            video: A list of paths to the video used when calling either
                   `fit` or `fit_transform`.
            code: The source code used when calling either `fit` or `fit_transform`.

        Examples:
        If you want to merge topics 1, 2, and 3:

        ```python
        topics_to_merge = [1, 2, 3]
        topic_model.merge_topics(docs, topics_to_merge)
        ```

        or if you want to merge topics 1 and 2, and separately
        merge topics 3 and 4:

        ```python
        topics_to_merge = [[1, 2],
                            [3, 4]]
        topic_model.merge_topics(docs, topics_to_merge)
        ```
        """
        check_is_fitted(self)
        check_documents_type(docs)

        # Build mapping: all topics map to themselves, except merged topics map to target
        mapping = {topic: topic for topic in set(self.topics_)}
        if isinstance(topics_to_merge[0], int):
            for topic in sorted(topics_to_merge):
                mapping[topic] = topics_to_merge[0]
        elif isinstance(topics_to_merge[0], Iterable):
            for topic_group in sorted(topics_to_merge):
                for topic in topic_group:
                    mapping[topic] = topic_group[0]
        else:
            raise ValueError(
                "Make sure that `topics_to_merge` is either a list of topics or a list of list of topics."
            )

        # Build Corpus BEFORE merge with current topic assignments and embeddings.
        # This ensures embeddings correspond to original topics, so after merge
        # the mean embedding correctly produces a weighted average.
        topic_embeddings = {topic.id: topic.embedding for topic in self._topics}
        doc_embeddings = np.array([topic_embeddings[topic_id] for topic_id in self.topics_])
        corpus = Corpus.from_inputs(
            documents=docs,
            images=images,
            audio=audio,
            video=video,
            code=code,
            topics=np.array(self.topics_),
            embeddings=doc_embeddings,
        )

        # Merge topics (updates topic IDs and cumulative mapping)
        self._topics.merge(mapping)

        # Map corpus topics to match merged state and then sort by frequency
        self._topics.sort_by_frequency()
        corpus.topics, corpus.probabilities = self._topics.predictions, self._topics.probabilities

        # Recalculate representations from merged documents
        self._extract_representations(corpus)
        self._save_representative_docs(corpus)

    def delete_topics(self, topics_to_delete: list[int] | int) -> None:
        """Delete topics from the topic model.

        The deleted topics will be mapped to -1 (outlier topic). Document predictions
        for deleted topics become -1. Remaining topics are renumbered by frequency.

        Arguments:
            topics_to_delete: List of topic IDs to delete or a single topic ID.

        Examples:
        ```python
        # Delete topics 3 and 5
        topic_model.delete_topics([3, 5])
        ```
        """
        check_is_fitted(self)

        self._topics.delete(topics_to_delete)
        self._topics.sort_by_frequency()

        # A hierarchy made earlier describes topics that may no longer exist
        self._hierarchy = None

    def reduce_topics(
        self,
        docs: list[str],
        nr_topics: int | str = 20,
        images: list | None = None,
        use_ctfidf: bool = False,
        *,
        audio: list | None = None,
        video: list | None = None,
        code: list[str] | None = None,
    ) -> "BERTopic":
        """Reduce the number of topics to a fixed number of topics
        or automatically.

        If nr_topics is an integer, then the number of topics is reduced
        to nr_topics using `AgglomerativeClustering` on the cosine distance matrix
        of the topic c-TF-IDF or semantic embeddings.

        If nr_topics is `"auto"`, then HDBSCAN is used to automatically
        reduce the number of topics by running it on the topic embeddings.

        The topics, their sizes, and representations are updated.

        Arguments:
            docs: The docs you used when calling either `fit` or `fit_transform`
            nr_topics: The number of topics you want reduced to
            images: A list of paths to the images used when calling either
                    `fit` or `fit_transform`
            audio: A list of paths to the audio used when calling either
                   `fit` or `fit_transform`
            video: A list of paths to the video used when calling either
                   `fit` or `fit_transform`
            code: The source code used when calling either `fit` or `fit_transform`
            use_ctfidf: Whether to calculate distances between topics based on c-TF-IDF embeddings. If False, the
                        embeddings from the embedding model are used.

        Examples:
        You can further reduce the topics by passing the documents with their
        topics and probabilities (if they were calculated):

        ```python
        topic_model.reduce_topics(docs, nr_topics=30)
        ```

        You can then access the updated topics and probabilities with:

        ```python
        topics = topic_model.topics_
        probabilities = topic_model.probabilities_
        ```
        """
        check_is_fitted(self)
        check_documents_type(docs)

        self.nr_topics = nr_topics

        # Build Corpus with current topic assignments
        # Add embedings by duplicating the topic embedding for each document
        topic_embeddings = {topic.id: topic.embedding for topic in self._topics}
        doc_embeddings = np.array([topic_embeddings[topic_id] for topic_id in self.topics_])
        corpus = Corpus.from_inputs(
            documents=docs,
            images=images,
            audio=audio,
            video=video,
            code=code,
            topics=np.array(self.topics_),
            embeddings=doc_embeddings,
        )

        # Reduce number of topics
        corpus = self._reduce_topics(corpus, use_ctfidf)
        self._save_representative_docs(corpus)

        # TODO: Check if zeroshot probabilities need to be updated
        # corpus = zeroshot.update_probabilities(topic_model=self, corpus=corpus, zeroshot_docs=zeroshot_docs)

        return self

    @wraps(plotting.visualize_topics)
    def visualize_topics(
        self,
        topics: List[int] | None = None,
        top_n_topics: int | None = None,
        use_ctfidf: bool = False,
        custom_labels: bool = False,
        title: str = "<b>Intertopic Distance Map</b>",
        width: int = 650,
        height: int = 650,
    ) -> "go.Figure":
        check_is_fitted(self)
        return plotting.visualize_topics(
            self,
            topics=topics,
            top_n_topics=top_n_topics,
            use_ctfidf=use_ctfidf,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
        )

    @wraps(plotting.visualize_documents)
    def visualize_documents(
        self,
        docs: List[str],
        topics: List[int] | None = None,
        embeddings: np.ndarray = None,
        reduced_embeddings: np.ndarray = None,
        sample: float | None = None,
        hide_annotations: bool = False,
        hide_document_hover: bool = False,
        custom_labels: bool = False,
        title: str = "<b>Documents and Topics</b>",
        width: int = 1200,
        height: int = 750,
    ) -> "go.Figure":
        check_is_fitted(self)
        check_documents_type(docs)
        return plotting.visualize_documents(
            self,
            docs=docs,
            topics=topics,
            embeddings=embeddings,
            reduced_embeddings=reduced_embeddings,
            sample=sample,
            hide_annotations=hide_annotations,
            hide_document_hover=hide_document_hover,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
        )

    @wraps(plotting.visualize_document_datamap)
    def visualize_document_datamap(
        self,
        docs: List[str] | None = None,
        topics: List[int] | None = None,
        embeddings: np.ndarray = None,
        reduced_embeddings: np.ndarray = None,
        custom_labels: Union[bool, str] = False,
        title: str = "Documents and Topics",
        sub_title: Union[str, None] = None,
        width: int = 1200,
        height: int = 750,
        interactive: bool = False,
        enable_search: bool = False,
        topic_prefix: bool = False,
        datamap_kwds: dict = {},
        int_datamap_kwds: dict = {},
        *,
        images: list | None = None,
        audio: list | None = None,
        video: list | None = None,
        code: List[str] | None = None,
    ) -> "fig.Figure":
        check_is_fitted(self)
        return plotting.visualize_document_datamap(
            self,
            docs,
            topics,
            embeddings,
            reduced_embeddings,
            custom_labels,
            title,
            sub_title,
            width,
            height,
            interactive,
            enable_search,
            topic_prefix,
            datamap_kwds,
            int_datamap_kwds,
            images=images,
            audio=audio,
            video=video,
            code=code,
        )

    @wraps(plotting.visualize_media)
    def visualize_media(
        self,
        topics: List[int] | None = None,
        top_n_topics: int | None = None,
        height: int = 200,
    ) -> "HTML":
        check_is_fitted(self)
        return plotting.visualize_media(self, topics=topics, top_n_topics=top_n_topics, height=height)

    @wraps(plotting.visualize_hierarchical_documents)
    def visualize_hierarchical_documents(
        self,
        docs: List[str],
        hierarchical_topics: IntoDataFrame,
        topics: List[int] | None = None,
        embeddings: np.ndarray = None,
        reduced_embeddings: np.ndarray = None,
        sample: Union[float, int] | None = None,
        hide_annotations: bool = False,
        hide_document_hover: bool = True,
        nr_levels: int = 10,
        level_scale: str = "linear",
        custom_labels: bool = False,
        title: str = "<b>Hierarchical Documents and Topics</b>",
        width: int = 1200,
        height: int = 750,
    ) -> "go.Figure":
        check_is_fitted(self)
        check_documents_type(docs)
        return plotting.visualize_hierarchical_documents(
            self,
            docs=docs,
            hierarchical_topics=hierarchical_topics,
            topics=topics,
            embeddings=embeddings,
            reduced_embeddings=reduced_embeddings,
            sample=sample,
            hide_annotations=hide_annotations,
            hide_document_hover=hide_document_hover,
            nr_levels=nr_levels,
            level_scale=level_scale,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
        )

    @wraps(plotting.visualize_term_rank)
    def visualize_term_rank(
        self,
        topics: List[int] | None = None,
        log_scale: bool = False,
        custom_labels: bool = False,
        title: str = "<b>Term score decline per Topic</b>",
        width: int = 800,
        height: int = 500,
    ) -> "go.Figure":
        check_is_fitted(self)
        return plotting.visualize_term_rank(
            self,
            topics=topics,
            log_scale=log_scale,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
        )

    @wraps(plotting.visualize_topics_over_time)
    def visualize_topics_over_time(
        self,
        topics_over_time: IntoDataFrame,
        top_n_topics: int | None = None,
        topics: List[int] | None = None,
        normalize_frequency: bool = False,
        custom_labels: bool = False,
        title: str = "<b>Topics over Time</b>",
        width: int = 1250,
        height: int = 450,
    ) -> "go.Figure":
        check_is_fitted(self)
        return plotting.visualize_topics_over_time(
            self,
            topics_over_time=topics_over_time,
            top_n_topics=top_n_topics,
            topics=topics,
            normalize_frequency=normalize_frequency,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
        )

    @wraps(plotting.visualize_topics_per_class)
    def visualize_topics_per_class(
        self,
        topics_per_class: IntoDataFrame,
        top_n_topics: int = 10,
        topics: List[int] | None = None,
        normalize_frequency: bool = False,
        custom_labels: bool = False,
        title: str = "<b>Topics per Class</b>",
        width: int = 1250,
        height: int = 900,
    ) -> "go.Figure":
        check_is_fitted(self)
        return plotting.visualize_topics_per_class(
            self,
            topics_per_class=topics_per_class,
            top_n_topics=top_n_topics,
            topics=topics,
            normalize_frequency=normalize_frequency,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
        )

    @wraps(plotting.visualize_distribution)
    def visualize_distribution(
        self,
        probabilities: np.ndarray,
        min_probability: float = 0.015,
        custom_labels: bool = False,
        title: str = "<b>Topic Probability Distribution</b>",
        width: int = 800,
        height: int = 600,
    ) -> "go.Figure":
        check_is_fitted(self)
        return plotting.visualize_distribution(
            self,
            probabilities=probabilities,
            min_probability=min_probability,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
        )

    @wraps(plotting.visualize_approximate_distribution)
    def visualize_approximate_distribution(
        self,
        document: str,
        topic_token_distribution: np.ndarray,
        normalize: bool = False,
    ):
        check_is_fitted(self)
        return plotting.visualize_approximate_distribution(
            self,
            document=document,
            topic_token_distribution=topic_token_distribution,
            normalize=normalize,
        )

    @wraps(plotting.visualize_hierarchy)
    def visualize_hierarchy(
        self,
        orientation: str = "left",
        topics: List[int] | None = None,
        top_n_topics: int | None = None,
        use_ctfidf: bool = True,
        custom_labels: bool = False,
        title: str = "<b>Hierarchical Clustering</b>",
        width: int = 1000,
        height: int = 600,
        hierarchical_topics: IntoDataFrame = None,
        linkage_function: Callable[[csr_matrix], np.ndarray] | None = None,
        distance_function: Callable[[csr_matrix], csr_matrix] | None = None,
        color_threshold: int = 1,
    ) -> "go.Figure":
        check_is_fitted(self)
        return plotting.visualize_hierarchy(
            self,
            orientation=orientation,
            topics=topics,
            top_n_topics=top_n_topics,
            use_ctfidf=use_ctfidf,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
            hierarchical_topics=hierarchical_topics,
            linkage_function=linkage_function,
            distance_function=distance_function,
            color_threshold=color_threshold,
        )

    @wraps(plotting.visualize_heatmap)
    def visualize_heatmap(
        self,
        topics: List[int] | None = None,
        top_n_topics: int | None = None,
        n_clusters: int | None = None,
        use_ctfidf: bool = False,
        custom_labels: bool = False,
        title: str = "<b>Similarity Matrix</b>",
        width: int = 800,
        height: int = 800,
    ) -> "go.Figure":
        check_is_fitted(self)
        return plotting.visualize_heatmap(
            self,
            topics=topics,
            top_n_topics=top_n_topics,
            n_clusters=n_clusters,
            use_ctfidf=use_ctfidf,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
        )

    @wraps(plotting.visualize_barchart)
    def visualize_barchart(
        self,
        topics: List[int] | None = None,
        top_n_topics: int = 8,
        n_words: int = 5,
        custom_labels: bool = False,
        title: str = "Topic Word Scores",
        width: int = 250,
        height: int = 250,
        autoscale: bool = False,
    ) -> "go.Figure":
        check_is_fitted(self)
        return plotting.visualize_barchart(
            self,
            topics=topics,
            top_n_topics=top_n_topics,
            n_words=n_words,
            custom_labels=custom_labels,
            title=title,
            width=width,
            height=height,
            autoscale=autoscale,
        )

    def save(
        self,
        path,
        serialization: Literal["safetensors", "pickle", "pytorch"] = "pickle",
        save_embedding_model: Union[bool, str] = True,
        save_ctfidf: bool = False,
    ):
        """Saves the model to the specified path or folder.

        When saving the model, make sure to also keep track of the versions
        of dependencies and Python used. Loading and saving the model should
        be done using the same dependencies and Python. Moreover, models
        saved in one version of BERTopic should not be loaded in other versions.

        Arguments:
            path: If `serialization` is 'safetensors' or `pytorch`, this is a directory.
                  If `serialization` is `pickle`, then this is a file.
            serialization: If `pickle`, the entire model will be pickled. If `safetensors`
                           or `pytorch` the model will be saved without the embedding,
                           dimensionality reduction, and clustering algorithms.
                           This is a very efficient format and typically advised.
            save_embedding_model: If serialization is `pickle`, then you can choose to skip
                                  saving the embedding model. If serialization is `safetensors`
                                  or `pytorch`, this variable can be used as a string pointing
                                  towards a huggingface model.
            save_ctfidf: Whether to save c-TF-IDF information if serialization is `safetensors`
                         or `pytorch`

        Examples:
        To save the model in an efficient and safe format (safetensors) with c-TF-IDF information:

        ```python
        topic_model.save("model_dir", serialization="safetensors", save_ctfidf=True)
        ```

        If you wish to also add a pointer to the embedding model, which will be downloaded from
        HuggingFace upon loading:

        ```python
        embedding_model = "google/embeddinggemma-2"
        topic_model.save("model_dir", serialization="safetensors", save_embedding_model=embedding_model)
        ```

        or if you want save the full model with pickle:

        ```python
        topic_model.save("my_model")
        ```

        NOTE: Pickle can run arbitrary code and is generally considered to be less safe than
        safetensors.
        """
        if serialization == "pickle":
            logger.warning(
                "When you use `pickle` to save/load a BERTopic model, "
                "please make sure that the environments in which you save "
                "and load the model are **exactly** the same. The version of BERTopic, "
                "its dependencies, and python need to remain the same."
            )

            with open(path, "wb") as file:
                # This prevents the vectorizer from being too large in size if `min_df` was
                # set to a value higher than 1
                self.vectorizer_model.stop_words_ = None

                if not save_embedding_model:
                    embedding_model = self.embedding_model
                    self.embedding_model = None
                    joblib.dump(self, file)
                    self.embedding_model = embedding_model
                else:
                    joblib.dump(self, file)
        elif serialization == "safetensors" or serialization == "pytorch":
            # Directory
            save_directory = Path(path)
            save_directory.mkdir(exist_ok=True, parents=True)

            # Check embedding model
            if (
                save_embedding_model
                and hasattr(self.embedding_model, "_hf_model")
                and not isinstance(save_embedding_model, str)
            ):
                save_embedding_model = self.embedding_model._hf_model
            elif not save_embedding_model:
                logger.warning(
                    "You are saving a BERTopic model without explicitly defining an embedding model."
                    "If you are using a sentence-transformers model or a HuggingFace model supported"
                    "by sentence-transformers, please save the model by using a pointer towards that model."
                    "For example, `save_embedding_model='google/embeddinggemma-2'`"
                )

            # Minimal
            save_utils.save_hf(model=self, save_directory=save_directory, serialization=serialization)
            save_utils.save_topics(model=self, path=save_directory / "topics.json")
            save_utils.save_summaries(model=self, directory=save_directory)
            save_utils.save_config(
                model=self,
                path=save_directory / "config.json",
                embedding_model=save_embedding_model,
            )

            # Additional
            if save_ctfidf:
                if self.c_tf_idf_ is None:
                    logger.warning(
                        "The c-TF-IDF matrix could not be saved as it was not found. "
                        "This typically occurs when merging BERTopic models with `BERTopic.merge_models`."
                    )
                else:
                    save_utils.save_ctfidf(
                        model=self,
                        save_directory=save_directory,
                        serialization=serialization,
                    )
                    save_utils.save_ctfidf_config(model=self, path=save_directory / "ctfidf_config.json")

    @classmethod
    def load(cls, path: str, embedding_model=None):
        """Loads the model from the specified path or directory.

        Arguments:
            path: Either load a BERTopic model from a file (`.pickle`) or a folder containing
                  `.safetensors` or `.bin` files.
            embedding_model: Additionally load in an embedding model if it was not saved
                             in the BERTopic model file or directory.

        Examples:
        ```python
        BERTopic.load("model_dir")
        ```

        or if you did not save the embedding model:

        ```python
        BERTopic.load("model_dir", embedding_model="google/embeddinggemma-2")
        ```
        """
        file_or_dir = Path(path)

        # Load from Pickle, which only works with the versions that saved it
        if file_or_dir.is_file():
            with open(file_or_dir, "rb") as file:
                try:
                    topic_model = joblib.load(file)
                except (AttributeError, ModuleNotFoundError) as error:
                    raise ValueError(
                        "This model could not be unpickled. A pickle needs BERTopic and the packages it "
                        "was saved with, at the same versions, so a model that BERTopic 0.17.4 or earlier "
                        "pickled does not load in 1.0. Load it with those versions, save it again with "
                        'serialization="safetensors", and load that folder instead. See '
                        "https://maartengr.github.io/BERTopic/migration.html#saved-models"
                    ) from error
            if embedding_model:
                topic_model.embedding_model = select_backend(embedding_model, verbose=topic_model.verbose)
            return topic_model

        # Load from directory or HF
        if file_or_dir.is_dir():
            topics, params, tensors, ctfidf_tensors, ctfidf_config, summaries = save_utils.load_local_files(
                file_or_dir
            )
        elif "/" in str(path):
            topics, params, tensors, ctfidf_tensors, ctfidf_config, summaries = save_utils.load_files_from_hf(
                path
            )
        else:
            raise ValueError("Make sure to either pass a valid directory or HF model.")
        topic_model = _create_model_from_files(
            topics,
            params,
            tensors,
            ctfidf_tensors,
            ctfidf_config,
            summaries,
            load_embedding_model=(embedding_model is None),
        )

        # Replace embedding model if one is specifically chosen
        if embedding_model is not None:
            topic_model.embedding_model = select_backend(embedding_model, verbose=topic_model.verbose)

        return topic_model

    @classmethod
    def merge_models(
        cls, models: list["BERTopic"], min_similarity: float = 0.7, embedding_model=None
    ) -> "BERTopic":
        """Merge multiple pre-trained BERTopic models into a single model.

        Topics are deduplicated based on embedding similarity. Topics with
        cosine similarity >= min_similarity are considered duplicates and
        merged. Dissimilar topics are added as new topics.

        The resulting model can be used for inference (transform) but not
        for fitting new data, as it lacks UMAP and HDBSCAN models.

        Arguments:
            models: A list of fitted BERTopic models to merge.
            min_similarity: Minimum cosine similarity to deduplicate topics.
            embedding_model: Optional embedding model to use for the merged model.

        Returns:
            A new BERTopic model containing topics from all input models.

        Examples:
        ```python
        from bertopic import BERTopic
        from sklearn.datasets import fetch_20newsgroups

        docs = fetch_20newsgroups(subset='all',  remove=('headers', 'footers', 'quotes'))['data']

        # Create three separate models
        topic_model_1 = BERTopic(min_topic_size=5).fit(docs[:4000])
        topic_model_2 = BERTopic(min_topic_size=5).fit(docs[4000:8000])
        topic_model_3 = BERTopic(min_topic_size=5).fit(docs[8000:])

        # Combine all models into one
        merged_model = BERTopic.merge_models([topic_model_1, topic_model_2, topic_model_3])
        ```
        """
        if not models:
            raise ValueError("At least one model is required")

        # Copy and merge topics
        merged_topics = models[0]._topics.copy()
        for model in models[1:]:
            merged_topics.merge_similar(model._topics, min_similarity)

        # Create model with minimal sub-models (no UMAP/HDBSCAN)
        merged_model = BERTopic(
            embedding_model=BaseEmbedder(),
            umap_model=BaseDimensionalityReduction(),
            hdbscan_model=BaseCluster(),
        )
        merged_model._topics = merged_topics
        merged_model._hierarchy = None

        # Each model counted words over its own vocabulary, so their c-TF-IDF rows do not fit together
        for topic in merged_model._topics:
            topic.c_tf_idf = csr_matrix([])

        # Set embedding model
        merged_model.embedding_model = models[0].embedding_model
        if embedding_model is not None:
            verbose = any(m.verbose for m in models)
            merged_model.embedding_model = select_backend(embedding_model, verbose=verbose)

        return merged_model

    def push_to_hf_hub(
        self,
        repo_id: str,
        commit_message: str = "Add BERTopic model",
        token: str | None = None,
        revision: str | None = None,
        private: bool = False,
        create_pr: bool = False,
        model_card: bool = True,
        serialization: str = "safetensors",
        save_embedding_model: Union[str, bool] = True,
        save_ctfidf: bool = False,
    ):
        """Push your BERTopic model to a HuggingFace Hub.

        Whenever you want to upload files to the Hub, you need to log in to your HuggingFace account:

        * Log in to your HuggingFace account with the following command:
            ```bash
            huggingface-cli login

            # or using an environment variable
            huggingface-cli login --token $HUGGINGFACE_TOKEN
            ```
        * Alternatively, you can programmatically login using login() in a notebook or a script:
            ```python
            from huggingface_hub import login
            login()
            ```
        * Or you can give a token with the `token` variable

        Arguments:
            repo_id: The name of your HuggingFace repository
            commit_message: A commit message
            token: Token to add if not already logged in
            revision: Repository revision
            private: Whether to create a private repository
            create_pr: Whether to upload the model as a Pull Request
            model_card: Whether to automatically create a modelcard
            serialization: The type of serialization.
                           Either `safetensors` or `pytorch`
            save_embedding_model: A pointer towards a HuggingFace model to be loaded in with
                                  SentenceTransformers. E.g.,
                                  `google/embeddinggemma-2`
            save_ctfidf: Whether to save c-TF-IDF information


        Examples:
        ```python
        topic_model.push_to_hf_hub(
            repo_id="ArXiv",
            save_ctfidf=True,
            save_embedding_model="google/embeddinggemma-2"
        )
        ```
        """
        return save_utils.push_to_hf_hub(
            model=self,
            repo_id=repo_id,
            commit_message=commit_message,
            token=token,
            revision=revision,
            private=private,
            create_pr=create_pr,
            model_card=model_card,
            serialization=serialization,
            save_embedding_model=save_embedding_model,
            save_ctfidf=save_ctfidf,
        )

    def get_params(self, deep: bool = False) -> dict[str, Any]:
        """Get parameters for this estimator.

        Adapted from:
            https://github.com/scikit-learn/scikit-learn/blob/b3ea3ed6a/sklearn/base.py#L178

        Arguments:
            deep: bool, default=True
                  If True, will return the parameters for this estimator and
                  contained subobjects that are estimators.

        Returns:
            out: Parameter names mapped to their values.
        """
        out = dict()
        for key in self._get_param_names():
            value = getattr(self, key)
            if deep and hasattr(value, "get_params"):
                deep_items = value.get_params().items()
                out.update((key + "__" + k, val) for k, val in deep_items)
            out[key] = value
        return out

    def _embed_corpus(self, corpus: Corpus, verbose: bool | None = None) -> np.ndarray:
        """Embed every row of a corpus, sending each modality to the model that handles it.

        Rows are grouped by modality rather than by which argument they arrived in, so a
        code snippet reaches a code encoder even though c-TF-IDF reads it as text. A row
        carrying both channels — a captioned image — is the mean of the two, which is what
        `documents=` alongside `images=` has always meant.

        Arguments:
            corpus: The corpus whose rows are to be embedded
            verbose: Whether to show a progressbar demonstrating the time to extract embeddings

        Returns:
            embeddings: One row of embeddings per row of the corpus, in corpus order.
        """
        # Backends that only embed text have nothing to group, but would embed media without text as ""
        if not hasattr(self.embedding_model, "embed_media"):
            if any(
                not document and modality not in (Modality.TEXT, Modality.CODE)
                for modality, document in zip(corpus.modality, corpus.documents)
            ):
                raise ValueError(
                    "The embedding model only embeds text, so images, audio or video without documents "
                    "cannot be embedded. Use a model that embeds them, such as "
                    'BERTopic(embedding_model="google/embeddinggemma-2"), or pass a document describing each.'
                )
            return self.embedding_model.embed_documents(corpus.documents, verbose=verbose)

        embeddings = None
        for modality in set(corpus.modality):
            rows = [index for index, value in enumerate(corpus.modality) if value == modality]
            source = corpus.documents if modality in (Modality.TEXT, Modality.CODE) else corpus.media
            vectors = self.embedding_model.embed_media([source[index] for index in rows], modality, verbose)

            if embeddings is None:
                embeddings = np.empty((len(corpus.documents), vectors.shape[1]), dtype=vectors.dtype)
            embeddings[rows] = vectors

        # A media row that also carries text is described by both, so average them in
        captioned = [
            index
            for index, (modality, document) in enumerate(zip(corpus.modality, corpus.documents))
            if document and modality not in (Modality.TEXT, Modality.CODE)
        ]
        if captioned:
            surrogates = self.embedding_model.embed_documents(
                [corpus.documents[index] for index in captioned], verbose
            )
            embeddings[captioned] = np.mean([embeddings[captioned], surrogates], axis=0)

        return embeddings

    def _flatten_representation_models(self) -> list[BaseRepresentation]:
        """Every configured representation model, whether passed alone, in a list, or per aspect."""
        if isinstance(self.representation_model, dict):
            configured = list(self.representation_model.values())
        elif isinstance(self.representation_model, list):
            configured = self.representation_model
        elif self.representation_model is not None:
            configured = [self.representation_model]
        else:
            return []

        # An aspect may itself be a list of models applied in sequence
        return [model for entry in configured for model in (entry if isinstance(entry, list) else [entry])]

    def _convert_media_to_text(self, corpus: Corpus) -> Corpus:
        """Let each converter turn the rows of its own modality into text for c-TF-IDF."""
        for model in self._flatten_representation_models():
            if isinstance(model, TextConverter):
                kinds = ", ".join(sorted(modality.value for modality in model.modalities))
                logger.info(f"Media - Converting {kinds} to text. This might take a while.")
                corpus = model.to_text(corpus)
                logger.info("Media - Completed ✓")
        return corpus

    def _reduce_dimensionality(
        self,
        corpus: Corpus,
        partial_fit: bool = False,
    ) -> Corpus:
        """Reduce dimensionality of embeddings using UMAP and train a UMAP model.

        Arguments:
            corpus: The documents containing embeddings and optionally labels
            partial_fit: Whether to run `partial_fit` for online learning

        Returns:
            corpus: The documents containing reduced embeddings
        """
        logger.info("Dimensionality - Fitting the dimensionality reduction algorithm")

        # Partial fit
        if partial_fit:
            if hasattr(self.umap_model, "partial_fit"):
                self.umap_model = self.umap_model.partial_fit(corpus.embeddings)
                umap_embeddings = self.umap_model.transform(corpus.embeddings)
            elif self.topic_representations_ is None:
                if hasattr(self.umap_model, "fit_transform"):
                    umap_embeddings = self.umap_model.fit_transform(corpus.embeddings)
                else:
                    self.umap_model.fit(corpus.embeddings)
                    umap_embeddings = self.umap_model.transform(corpus.embeddings)
            else:
                umap_embeddings = self.umap_model.transform(corpus.embeddings)

        # Regular fit
        else:
            try:
                # cuml umap needs y to be an numpy array
                if hasattr(self.umap_model, "fit_transform"):
                    umap_embeddings = self.umap_model.fit_transform(corpus.embeddings, y=corpus.y)
                else:
                    self.umap_model.fit(corpus.embeddings, y=corpus.y)
                    umap_embeddings = self.umap_model.transform(corpus.embeddings)
            except TypeError:
                if hasattr(self.umap_model, "fit_transform"):
                    umap_embeddings = self.umap_model.fit_transform(corpus.embeddings, y=corpus.y)
                else:
                    self.umap_model.fit(corpus.embeddings, y=corpus.y)
                    umap_embeddings = self.umap_model.transform(corpus.embeddings)

        # Store umap embeddings removing NaN values
        corpus.umap_embeddings = np.nan_to_num(umap_embeddings)
        logger.info("Dimensionality - Completed \u2713")

        return corpus

    def _cluster_embeddings(self, corpus: Corpus, partial_fit: bool = False) -> Corpus:
        """Cluster UMAP reduced embeddings with HDBSCAN.

        Arguments:
            corpus: The documents containing reduced embeddings, documents, and optionally labels
            partial_fit: Whether to run `partial_fit` for online learning

        Returns:
            data: The data containing topic assignments
        """
        if len(corpus) == 0:
            return corpus

        logger.info("Cluster - Start clustering the reduced embeddings")
        corpus.umap_embeddings = corpus.umap_embeddings.astype(np.float32, copy=False)

        # Fit cluster model
        if partial_fit:
            self.hdbscan_model = self.hdbscan_model.partial_fit(corpus.umap_embeddings)
            corpus.topics = self.hdbscan_model.labels_
        else:
            try:
                self.hdbscan_model.fit(corpus.umap_embeddings, y=corpus.y)
            except TypeError:
                self.hdbscan_model.fit(corpus.umap_embeddings)

            try:
                corpus.topics = self.hdbscan_model.labels_
            except AttributeError:
                corpus.topics = corpus.y

        # Extract probabilities in the cluster model's own label order
        if hasattr(self.hdbscan_model, "probabilities_"):
            corpus.probabilities = self.hdbscan_model.probabilities_

            if self.calculate_probabilities and is_supported_hdbscan(self.hdbscan_model):
                corpus.probabilities = hdbscan_delegator(self.hdbscan_model, "all_points_membership_vectors")

                # HDBSCAN gives a column per cluster and none for outliers, whose share is
                # therefore whatever is left over. Column 0 then lines up with topic -1.
                if -1 in corpus.topics:
                    outlier_probabilities = 1 - np.sum(corpus.probabilities, axis=1)
                    corpus.probabilities = np.hstack(
                        [outlier_probabilities.reshape(-1, 1), corpus.probabilities]
                    )

        # Hand the rows to Topics, which owns them from here on, and renumber by frequency
        if not partial_fit:
            self._topics = (
                Topics().initialize(corpus.topics, probabilities=corpus.probabilities).sort_by_frequency()
            )
            corpus.topics, corpus.probabilities = self._topics.predictions, self._topics.probabilities

        logger.info("Cluster - Completed \u2713")

        return corpus

    def _is_zeroshot(self):
        """Check whether zero-shot topic modeling is possible.

        * Embedding model is necessary to convert zero-shot topics to embeddings
        * Zero-shot topics should be defined
        """
        return self.zeroshot_topic_list is not None and self.embedding_model is not None

    def _extract_representations(
        self,
        corpus: Corpus,
        mappings=None,
        verbose: bool = False,
        fine_tune: bool = True,
    ):
        """Extract topics from the clusters using a class-based TF-IDF.

        Arguments:
            corpus: A Corpus object containing documents and their corresponding IDs
            mappings: The mappings from topic to word
            verbose: Whether to log the process of extracting topics
            fine_tune: If True, the topic representation will be fine-tuned using representation models.
                       If False, the topic representation will remain as the base c-TF-IDF representation.

        Returns:
            c_tf_idf: The resulting matrix giving a value (importance score) for each word per topic
        """
        if verbose:
            action = "Fine-tuning" if fine_tune else "Extracting"
            method = "representation models" if fine_tune else "c-TF-IDF for topic reduction"
            logger.info(f"Representation - {action} topics using {method}.")

        # Calculate c-TF-IDF
        documents_per_topic = corpus.group_documents_by_topic()
        c_tf_idf, words = self._c_tf_idf(documents_per_topic)
        self._topics.set_data(c_tf_idf=c_tf_idf)

        # Extract (additional) topic representations
        topic_representations = self._extract_words_per_topic(
            words=words,
            corpus=corpus,
            fine_tune=fine_tune,
            calculate_aspects=fine_tune,
        )
        self._topics.set_data(representations={"Main": topic_representations})
        self._create_topic_vectors(corpus, mappings=mappings)

        # A hierarchy made earlier describes topics that may no longer exist
        self._hierarchy = None

        if verbose:
            logger.info("Representation - Completed \u2713")

    def _save_representative_docs(self, corpus: Corpus):
        """Save the 3 most representative docs per topic.

        Arguments:
            corpus: Corpus object containing documents and their corresponding IDs
        Updates:
            self.representative_docs_: Populate each topic with 3 representative docs
        """
        representative_docs, _, _, _ = self._extract_representative_docs(
            c_tf_idf=self._topics.c_tf_idf,
            corpus=corpus,
            nr_samples=500,
            nr_repr_docs=3,
        )
        self._topics.set_data(representative_documents=representative_docs)

    def _extract_representative_docs(
        self,
        c_tf_idf: csr_matrix,
        corpus: Corpus,
        nr_samples: int = 500,
        nr_repr_docs: int = 5,
        diversity: float | None = None,
    ) -> Union[List[str], List[List[int]]]:
        """Approximate most representative documents per topic by sampling
        a subset of the documents in each topic and calculating which are
        most representative to their topic based on the cosine similarity between
        c-TF-IDF representations.

        Arguments:
            c_tf_idf: The topic c-TF-IDF representation
            corpus: Corpus object containing documents and their corresponding IDs
            nr_samples: The number of candidate documents to extract per topic
            nr_repr_docs: The number of representative documents to extract per topic
            diversity: The diversity between the most representative documents.
                       If None, no MMR is used. Otherwise, accepts values between 0 and 1.

        Returns:
            repr_docs_mappings: A dictionary from topic to representative documents
            representative_docs: A flat list of representative documents
            repr_doc_indices: Ordered indices of representative documents
                              that belong to each topic
            repr_doc_ids: The indices of representative documents
                          that belong to each topic
        """
        # Find and extract documents that are most similar to the topic
        repr_docs = []
        repr_docs_indices = []
        repr_docs_mappings = {}
        repr_docs_ids = []
        topic_ids = corpus.topic_ids()

        for index, topic_id in enumerate(topic_ids):
            # Slice data from the rows with text, since a topic's media is only ever described
            # for a sample; a topic with no text at all falls back to every row
            selection = corpus.get_topic(topic_id, nr_samples=nr_samples, with_text=True)
            if len(selection.documents) == 0:
                selection = corpus.get_topic(topic_id, nr_samples=nr_samples)

            # Repeated documents, such as cross-posts, are candidates only once
            documents = list(dict.fromkeys(selection.documents))

            # Calculate similarity
            nr_docs = nr_repr_docs if len(documents) > nr_repr_docs else len(documents)
            bow = self.vectorizer_model.transform(documents)
            ctfidf = self.ctfidf_model.transform(bow)
            sim_matrix = cosine_similarity(ctfidf, c_tf_idf[index])

            # Use MMR to find representative but diverse documents
            if diversity:
                docs = mmr(
                    c_tf_idf[index],
                    ctfidf,
                    documents,
                    top_n=nr_docs,
                    diversity=diversity,
                )

            # Extract top n most representative documents
            else:
                indices = np.argpartition(sim_matrix.reshape(1, -1)[0], -nr_docs)[-nr_docs:]
                docs = [documents[index] for index in indices]

            doc_ids = [
                selection.original_indices[index]
                for index, doc in enumerate(selection.documents)
                if doc in docs
            ]
            repr_docs_ids.append(doc_ids)
            repr_docs.extend(docs)
            repr_docs_indices.append(
                [repr_docs_indices[-1][-1] + i + 1 if index != 0 else i for i in range(nr_docs)]
            )

        # Create mapping from topic to representative documents
        repr_docs_mappings = {
            topic_id: repr_docs[i[0] : i[-1] + 1] for topic_id, i in zip(topic_ids, repr_docs_indices)
        }

        return repr_docs_mappings, repr_docs, repr_docs_indices, repr_docs_ids

    def _create_topic_vectors(self, corpus: Corpus = None, mappings=None):
        """Creates embeddings per topics based on their topic representation.

        As a default, topic vectors (topic embeddings) are created by taking
        the average of all document embeddings within a topic. If topics are
        merged, then a weighted average of topic embeddings is taken based on
        the initial topic sizes.

        For the `.partial_fit` and `.update_topics` method, the average
        of all document embeddings is not taken since those are not known.
        Instead, the weighted average of the embeddings of the top n words
        is taken for each topic. The weighting is done based on the c-TF-IDF
        score. This will put more emphasis to words that represent a topic best.
        """
        # Topic embeddings based on input embeddings
        if corpus.embeddings is not None and corpus.documents is not None:
            topic_embeddings = []
            for topic_id in self._topics.topic_ids():
                # If there are no embeddings for a topic, use them from self._topics[topic_id].embedding
                # This happens during `partial_fit` when new topics are added or only a subset of of topics is found
                if topic_id not in corpus.topic_ids():
                    topic_embedding = self._topics[topic_id].embedding
                    topic_embedding = (
                        np.zeros_like(topic_embedding) if topic_embedding is None else topic_embedding
                    )
                else:
                    topic_embedding = corpus.get_topic(topic_id).embeddings.mean(axis=0)
                topic_embeddings.append(topic_embedding)
            self._topics.set_data(embeddings=np.array(topic_embeddings))

        # Topic embeddings based on keyword representations
        elif self.embedding_model is not None and type(self.embedding_model) is not BaseEmbedder:
            topic_list = list(self.topic_representations_.keys())
            topic_list.sort()

            # Only extract top n words
            n = len(self.topic_representations_[topic_list[0]])
            if self.top_n_words < n:
                n = self.top_n_words

            # Extract embeddings for all words in all topics
            topic_words = [self.get_topic(topic) for topic in topic_list]
            topic_words = [word[0] for topic in topic_words for word in topic]
            word_embeddings = self.embedding_model.embed_words(topic_words, verbose=False)

            # Take the weighted average of word embeddings in a topic based on their c-TF-IDF value
            # The embeddings var is a single numpy matrix and therefore slicing is necessary to
            # access the words per topic
            topic_embeddings = []
            for i, topic in enumerate(topic_list):
                word_importance = [val[1] for val in self.get_topic(topic)]
                if sum(word_importance) == 0:
                    word_importance = [1 for _ in range(len(self.get_topic(topic)))]
                topic_embedding = np.average(
                    word_embeddings[i * n : n + (i * n)],
                    weights=word_importance,
                    axis=0,
                )
                topic_embeddings.append(topic_embedding)

            self._topics.set_data(topic_embeddings=np.array(topic_embeddings))

    def _c_tf_idf(
        self,
        documents_per_topic: dict[int, str],
        fit: bool = True,
        partial_fit: bool = False,
    ) -> Tuple[csr_matrix, List[str]]:
        """Calculate a class-based TF-IDF.

        Arguments:
            documents_per_topic: The joined documents per topic such that each topic has a single
                                 string made out of multiple documents
            fit: Whether to fit a new vectorizer or use the fitted self.vectorizer_model
            partial_fit: Whether to run `partial_fit` for online learning

        Returns:
            tf_idf: The resulting matrix giving a value (importance score) for each word per topic
            words: The names of the words to which values were given
        """
        documents = self._preprocess_text(list(documents_per_topic.values()))

        if partial_fit:
            X = self.vectorizer_model.partial_fit(documents).update_bow(documents)
        elif fit:
            X = self.vectorizer_model.fit_transform(documents)
        else:
            X = self.vectorizer_model.transform(documents)

        # Scikit-Learn Deprecation: get_feature_names is deprecated in 1.0
        # and will be removed in 1.2. Please use get_feature_names_out instead.
        if version.parse(sklearn_version) >= version.parse("1.0.0"):
            words = self.vectorizer_model.get_feature_names_out()
        else:
            words = self.vectorizer_model.get_feature_names()

        multiplier = None
        if self.ctfidf_model.seed_words and self.seed_topic_list:
            seed_topic_list = [seed for seeds in self.seed_topic_list for seed in seeds]
            multiplier = np.array(
                [
                    self.ctfidf_model.seed_multiplier if word in self.ctfidf_model.seed_words else 1
                    for word in words
                ]
            )
            multiplier = np.array(
                [1.2 if word in seed_topic_list else value for value, word in zip(multiplier, words)]
            )
        elif self.ctfidf_model.seed_words:
            multiplier = np.array(
                [
                    self.ctfidf_model.seed_multiplier if word in self.ctfidf_model.seed_words else 1
                    for word in words
                ]
            )
        elif self.seed_topic_list:
            seed_topic_list = [seed for seeds in self.seed_topic_list for seed in seeds]
            multiplier = np.array([1.2 if word in seed_topic_list else 1 for word in words])

        if fit:
            self.ctfidf_model = self.ctfidf_model.fit(X, multiplier=multiplier)

        c_tf_idf = self.ctfidf_model.transform(X)

        return c_tf_idf, words

    def _extract_words_per_topic(
        self,
        words: list[str],
        corpus: Corpus,
        c_tf_idf: csr_matrix = None,
        fine_tune: bool = True,
        calculate_aspects: bool = True,
        aspect_to_return: str | None = None,
    ) -> dict[int, TopicRepresentation]:
        """Based on tf_idf scores per topic, extract the top n words per topic.

        If the top words per topic need to be extracted, then only the `words` parameter
        needs to be passed. If the top words per topic in a specific timestamp, then it
        is important to pass the timestamp-based c-TF-IDF matrix and its corresponding
        labels.

        Arguments:
            words: List of all words (sorted according to tf_idf matrix position)
            corpus: Corpus object with documents and their corresponding IDs and Topics
            c_tf_idf: A c-TF-IDF matrix from which to calculate the top words
            fine_tune: If True, the topic representation will be fine-tuned using representation models.
                       If False, the topic representation will remain as the base c-TF-IDF representation.
            calculate_aspects: Whether to calculate additional topic aspects
            aspect_to_return: If `calculate_aspects` is set to True and this parameter is specified,
                              only calculate this aspect rather than all aspects.

        Returns:
            topics: The top words per topic
        """
        if c_tf_idf is None:
            c_tf_idf = self._topics.c_tf_idf

        # Get at least the top 30 indices and values per row in a sparse c-TF-IDF matrix
        top_n_words = max(self.top_n_words, 30)
        indices = self._top_n_idx_sparse(c_tf_idf, top_n_words)
        scores = self._top_n_values_sparse(c_tf_idf, indices)
        sorted_indices = np.argsort(scores, 1)
        indices = np.take_along_axis(indices, sorted_indices, axis=1)
        scores = np.take_along_axis(scores, sorted_indices, axis=1)

        # Get top 30 words per topic based on c-TF-IDF score, the candidates every representation starts from
        candidates = {
            topic_id: Keywords(
                [
                    (words[word_index], score) if word_index is not None and score > 0 else ("", 0.00001)
                    for word_index, score in zip(indices[index][::-1], scores[index][::-1])
                ]
            )
            for index, topic_id in enumerate(corpus.topic_ids())
        }

        # Main topic representation fine-tuning
        if fine_tune and (
            (isinstance(self.representation_model, dict) and "Main" in self.representation_model)
            or isinstance(self.representation_model, (BaseRepresentation, list))
        ):
            topic_representations = self._apply_representation_models(
                representation_models=self.representation_model,
                corpus=corpus,
                topic_representations=candidates.copy(),
                c_tf_idf=c_tf_idf,
                name="Main",
            )
        else:
            # Without a representation model the top c-TF-IDF words are the representation,
            # so cut the extra candidates back to the `top_n_words` that were asked for
            topic_representations = {
                topic_id: Keywords(keywords.data[: self.top_n_words])
                for topic_id, keywords in candidates.items()
            }

        # Extract topic representations other than the Main one (called aspects), each from the candidates
        if calculate_aspects and isinstance(self.representation_model, dict):
            if aspect_to_return is not None:
                if aspect_to_return not in self.representation_model:
                    raise ValueError(
                        f"Representation {aspect_to_return!r} not found in the `.representation_model` keys: "
                        f"{list(self.representation_model.keys())}"
                    )
                return self._apply_representation_models(
                    representation_models=self.representation_model[aspect_to_return],
                    corpus=corpus,
                    topic_representations=candidates.copy(),
                    c_tf_idf=c_tf_idf,
                    name=aspect_to_return,
                )
            else:
                for name, aspect_model in self.representation_model.items():
                    if name != "Main":
                        aspect = self._apply_representation_models(
                            representation_models=aspect_model,
                            corpus=corpus,
                            topic_representations=candidates.copy(),
                            c_tf_idf=c_tf_idf,
                            name=name,
                        )
                        self._topics.set_data(representations={name: aspect})

        return topic_representations

    def _apply_representation_models(
        self,
        representation_models: dict[str, BaseRepresentation] | list[BaseRepresentation] | BaseRepresentation,
        corpus: Corpus,
        topic_representations: dict[int, TopicRepresentation],
        c_tf_idf: csr_matrix,
        name: str,
    ) -> dict[int, TopicRepresentation]:
        """Apply representation models to extract additional topic aspects.

        Arguments:
            representation_models: One or more representation models.
            corpus: Corpus object with documents and their corresponding IDs, Topics, and (potentially) embeddings
            topic_representations: Current topic representation to be fine-tuned
            c_tf_idf: A c-TF-IDF matrix from which to calculate the top words
            name: The name of the aspect to apply, either "Main" for the main representation or the name of an aspect

        Returns:
            topic_representations: The updated topic representation
        """
        if isinstance(representation_models, dict):
            selected_model = representation_models[name]
        else:
            selected_model = representation_models

        if selected_model:
            if isinstance(selected_model, BaseRepresentation):
                topic_representations = selected_model.extract_topics(
                    topic_model=self,
                    corpus=corpus,
                    topic_representations=topic_representations,
                    c_tf_idf=c_tf_idf,
                )
            elif isinstance(selected_model, list):
                for tuner in selected_model:
                    topic_representations = tuner.extract_topics(
                        topic_model=self,
                        corpus=corpus,
                        topic_representations=topic_representations,
                        c_tf_idf=c_tf_idf,
                    )
            else:
                raise TypeError(
                    f"unsupported type {type(selected_model).__name__} for representation_model[{name!r}]"
                )

        return topic_representations

    def _reduce_topics(self, corpus: Corpus, use_ctfidf: bool = False) -> Corpus:
        """Reduce topics to self.nr_topics.

        Arguments:
            corpus: Corpus and their corresponding IDs and Topics
            use_ctfidf: Whether to calculate distances between topics based on c-TF-IDF embeddings. If False, semantic
                        embeddings are used.

        Returns:
            documents: Updated dataframe with documents and the reduced number of Topics
        """
        if self.nr_topics:
            logger.info("Topic reduction - Reducing number of topics")
            initial_nr_topics = len(self._topics)

            if isinstance(self.nr_topics, int):
                if self.nr_topics < initial_nr_topics:
                    corpus = self._reduce_to_n_topics(corpus, use_ctfidf)
                else:
                    logger.info(
                        f"Topic reduction - Number of topics ({self.nr_topics}) is equal or higher than the clustered topics({len(self._topics)})."
                    )
                    self._extract_representations(corpus, verbose=self.verbose)
                    return corpus
            elif isinstance(self.nr_topics, str):
                corpus = self._auto_reduce_topics(corpus, use_ctfidf)
            else:
                raise ValueError("nr_topics needs to be an int or 'auto'! ")

            logger.info(
                f"Topic reduction - Reduced number of topics from {initial_nr_topics} to {len(self._topics)}"
            )
        return corpus

    def _reduce_to_n_topics(self, corpus: Corpus, use_ctfidf: bool = False) -> Corpus:
        """Reduce topics to self.nr_topics.

        Arguments:
            corpus: Corpus and their corresponding IDs and Topics
            use_ctfidf: Whether to calculate distances between topics based on c-TF-IDF embeddings. If False, semantic
                        embedding are used.

        Returns:
            corpus: Updated Corpus and the reduced number of Topics
        """
        # The outlier and zero-shot topics are never merged, since the user named the zero-shot ones
        nr_kept = self._outliers + sum(topic.topic_type == TopicType.ZERO_SHOT for topic in self._topics)
        nr_clusters = self.nr_topics - nr_kept
        if nr_clusters < 1:
            raise ValueError(
                f"nr_topics ({self.nr_topics}) must exceed the {nr_kept} outlier and zero-shot topics, "
                "which topic reduction never merges."
            )

        # Sorting puts the kept topics first, even after merge_models
        self._topics.sort_by_frequency()
        topic_ids = self._topics.topic_ids()

        # Create topic distance matrix
        topic_embeddings = select_topic_representation(
            self._topics.c_tf_idf, self._topics.embeddings, use_ctfidf, output_ndarray=True
        )[0][nr_kept:]
        distance_matrix = 1 - cosine_similarity(topic_embeddings)
        np.fill_diagonal(distance_matrix, 0)

        # Cluster the topic embeddings using AgglomerativeClustering
        if version.parse(sklearn_version) >= version.parse("1.4.0"):
            cluster = AgglomerativeClustering(nr_clusters, metric="precomputed", linkage="average")
        else:
            cluster = AgglomerativeClustering(nr_clusters, affinity="precomputed", linkage="average")
        cluster.fit(distance_matrix)

        # Kept topics map to themselves, clustered topics to IDs after them, until sort_by_frequency renumbers
        mappings = {topic_id: topic_id for topic_id in topic_ids[:nr_kept]}
        for topic_id, label in zip(topic_ids[nr_kept:], cluster.labels_):
            mappings[topic_id] = nr_kept + int(label)
        self._topics.merge(mappings)

        # Update frequency, then take the rows back from the single store that owns them
        self._topics.sort_by_frequency()
        corpus.topics, corpus.probabilities = self._topics.predictions, self._topics.probabilities

        # Recalculate topic representations
        self._extract_representations(corpus=corpus, verbose=self.verbose)

        return corpus

    def _auto_reduce_topics(self, corpus: Corpus, use_ctfidf: bool = False) -> Corpus:
        """Reduce the number of topics automatically using HDBSCAN.

        Arguments:
            corpus: Corpus and their corresponding IDs and Topics
            use_ctfidf: Whether to calculate distances between topics based on c-TF-IDF embeddings. If False, the
                        embeddings from the embedding model are used.

        Returns:
            corpus: Updated Corpus and the reduced number of Topics
        """
        # The outlier and zero-shot topics are never merged, since the user named the zero-shot ones,
        # and sorting puts them first, even after merge_models
        self._topics.sort_by_frequency()
        nr_kept = self._outliers + sum(topic.topic_type == TopicType.ZERO_SHOT for topic in self._topics)
        unique_topics = self._topics.topic_ids()[nr_kept:]

        # Find similar topics
        embeddings = select_topic_representation(
            self.c_tf_idf_, self.topic_embeddings_, use_ctfidf, output_ndarray=True
        )[0]
        norm_data = normalize(embeddings, norm="l2")

        # Fewer than two topics, such as when every document is an outlier, leaves nothing to cluster
        if len(unique_topics) < 2:
            predictions = [-1] * len(unique_topics)
        elif HAS_HDBSCAN:
            predictions = HDBSCAN(
                min_cluster_size=2,
                metric="euclidean",
                cluster_selection_method="eom",
                prediction_data=True,
            ).fit_predict(norm_data[nr_kept:])
        else:
            predictions = SK_HDBSCAN(
                min_cluster_size=2, metric="euclidean", cluster_selection_method="eom", n_jobs=-1
            ).fit_predict(norm_data[nr_kept:])

        # Map clusters to their lowest topic_id
        cluster_to_lowest = {}
        for cluster, topic_id in zip(predictions, unique_topics):
            if cluster != -1:  # Ignore unclustered items
                if cluster not in cluster_to_lowest:
                    cluster_to_lowest[cluster] = topic_id
                else:
                    cluster_to_lowest[cluster] = min(cluster_to_lowest[cluster], topic_id)

        # Map each topic_id to the lowest topic_id in its cluster
        mapped_topics = {}
        for cluster, topic_id in zip(predictions, unique_topics):
            if cluster == -1:
                mapped_topics[topic_id] = topic_id  # No clustering, stays the same
            else:
                mapped_topics[topic_id] = cluster_to_lowest[cluster]

        # Map every topic, not just those holding documents, so no topic is left behind
        mappings = {topic_id: mapped_topics.get(topic_id, topic_id) for topic_id in self._topics.topic_ids()}
        self._topics.merge(mappings)

        # Update frequency, then take the rows back from the single store that owns them
        self._topics.sort_by_frequency()
        corpus.topics, corpus.probabilities = self._topics.predictions, self._topics.probabilities

        # Recalculate topic representations
        self._extract_representations(corpus=corpus, verbose=self.verbose)

        return corpus

    def _preprocess_text(self, documents: np.ndarray) -> List[str]:
        r"""Basic preprocessing of text.

        Steps:
            * Replace \n and \t with whitespace
            * Only keep alpha-numerical characters when `language` is "english"
        """
        cleaned_documents = [doc.replace("\n", " ") for doc in documents]
        cleaned_documents = [doc.replace("\t", " ") for doc in cleaned_documents]
        if self.language == "english":
            cleaned_documents = [re.sub(r"[^A-Za-z0-9 ]+", "", doc) for doc in cleaned_documents]
        cleaned_documents = [doc if doc != "" else "emptydoc" for doc in cleaned_documents]
        return cleaned_documents

    @staticmethod
    def _top_n_idx_sparse(matrix: csr_matrix, n: int) -> np.ndarray:
        """Return indices of top n values in each row of a sparse matrix.

        Retrieved from:
            https://stackoverflow.com/questions/49207275/finding-the-top-n-values-in-a-row-of-a-scipy-sparse-matrix

        Arguments:
            matrix: The sparse matrix from which to get the top n indices per row
            n: The number of highest values to extract from each row

        Returns:
            indices: The top n indices per row
        """
        indices = []
        for le, ri in zip(matrix.indptr[:-1], matrix.indptr[1:]):
            n_row_pick = min(n, ri - le)
            values = matrix.indices[le + np.argpartition(matrix.data[le:ri], -n_row_pick)[-n_row_pick:]]
            values = [values[index] if len(values) >= index + 1 else None for index in range(n)]
            indices.append(values)
        return np.array(indices)

    @staticmethod
    def _top_n_values_sparse(matrix: csr_matrix, indices: np.ndarray) -> np.ndarray:
        """Return the top n values for each row in a sparse matrix.

        Arguments:
            matrix: The sparse matrix from which to get the top n indices per row
            indices: The top n indices per row

        Returns:
            top_values: The top n scores per row
        """
        top_values = []
        for row, values in enumerate(indices):
            scores = np.array([matrix[row, value] if value is not None else 0 for value in values])
            top_values.append(scores)
        return np.array(top_values)

    @classmethod
    def _get_param_names(cls):
        """Get parameter names for the estimator.

        Adapted from:
            https://github.com/scikit-learn/scikit-learn/blob/b3ea3ed6a/sklearn/base.py#L178
        """
        init_signature = inspect.signature(cls.__init__)
        parameters = sorted(
            [
                p.name
                for p in init_signature.parameters.values()
                if p.name != "self" and p.kind != p.VAR_KEYWORD
            ]
        )
        return parameters

    def __str__(self):
        """Get a string representation of the current object.

        Returns:
            str: Human readable representation of the most important model parameters.
                 The parameters that represent models are ignored due to their length.
        """
        parameters = ""
        for parameter, value in self.get_params().items():
            value = str(value)
            if "(" in value and value[0] != "(":
                value = value.split("(")[0] + "(...)"
            parameters += f"{parameter}={value}, "

        return f"BERTopic({parameters[:-2]})"

c_tf_idf_: csr_matrix | None property

For backwards compatibility.

custom_labels_: list[str] | None property

For backwards compatibility. None until set_topic_labels is called.

hierarchy_: IntoDataFrame | None property

Get the TopicHierarchy object that contains all hierarchical topic information.

probabilities_: list[int] property

For backwards compatibility.

representative_docs_: dict[int, str] property

For backwards compatibility.

representative_images_: dict[int, Any] property

For backwards compatibility.

representative_items_: dict[int, list] property

The media that represent each topic, whatever their modality.

topic_aspects_: dict[int, dict[str, list[tuple[str, float]]]] property

For backwards compatibility.

topic_embeddings_: np.ndarray property

For backwards compatibility.

topic_labels_: dict[int, str] property

For backwards compatibility.

topic_representations_: dict[int, list[tuple[str, float]]] property

For backwards compatibility.

topic_sizes_: dict[int, int] property

For backwards compatibility.

topics: Topics property

Get the Topics object that contains all topic information.

topics_: list[int] property

For backwards compatibility.

__init__(language='english', top_n_words=10, n_gram_range=(1, 1), min_topic_size=10, nr_topics=None, low_memory=False, calculate_probabilities=False, seed_topic_list=None, zeroshot_topic_list=None, zeroshot_min_similarity=0.7, embedding_model=None, umap_model=None, hdbscan_model=None, vectorizer_model=None, ctfidf_model=None, representation_model=None, verbose=False)

BERTopic initialization.

Parameters:

Name	Type	Description	Default
language	str	The main language used in your documents, one of bertopic.backend.languages or "multilingual". The default embedding model, EmbeddingGemma 2, supports 100+ languages.	'english'
top_n_words	int	The number of words per topic to extract. Setting this too high can negatively impact topic embeddings as topics are typically best represented by at most 10 words.	10
n_gram_range	tuple[int, int]	The n-gram range for the CountVectorizer. Advised to keep high values between 1 and 3. More would likely lead to memory issues. NOTE: This param will not be used if you pass in your own CountVectorizer.	(1, 1)
min_topic_size	int	The minimum size of the topic. Increasing this value will lead to a lower number of clusters/topics and vice versa. It is the same parameter as min_cluster_size in HDBSCAN. NOTE: This param will not be used if you are using hdbscan_model.	10
nr_topics	int | str | None	Specifying the number of topics will reduce the initial number of topics to the value specified. This reduction can take a while as each reduction in topics (-1) activates a c-TF-IDF calculation. If this is set to None, no reduction is applied. Use "auto" to automatically reduce topics using HDBSCAN. Zero-shot topics are never merged. NOTE: Controlling the number of topics is best done by adjusting min_topic_size first before adjusting this parameter.	None
low_memory	bool	Sets UMAP low memory to True to make sure less memory is used. NOTE: This is only used in UMAP. For example, if you use PCA instead of UMAP this parameter will not be used.	False
calculate_probabilities	bool	Calculate the probabilities of all topics per document instead of the probability of the assigned topic per document. This could slow down the extraction of topics if you have many documents (> 100_000). NOTE: If false you cannot use the corresponding visualization method visualize_probabilities. NOTE: This is an approximation of topic probabilities as used in HDBSCAN and not an exact representation.	False
seed_topic_list	list[list[str]] | None	A list of seed words per topic to converge around	None
zeroshot_topic_list	list[str] | None	A list of topic names to use for zero-shot classification	None
zeroshot_min_similarity	float	The minimum similarity between a zero-shot topic and a document for assignment. The higher this value, the more confident the model needs to be to assign a zero-shot topic to a document.	0.7
verbose	bool	Changes the verbosity of the model, Set to True if you want to track the stages of the model.	False
embedding_model		Use a custom embedding model. The following backends are currently supported * SentenceTransformers * Flair * Spacy * Gensim * USE (TF-Hub) You can also pass in a string that points to one of the following sentence-transformers models: * https://www.sbert.net/docs/pretrained_models.html	None
umap_model		Pass in a UMAP model to be used instead of the default. NOTE: You can also pass in any dimensionality reduction algorithm as long as it has .fit and .transform functions.	None
hdbscan_model		Pass in a hdbscan.HDBSCAN model to be used instead of the default NOTE: You can also pass in any clustering algorithm as long as it has .fit and .predict functions along with the .labels_ variable.	None
vectorizer_model	CountVectorizer	Pass in a custom CountVectorizer instead of the default model.	None
ctfidf_model	TfidfTransformer	Pass in a custom ClassTfidfTransformer instead of the default model.	None
representation_model	BaseRepresentation	Pass in a model that fine-tunes the topic representations calculated through c-TF-IDF. Models from bertopic.representation are supported.	None

Source code in bertopic\_bertopic.py

def __init__(
    self,
    language: str = "english",
    top_n_words: int = 10,
    n_gram_range: tuple[int, int] = (1, 1),
    min_topic_size: int = 10,
    nr_topics: int | str | None = None,
    low_memory: bool = False,
    calculate_probabilities: bool = False,
    seed_topic_list: list[list[str]] | None = None,
    zeroshot_topic_list: list[str] | None = None,
    zeroshot_min_similarity: float = 0.7,
    embedding_model=None,
    umap_model=None,
    hdbscan_model=None,
    vectorizer_model: CountVectorizer = None,
    ctfidf_model: TfidfTransformer = None,
    representation_model: BaseRepresentation = None,
    verbose: bool = False,
):
    """BERTopic initialization.

    Arguments:
        language: The main language used in your documents, one of bertopic.backend.languages
                  or "multilingual". The default embedding model, EmbeddingGemma 2, supports
                  100+ languages.
        top_n_words: The number of words per topic to extract. Setting this
                     too high can negatively impact topic embeddings as topics
                     are typically best represented by at most 10 words.
        n_gram_range: The n-gram range for the CountVectorizer.
                      Advised to keep high values between 1 and 3.
                      More would likely lead to memory issues.
                      NOTE: This param will not be used if you pass in your own
                      CountVectorizer.
        min_topic_size: The minimum size of the topic. Increasing this value will lead
                        to a lower number of clusters/topics and vice versa.
                        It is the same parameter as `min_cluster_size` in HDBSCAN.
                        NOTE: This param will not be used if you are using `hdbscan_model`.
        nr_topics: Specifying the number of topics will reduce the initial
                   number of topics to the value specified. This reduction can take
                   a while as each reduction in topics (-1) activates a c-TF-IDF
                   calculation. If this is set to None, no reduction is applied. Use
                   "auto" to automatically reduce topics using HDBSCAN. Zero-shot topics
                   are never merged.
                   NOTE: Controlling the number of topics is best done by adjusting
                   `min_topic_size` first before adjusting this parameter.
        low_memory: Sets UMAP low memory to True to make sure less memory is used.
                    NOTE: This is only used in UMAP. For example, if you use PCA instead of UMAP
                    this parameter will not be used.
        calculate_probabilities: Calculate the probabilities of all topics
                                 per document instead of the probability of the assigned
                                 topic per document. This could slow down the extraction
                                 of topics if you have many documents (> 100_000).
                                 NOTE: If false you cannot use the corresponding
                                 visualization method `visualize_probabilities`.
                                 NOTE: This is an approximation of topic probabilities
                                 as used in HDBSCAN and not an exact representation.
        seed_topic_list: A list of seed words per topic to converge around
        zeroshot_topic_list: A list of topic names to use for zero-shot classification
        zeroshot_min_similarity: The minimum similarity between a zero-shot topic and
                                 a document for assignment. The higher this value, the more
                                 confident the model needs to be to assign a zero-shot topic to a document.
        verbose: Changes the verbosity of the model, Set to True if you want
                 to track the stages of the model.
        embedding_model: Use a custom embedding model.
                         The following backends are currently supported
                           * SentenceTransformers
                           * Flair
                           * Spacy
                           * Gensim
                           * USE (TF-Hub)
                         You can also pass in a string that points to one of the following
                         sentence-transformers models:
                           * https://www.sbert.net/docs/pretrained_models.html
        umap_model: Pass in a UMAP model to be used instead of the default.
                    NOTE: You can also pass in any dimensionality reduction algorithm as long
                    as it has `.fit` and `.transform` functions.
        hdbscan_model: Pass in a hdbscan.HDBSCAN model to be used instead of the default
                       NOTE: You can also pass in any clustering algorithm as long as it has
                       `.fit` and `.predict` functions along with the `.labels_` variable.
        vectorizer_model: Pass in a custom `CountVectorizer` instead of the default model.
        ctfidf_model: Pass in a custom ClassTfidfTransformer instead of the default model.
        representation_model: Pass in a model that fine-tunes the topic representations
                              calculated through c-TF-IDF. Models from `bertopic.representation`
                              are supported.
    """
    # Topic-based parameters
    if top_n_words > 100:
        logger.warning(
            "Note that extracting more than 100 words from a sparse can slow down computation quite a bit."
        )

    self.top_n_words = top_n_words
    self.min_topic_size = min_topic_size
    self.nr_topics = nr_topics
    self.low_memory = low_memory
    self.calculate_probabilities = calculate_probabilities
    self.verbose = verbose
    self.seed_topic_list = seed_topic_list
    self.zeroshot_topic_list = zeroshot_topic_list
    self.zeroshot_min_similarity = zeroshot_min_similarity

    # Embedding model
    self.language = language if not embedding_model else None
    self.embedding_model = embedding_model

    # Vectorizer
    self.n_gram_range = n_gram_range
    self.vectorizer_model = vectorizer_model or CountVectorizer(ngram_range=self.n_gram_range)
    self.ctfidf_model = ctfidf_model or ClassTfidfTransformer()

    # Representation model
    self.representation_model = representation_model

    # UMAP or another algorithm that has .fit and .transform functions
    if umap_model is not None:
        self.umap_model = umap_model
    else:
        try:
            from umap import UMAP

            self.umap_model = UMAP(
                n_neighbors=15,
                n_components=5,
                min_dist=0.0,
                metric="cosine",
                low_memory=self.low_memory,
            )
        except (ImportError, ModuleNotFoundError):
            self.umap_model = PCA(n_components=5)

    # HDBSCAN or another clustering algorithm that has .fit and .predict functions and
    # the .labels_ variable to extract the labels

    if hdbscan_model is not None:
        self.hdbscan_model = hdbscan_model
    elif HAS_HDBSCAN:
        self.hdbscan_model = HDBSCAN(
            min_cluster_size=self.min_topic_size,
            metric="euclidean",
            cluster_selection_method="eom",
            prediction_data=True,
        )
    else:
        self.hdbscan_model = SK_HDBSCAN(
            min_cluster_size=self.min_topic_size,
            metric="euclidean",
            cluster_selection_method="eom",
            n_jobs=-1,
        )

    # Track topics complete with metadata
    self._topics: Topics = Topics()
    self._hierarchy: TopicHierarchy | None = None

    if verbose:
        logger.set_level("DEBUG")
    else:
        logger.set_level("WARNING")

__str__()

Get a string representation of the current object.

Returns:

Name	Type	Description
str		Human readable representation of the most important model parameters. The parameters that represent models are ignored due to their length.

Source code in bertopic\_bertopic.py

def __str__(self):
    """Get a string representation of the current object.

    Returns:
        str: Human readable representation of the most important model parameters.
             The parameters that represent models are ignored due to their length.
    """
    parameters = ""
    for parameter, value in self.get_params().items():
        value = str(value)
        if "(" in value and value[0] != "(":
            value = value.split("(")[0] + "(...)"
        parameters += f"{parameter}={value}, "

    return f"BERTopic({parameters[:-2]})"

delete_topics(topics_to_delete)

Delete topics from the topic model.

The deleted topics will be mapped to -1 (outlier topic). Document predictions for deleted topics become -1. Remaining topics are renumbered by frequency.

Parameters:

Name	Type	Description	Default
topics_to_delete	list[int] | int	List of topic IDs to delete or a single topic ID.	required

Examples:

# Delete topics 3 and 5
topic_model.delete_topics([3, 5])

Source code in bertopic\_bertopic.py

def delete_topics(self, topics_to_delete: list[int] | int) -> None:
    """Delete topics from the topic model.

    The deleted topics will be mapped to -1 (outlier topic). Document predictions
    for deleted topics become -1. Remaining topics are renumbered by frequency.

    Arguments:
        topics_to_delete: List of topic IDs to delete or a single topic ID.

    Examples:
    ```python
    # Delete topics 3 and 5
    topic_model.delete_topics([3, 5])
    ```
    """
    check_is_fitted(self)

    self._topics.delete(topics_to_delete)
    self._topics.sort_by_frequency()

    # A hierarchy made earlier describes topics that may no longer exist
    self._hierarchy = None

find_topics(search_term=None, image=None, top_n=5)

Find topics most similar to a search_term.

Creates an embedding for a search query and compares that with the topic embeddings. The most similar topics are returned along with their similarity values.

The query is specified using search_term for text queries or image for image queries.

The search_term can be of any size but since it is compared with the topic representation it is advised to keep it below 5 words.

Parameters:

Name	Type	Description	Default
search_term	str | list[str] | None	the term you want to use to search for topics, or a list of terms whose embeddings are averaged into one query.	None
image	str | None	path to the image you want to use to search for topics.	None
top_n	int	the number of topics to return	5

Returns:

Name	Type	Description
similar_topics	list[int]	the most similar topics from high to low
similarity	list[float]	the similarity scores from high to low

Examples: You can use the underlying embedding model to find topics that best represent the search term:

topics, similarity = topic_model.find_topics("sports", top_n=5)

Note that the search query is typically more accurate if the search_term consists of a phrase or multiple words.

Source code in bertopic\_bertopic.py

def find_topics(
    self, search_term: str | list[str] | None = None, image: str | None = None, top_n: int = 5
) -> tuple[list[int], list[float]]:
    """Find topics most similar to a search_term.

    Creates an embedding for a search query and compares that with
    the topic embeddings. The most similar topics are returned
    along with their similarity values.

    The query is specified using search_term for text queries or image for image queries.

    The search_term can be of any size but since it is compared
    with the topic representation it is advised to keep it
    below 5 words.

    Arguments:
        search_term: the term you want to use to search for topics, or a list of terms whose
                     embeddings are averaged into one query.
        image: path to the image you want to use to search for topics.
        top_n: the number of topics to return

    Returns:
        similar_topics: the most similar topics from high to low
        similarity: the similarity scores from high to low

    Examples:
    You can use the underlying embedding model to find topics that
    best represent the search term:

    ```python
    topics, similarity = topic_model.find_topics("sports", top_n=5)
    ```

    Note that the search query is typically more accurate if the
    search_term consists of a phrase or multiple words.
    """
    if self.embedding_model is None:
        raise Exception("This method can only be used if you did not use custom embeddings.")

    # The outlier topic holds what fits no topic, so it is not a topic to find
    topic_list = self._topics.topic_ids(outliers=False)
    topic_embeddings = self.topic_embeddings_[self._outliers :]

    # Extract search_term embeddings and compare with topic embeddings
    if search_term is not None:
        search_terms = [search_term] if isinstance(search_term, str) else search_term
        search_embedding = self.embedding_model.embed_words(search_terms, verbose=False).mean(axis=0)
    elif image is not None:
        search_embedding = self.embedding_model.embed_media([image], Modality.IMAGE).flatten()
    sims = cosine_similarity(search_embedding.reshape(1, -1), topic_embeddings).flatten()

    # Extract topics most similar to search_term
    ids = np.argsort(sims)[-top_n:]
    similarity = [sims[i] for i in ids][::-1]
    similar_topics = [topic_list[index] for index in ids][::-1]

    return similar_topics, similarity

fit(documents=None, embeddings=None, images=None, y=None, *, audio=None, video=None, code=None)

Fit the models on a collection of documents and generate topics.

Parameters:

Name	Type	Description	Default
documents	list[str] | None	A list of documents to fit on	None
embeddings	ndarray	Pre-trained document embeddings. These can be used instead of the sentence-transformer model	None
images	list | None	A list of paths to the images to fit on, or the images themselves	None
audio	list | None	A list of paths to the audio to fit on, or the clips themselves	None
video	list | None	A list of paths to the video to fit on, or the clips themselves	None
code	list[str] | None	A list of source code snippets to fit on	None
y	list[int] | ndarray	The target class for (semi)-supervised modeling. Use -1 if no class for a specific instance is specified.	None

Examples:

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups

docs = fetch_20newsgroups(subset='all')['data']
topic_model = BERTopic().fit(docs)

If you want to use your own embeddings, use it as follows:

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups
from sentence_transformers import SentenceTransformer

# Create embeddings
docs = fetch_20newsgroups(subset='all')['data']
sentence_model = SentenceTransformer("google/embeddinggemma-2", default_prompt_name="Clustering")
sentence_model.max_seq_length = 1024
embeddings = sentence_model.encode(docs, show_progress_bar=True)

# Create topic model
topic_model = BERTopic().fit(docs, embeddings)

Source code in bertopic\_bertopic.py

def fit(
    self,
    documents: list[str] | None = None,
    embeddings: np.ndarray = None,
    images: list | None = None,
    y: list[int] | np.ndarray = None,
    *,
    audio: list | None = None,
    video: list | None = None,
    code: list[str] | None = None,
) -> "BERTopic":
    """Fit the models on a collection of documents and generate topics.

    Arguments:
        documents: A list of documents to fit on
        embeddings: Pre-trained document embeddings. These can be used
                    instead of the sentence-transformer model
        images: A list of paths to the images to fit on, or the images themselves
        audio: A list of paths to the audio to fit on, or the clips themselves
        video: A list of paths to the video to fit on, or the clips themselves
        code: A list of source code snippets to fit on
        y: The target class for (semi)-supervised modeling. Use -1 if no class for a
           specific instance is specified.

    Examples:
    ```python
    from bertopic import BERTopic
    from sklearn.datasets import fetch_20newsgroups

    docs = fetch_20newsgroups(subset='all')['data']
    topic_model = BERTopic().fit(docs)
    ```

    If you want to use your own embeddings, use it as follows:

    ```python
    from bertopic import BERTopic
    from sklearn.datasets import fetch_20newsgroups
    from sentence_transformers import SentenceTransformer

    # Create embeddings
    docs = fetch_20newsgroups(subset='all')['data']
    sentence_model = SentenceTransformer("google/embeddinggemma-2", default_prompt_name="Clustering")
    sentence_model.max_seq_length = 1024
    embeddings = sentence_model.encode(docs, show_progress_bar=True)

    # Create topic model
    topic_model = BERTopic().fit(docs, embeddings)
    ```
    """
    self.fit_transform(
        documents=documents,
        embeddings=embeddings,
        y=y,
        images=images,
        audio=audio,
        video=video,
        code=code,
    )
    return self

fit_transform(documents=None, embeddings=None, images=None, y=None, *, audio=None, video=None, code=None)

Fit the models on a collection of documents, generate topics, and return the probabilities and topic per document.

Note that the inline docstrings follow the standard pipeline of BERTopic:

• 1. Embed documents
• 1. Dimensionality reduction
• 1. Cluster Documents
• 1. Bag-of-words
• 1. Topic representation
• 1. (Optional) Fine-tune Topic representation

Parameters:

Name	Type	Description	Default
documents	list[str] | None	A list of documents to fit on	None
embeddings	ndarray | None	Pre-trained document embeddings. These can be used instead of the sentence-transformer model	None
images	list | None	A list of paths to the images to fit on, or the images themselves	None
audio	list | None	A list of paths to the audio to fit on, or the clips themselves	None
video	list | None	A list of paths to the video to fit on, or the clips themselves	None
code	list[str] | None	A list of source code snippets to fit on	None
y	list[int] | ndarray | None	The target class for (semi)-supervised modeling. Use -1 if no class for a specific instance is specified.	None

Returns:

Name	Type	Description
predictions	list[int]	Topic predictions for each documents
probabilities	ndarray | None	The probability of the assigned topic per document. If calculate_probabilities in BERTopic is set to True, then it calculates the probabilities of all topics across all documents instead of only the assigned topic. This, however, slows down computation and may increase memory usage.

Examples:

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups

docs = fetch_20newsgroups(subset='all')['data']
topic_model = BERTopic()
topics, probs = topic_model.fit_transform(docs)

If you want to use your own embeddings, use it as follows:

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups
from sentence_transformers import SentenceTransformer

# Create embeddings
docs = fetch_20newsgroups(subset='all')['data']
sentence_model = SentenceTransformer("google/embeddinggemma-2", default_prompt_name="Clustering")
sentence_model.max_seq_length = 1024
embeddings = sentence_model.encode(docs, show_progress_bar=True)

# Create topic model
topic_model = BERTopic()
topics, probs = topic_model.fit_transform(docs, embeddings)

Source code in bertopic\_bertopic.py

def fit_transform(
    self,
    documents: list[str] | None = None,
    embeddings: np.ndarray | None = None,
    images: list | None = None,
    y: list[int] | np.ndarray | None = None,
    *,
    audio: list | None = None,
    video: list | None = None,
    code: list[str] | None = None,
) -> tuple[list[int], np.ndarray | None]:
    """Fit the models on a collection of documents, generate topics,
    and return the probabilities and topic per document.

    Note that the inline docstrings follow the standard pipeline of BERTopic:

    * 1. Embed documents
    * 2. Dimensionality reduction
    * 3. Cluster Documents
    * 4. Bag-of-words
    * 5. Topic representation
    * 6. (Optional) Fine-tune Topic representation

    Arguments:
        documents: A list of documents to fit on
        embeddings: Pre-trained document embeddings. These can be used
                    instead of the sentence-transformer model
        images: A list of paths to the images to fit on, or the images themselves
        audio: A list of paths to the audio to fit on, or the clips themselves
        video: A list of paths to the video to fit on, or the clips themselves
        code: A list of source code snippets to fit on
        y: The target class for (semi)-supervised modeling. Use -1 if no class for a
           specific instance is specified.

    Returns:
        predictions: Topic predictions for each documents
        probabilities: The probability of the assigned topic per document.
                       If `calculate_probabilities` in BERTopic is set to True, then
                       it calculates the probabilities of all topics across all documents
                       instead of only the assigned topic. This, however, slows down
                       computation and may increase memory usage.

    Examples:
    ```python
    from bertopic import BERTopic
    from sklearn.datasets import fetch_20newsgroups

    docs = fetch_20newsgroups(subset='all')['data']
    topic_model = BERTopic()
    topics, probs = topic_model.fit_transform(docs)
    ```

    If you want to use your own embeddings, use it as follows:

    ```python
    from bertopic import BERTopic
    from sklearn.datasets import fetch_20newsgroups
    from sentence_transformers import SentenceTransformer

    # Create embeddings
    docs = fetch_20newsgroups(subset='all')['data']
    sentence_model = SentenceTransformer("google/embeddinggemma-2", default_prompt_name="Clustering")
    sentence_model.max_seq_length = 1024
    embeddings = sentence_model.encode(docs, show_progress_bar=True)

    # Create topic model
    topic_model = BERTopic()
    topics, probs = topic_model.fit_transform(docs, embeddings)
    ```
    """
    corpus = Corpus.from_inputs(
        documents=documents,
        images=images,
        audio=audio,
        video=video,
        code=code,
        embeddings=embeddings,
        y=y,
    )

    # 1. Extract embeddings
    if corpus.embeddings is None or (corpus.embeddings is not None and self.embedding_model is not None):
        self.embedding_model = select_backend(
            embedding_model=self.embedding_model, language=self.language, verbose=self.verbose
        )

    if corpus.embeddings is None:
        corpus.embeddings = self._embed_corpus(corpus, verbose=self.verbose)

    # Guided Topic Modeling
    corpus = guided.guided_tm(self, corpus)

    # 2) Reduce dimensionality and fit UMAP model
    corpus = self._reduce_dimensionality(corpus)

    # Zero-shot Topic Modeling
    corpus, zeroshot_docs = zeroshot.zeroshot_tm(self, corpus)

    # 3) Cluster reduced embeddings
    corpus = self._cluster_embeddings(corpus)

    # Combine zero-shot topics with clustered topics
    corpus = zeroshot.combine_zeroshot_topics(self, corpus, zeroshot_docs)

    # Let converters describe their own modality in text, since c-TF-IDF needs words
    corpus = self._convert_media_to_text(corpus)

    # 4/5/6) Process text documents
    self._extract_representations(corpus, verbose=self.verbose, fine_tune=not self.nr_topics)
    corpus = self._reduce_topics(corpus)
    self._save_representative_docs(corpus)

    # With zero-shot topics, probability will come from cosine similarity, and the HDBSCAN model will be removed
    corpus = zeroshot.update_probabilities(topic_model=self, corpus=corpus, zeroshot_docs=zeroshot_docs)

    # Assign to public attributes
    self._data = corpus

    return self._topics.predictions, self._topics.probabilities

generate_topic_labels(nr_words=3, topic_prefix=True, word_length=None, separator='_', aspect=None)

Get labels for each topic in a user-defined format.

Parameters:

Name	Type	Description	Default
nr_words	int	Top n words per topic to use	3
topic_prefix	bool	Whether to use the topic ID as a prefix. If set to True, the topic ID will be separated using the separator	True
word_length	int | None	The maximum length of each word in the topic label. Some words might be relatively long and setting this value helps to make sure that all labels have relatively similar lengths.	None
separator	str	The string with which the words and topic prefix will be separated. Underscores are the default but a nice alternative is ", ".	'_'
aspect	str | None	The aspect from which to generate topic labels	None

Returns:

Name	Type	Description
topic_labels	list[str]	A list of topic labels sorted from the lowest topic ID to the highest. If the topic model was trained using HDBSCAN, the lowest topic ID is -1, otherwise it is 0.

Examples: To create our custom topic labels, usage is rather straightforward:

topic_labels = topic_model.generate_topic_labels(nr_words=2, separator=", ")

Source code in bertopic\_bertopic.py

def generate_topic_labels(
    self,
    nr_words: int = 3,
    topic_prefix: bool = True,
    word_length: int | None = None,
    separator: str = "_",
    aspect: str | None = None,
) -> list[str]:
    """Get labels for each topic in a user-defined format.

    Arguments:
        nr_words: Top `n` words per topic to use
        topic_prefix: Whether to use the topic ID as a prefix.
                      If set to True, the topic ID will be separated
                      using the `separator`
        word_length: The maximum length of each word in the topic label.
                     Some words might be relatively long and setting this
                     value helps to make sure that all labels have relatively
                     similar lengths.
        separator: The string with which the words and topic prefix will be
                   separated. Underscores are the default but a nice alternative
                   is `", "`.
        aspect: The aspect from which to generate topic labels

    Returns:
        topic_labels: A list of topic labels sorted from the lowest topic ID to the highest.
                      If the topic model was trained using HDBSCAN, the lowest topic ID is -1,
                      otherwise it is 0.

    Examples:
    To create our custom topic labels, usage is rather straightforward:

    ```python
    topic_labels = topic_model.generate_topic_labels(nr_words=2, separator=", ")
    ```
    """
    check_is_fitted(self)
    topic_labels = []
    for topic in self._topics:
        representation = topic.representations.get(aspect or "Main")

        # For non-keyword representations (Label, StructuredJSON), use their
        # label directly since word-level operations don't apply.
        if representation and not isinstance(representation, Keywords):
            label = representation.label
            if topic_prefix:
                topic_label = f"{topic.id}{separator}{label}"
            else:
                topic_label = label
        else:
            words = representation.words if representation else []

            if word_length:
                words = [word[:word_length] for word in words][:nr_words]
            else:
                words = list(words)[:nr_words]

            if topic_prefix:
                topic_label = f"{topic.id}{separator}" + separator.join(words)
            else:
                topic_label = separator.join(words)

        topic_labels.append(topic_label)

    return topic_labels

get_document_info(docs, df=None, metadata=None)

Get information about the documents on which the topic was trained including the documents themselves, their respective topics, the name of each topic, the top n words of each topic, whether it is a representative document, and probability of the clustering if the cluster model supports it.

Parameters:

Name	Type	Description	Default
docs	list[str]	The documents on which the topic model was trained.	required
df	IntoDataFrame | None	A dataframe with extra columns to include in the output.	None
metadata	dict[str, Any] | None	A dictionary with meta data for each document in the form of column name (key) and the respective values (value).	None

Returns:

Name	Type	Description
document_info	IntoDataFrame	A dataframe with several statistics regarding the documents on which the topic model was trained.

Examples:

document_info = topic_model.get_document_info(docs)

Source code in bertopic\_bertopic.py

def get_document_info(
    self,
    docs: list[str],
    df: IntoDataFrame | None = None,
    metadata: dict[str, Any] | None = None,
) -> IntoDataFrame:
    """Get information about the documents on which the topic was trained
    including the documents themselves, their respective topics, the name
    of each topic, the top n words of each topic, whether it is a
    representative document, and probability of the clustering if the cluster
    model supports it.

    Arguments:
        docs: The documents on which the topic model was trained.
        df: A dataframe with extra columns to include in the output.
        metadata: A dictionary with meta data for each document in the form
                  of column name (key) and the respective values (value).

    Returns:
        document_info: A dataframe with several statistics regarding
                       the documents on which the topic model was trained.

    Examples:
    ```python
    document_info = topic_model.get_document_info(docs)
    ```
    """
    check_documents_type(docs)
    check_is_fitted(self)

    predictions = self.topics_
    topics_lookup = self._topics.topics
    representative_docs = {doc for topic in self._topics for doc in topic.representative_documents or []}

    # Each document gets its topic's row of `get_topic_info`, as in 0.17
    topic_info = nw.from_native(self._topics.to_dataframe(topics=predictions), eager_only=True)
    data: dict[str, list] = {
        "Top_n_words": [
            " - ".join(topics_lookup[tid].representations["Main"].words) for tid in predictions
        ],
    }

    # Probabilities
    if self.probabilities_ is not None:
        if len(self.probabilities_.shape) == 1:
            data["Probability"] = self.probabilities_.tolist()
        else:
            # Column `j` holds topic `topic_ids()[j]`, so the assigned topic's
            # probability is read directly rather than derived
            topic_ids = self._topics.topic_ids()
            data["Probability"] = [
                float(probabilities[topic_ids.index(topic_id)])
                for topic_id, probabilities in zip(predictions, self.probabilities_)
            ]

    data["Representative_document"] = [doc in representative_docs for doc in docs]

    # Custom metadata
    if metadata is not None:
        data.update(metadata)

    # The document comes first, then its topic's information and the columns above, which replace any of
    # the same name
    documents = nw.from_dict({"Document": docs}, backend=get_output())
    columns = nw.from_dict(data, backend=get_output())
    topic_info = topic_info.drop(["Count", *data], strict=False)
    result = nw.concat([documents, topic_info, columns], how="horizontal")

    # The caller's own columns come first, in whatever library they used, unless ours replace them
    if df is not None:
        df = nw.from_native(df, eager_only=True)
        result = nw.concat([df.drop(result.columns, strict=False), result], how="horizontal")
    return result.to_native()

get_params(deep=False)

Get parameters for this estimator.

Adapted from

https://github.com/scikit-learn/scikit-learn/blob/b3ea3ed6a/sklearn/base.py#L178

Parameters:

Name	Type	Description	Default
deep	bool	bool, default=True If True, will return the parameters for this estimator and contained subobjects that are estimators.	False

Returns:

Name	Type	Description
out	dict[str, Any]	Parameter names mapped to their values.

Source code in bertopic\_bertopic.py

def get_params(self, deep: bool = False) -> dict[str, Any]:
    """Get parameters for this estimator.

    Adapted from:
        https://github.com/scikit-learn/scikit-learn/blob/b3ea3ed6a/sklearn/base.py#L178

    Arguments:
        deep: bool, default=True
              If True, will return the parameters for this estimator and
              contained subobjects that are estimators.

    Returns:
        out: Parameter names mapped to their values.
    """
    out = dict()
    for key in self._get_param_names():
        value = getattr(self, key)
        if deep and hasattr(value, "get_params"):
            deep_items = value.get_params().items()
            out.update((key + "__" + k, val) for k, val in deep_items)
        out[key] = value
    return out

get_representation(topic, aspect='Main')

Return a topic's representation with its structure intact.

get_topic flattens every representation to words and scores, which loses the shape of anything richer than keywords, such as the dictionary an LLM returns. This returns the representation itself.

Parameters:

Name	Type	Description	Default
topic	int	A specific topic for which you want its representation	required
aspect	str	Which representation to return, defaulting to the main one	'Main'

Returns:

Type	Description
TopicRepresentation	The TopicRepresentation for that topic and aspect

Examples:

representation = topic_model.get_representation(12)
representation.words

Source code in bertopic\_bertopic.py

def get_representation(self, topic: int, aspect: str = "Main") -> TopicRepresentation:
    """Return a topic's representation with its structure intact.

    `get_topic` flattens every representation to words and scores, which loses the shape
    of anything richer than keywords, such as the dictionary an LLM returns. This returns
    the representation itself.

    Arguments:
        topic: A specific topic for which you want its representation
        aspect: Which representation to return, defaulting to the main one

    Returns:
        The `TopicRepresentation` for that topic and aspect

    Examples:
    ```python
    representation = topic_model.get_representation(12)
    representation.words
    ```
    """
    check_is_fitted(self)
    return self._topics[topic].representations[aspect]

get_representative_docs(topic=None)

Extract the best representing documents per topic.

Parameters:

Name	Type	Description	Default
topic	int | None	A specific topic for which you want the representative documents	None

Returns:

Type	Description
list[str] | dict[int, list[str]] | None	Representative documents of the chosen topic, or a dict
list[str] | dict[int, list[str]] | None	of all topics to their representative documents if no
list[str] | dict[int, list[str]] | None	topic is specified.

Examples: To extract the representative docs of all topics:

representative_docs = topic_model.get_representative_docs()

To get the representative docs of a single topic:

representative_docs = topic_model.get_representative_docs(12)

Source code in bertopic\_bertopic.py

def get_representative_docs(self, topic: int | None = None) -> list[str] | dict[int, list[str]] | None:
    """Extract the best representing documents per topic.

    Arguments:
        topic: A specific topic for which you want
               the representative documents

    Returns:
        Representative documents of the chosen topic, or a dict
        of all topics to their representative documents if no
        topic is specified.

    Examples:
    To extract the representative docs of all topics:

    ```python
    representative_docs = topic_model.get_representative_docs()
    ```

    To get the representative docs of a single topic:

    ```python
    representative_docs = topic_model.get_representative_docs(12)
    ```
    """
    check_is_fitted(self)
    if isinstance(topic, int):
        selected_topic = self._topics.get(topic)
        if selected_topic and selected_topic.representative_documents:
            return selected_topic.representative_documents
        return None
    else:
        return {t.id: t.representative_documents for t in self._topics if t.representative_documents}

get_topic(topic, full=False)

Return top n words for a specific topic and their c-TF-IDF scores.

Parameters:

Name	Type	Description	Default
topic	int	A specific topic for which you want its representation	required
full	bool	If True, returns all different forms of topic representations for a topic, including aspects	False

Returns:

Type	Description
dict[str, tuple[str, float]] | bool	The top n words for a specific word and its respective c-TF-IDF scores

Examples:

topic = topic_model.get_topic(12)

Source code in bertopic\_bertopic.py

def get_topic(self, topic: int, full: bool = False) -> dict[str, tuple[str, float]] | bool:
    """Return top n words for a specific topic and their c-TF-IDF scores.

    Arguments:
        topic: A specific topic for which you want its representation
        full: If True, returns all different forms of topic representations
              for a topic, including aspects

    Returns:
        The top n words for a specific word and its respective c-TF-IDF scores

    Examples:
    ```python
    topic = topic_model.get_topic(12)
    ```
    """
    check_is_fitted(self)
    if topic in self.topic_representations_:
        if full:
            representations = {"Main": self.topic_representations_[topic]}
            aspects = {
                aspect: representations[topic] for aspect, representations in self.topic_aspects_.items()
            }
            representations.update(aspects)
            return representations
        else:
            return self.topic_representations_[topic]
    else:
        return False

get_topic_freq(topic=None)

Return the size of topics (descending order).

Parameters:

Name	Type	Description	Default
topic	int | None	A specific topic for which you want the frequency	None

Returns:

Type	Description
IntoDataFrame | int	Either the frequency of a single topic or dataframe with
IntoDataFrame | int	the frequencies of all topics

Examples: To extract the frequency of all topics:

frequency = topic_model.get_topic_freq()

To get the frequency of a single topic:

frequency = topic_model.get_topic_freq(12)

Source code in bertopic\_bertopic.py

def get_topic_freq(self, topic: int | None = None) -> IntoDataFrame | int:
    """Return the size of topics (descending order).

    Arguments:
        topic: A specific topic for which you want the frequency

    Returns:
        Either the frequency of a single topic or dataframe with
        the frequencies of all topics

    Examples:
    To extract the frequency of all topics:

    ```python
    frequency = topic_model.get_topic_freq()
    ```

    To get the frequency of a single topic:

    ```python
    frequency = topic_model.get_topic_freq(12)
    ```
    """
    check_is_fitted(self)
    if isinstance(topic, int):
        return self.topic_sizes_[topic]
    else:
        sizes = self.topic_sizes_
        data = {"Topic": list(sizes.keys()), "Count": list(sizes.values())}
        return nw.from_dict(data, backend=get_output()).sort("Count", descending=True).to_native()

get_topic_info(topic=None)

Get information about each topic including its ID, frequency, and name.

Parameters:

Name	Type	Description	Default
topic	int | None	A specific topic for which you want the frequency	None

Returns:

Name	Type	Description
df	IntoDataFrame	A dataframe containing information about each topic

Examples:

info_df = topic_model.get_topic_info()

Source code in bertopic\_bertopic.py

def get_topic_info(self, topic: int | None = None) -> IntoDataFrame:
    """Get information about each topic including its ID, frequency, and name.

    Arguments:
        topic: A specific topic for which you want the frequency

    Returns:
        df: A dataframe containing information about each topic

    Examples:
    ```python
    info_df = topic_model.get_topic_info()
    ```
    """
    check_is_fitted(self)
    return self._topics.to_dataframe(topics=topic)

get_topic_tree(hier_topics=None, max_distance=None, tight_layout=False)

Extract the topic tree such that it can be printed.

Parameters:

Name	Type	Description	Default
hier_topics	IntoDataFrame | None	A dataframe containing the structure of the topic tree. This is the output of topic_model.hierarchical_topics(). If None, the hierarchy that it created last is used.	None
max_distance	float | None	The maximum distance between two topics. Topics merged at distances greater than this are shown as 'O'.	None
tight_layout	bool	Whether to use a tight layout (narrow width) for easier readability if you have hundreds of topics.	False

Returns:

Type	Description
str	A tree that has the following structure when printed: . . └─health_medical_disease_patients_hiv ├─patients_medical_disease_candida_health │ ├─■──candida_yeast_infection_gonorrhea_infections ── Topic: 48 │ └─patients_disease_cancer_medical_doctor │ ├─■──hiv_medical_cancer_patients_doctor ── Topic: 34 │ └─■──pain_drug_patients_disease_diet ── Topic: 26 └─■──health_newsgroup_tobacco_vote_votes ── Topic: 9
str	The blocks (■) indicate that the topic is one you can directly access
str	from topic_model.get_topic. In other words, they are the original un-grouped topics.

Examples:

# Train model
from bertopic import BERTopic
topic_model = BERTopic()
topics, probs = topic_model.fit_transform(docs)
hierarchical_topics = topic_model.hierarchical_topics(docs)

# Print topic tree
tree = topic_model.get_topic_tree(hierarchical_topics)
print(tree)

Source code in bertopic\_bertopic.py

def get_topic_tree(
    self,
    hier_topics: IntoDataFrame | None = None,
    max_distance: float | None = None,
    tight_layout: bool = False,
) -> str:
    """Extract the topic tree such that it can be printed.

    Arguments:
        hier_topics: A dataframe containing the structure of the topic tree.
                     This is the output of `topic_model.hierarchical_topics()`. If None,
                     the hierarchy that it created last is used.
        max_distance: The maximum distance between two topics. Topics merged
                      at distances greater than this are shown as 'O'.
        tight_layout: Whether to use a tight layout (narrow width) for
                      easier readability if you have hundreds of topics.

    Returns:
        A tree that has the following structure when printed:
            .
            .
            └─health_medical_disease_patients_hiv
                ├─patients_medical_disease_candida_health
                │    ├─■──candida_yeast_infection_gonorrhea_infections ── Topic: 48
                │    └─patients_disease_cancer_medical_doctor
                │         ├─■──hiv_medical_cancer_patients_doctor ── Topic: 34
                │         └─■──pain_drug_patients_disease_diet ── Topic: 26
                └─■──health_newsgroup_tobacco_vote_votes ── Topic: 9

        The blocks (■) indicate that the topic is one you can directly access
        from `topic_model.get_topic`. In other words, they are the original un-grouped topics.

    Examples:
    ```python
    # Train model
    from bertopic import BERTopic
    topic_model = BERTopic()
    topics, probs = topic_model.fit_transform(docs)
    hierarchical_topics = topic_model.hierarchical_topics(docs)

    # Print topic tree
    tree = topic_model.get_topic_tree(hierarchical_topics)
    print(tree)
    ```
    """
    if hier_topics is None:
        if self._hierarchy is None:
            raise ValueError(
                "You need to first create a topic hierarchy through "
                "`topic_model.hierarchical_topics()` before you can "
                "extract the topic tree."
            )
        hier_topics = self._hierarchy.to_dataframe()

    # Map each merged topic to its children, and each child to its name and the distance it was merged at
    tree, names, distances = {}, {}, {}
    for row in nw.from_native(hier_topics, eager_only=True).rows(named=True):
        tree[row["Parent_ID"]] = [row["Child_Left_ID"], row["Child_Right_ID"]]
        for side in ["Left", "Right"]:
            names[row[f"Child_{side}_ID"]] = row[f"Child_{side}_Name"][:100]
            distances[row[f"Child_{side}_ID"]] = row["Distance"]
    root = next(topic for topic in tree if topic not in distances)
    max_distance = max(distances.values()) + 1 if max_distance is None else max_distance
    width = 1 if tight_layout else 4

    def _tree(to_print, topic, indent=""):
        """Based on: https://stackoverflow.com/a/51920869/10532563."""
        # An original topic is shown with its ID, unless it was merged beyond `max_distance`
        if topic != root:
            if topic in tree:
                to_print += names[topic] + "\n"
            elif distances[topic] < max_distance:
                to_print += "■──" + names[topic] + f" ── Topic: {topic}" + "\n"
            else:
                to_print += "O \n"

        if topic not in tree:
            return to_print

        for child in tree[topic][:-1]:
            to_print += indent + "├" + "─"
            to_print = _tree(to_print, child, indent + "│" + " " * width)

        child = tree[topic][-1]
        to_print += indent + "└" + "─"
        return _tree(to_print, child, indent + " " * (width + 1))

    return _tree("." + "\n", root)

get_topics(full=False)

Return topics with top n words and their c-TF-IDF score.

Parameters:

Name	Type	Description	Default
full	bool	If True, returns all different forms of topic representations for each topic, including aspects	False

Returns:

Type	Description
dict[str, tuple[str, float]]	self.topic_representations_: The top n words per topic and the corresponding c-TF-IDF score

Examples:

all_topics = topic_model.get_topics()

Source code in bertopic\_bertopic.py

def get_topics(self, full: bool = False) -> dict[str, tuple[str, float]]:
    """Return topics with top n words and their c-TF-IDF score.

    Arguments:
        full: If True, returns all different forms of topic representations
              for each topic, including aspects

    Returns:
        self.topic_representations_: The top n words per topic and the corresponding c-TF-IDF score

    Examples:
    ```python
    all_topics = topic_model.get_topics()
    ```
    """
    check_is_fitted(self)

    if full:
        topic_representations = {"Main": self.topic_representations_}
        topic_representations.update(self.topic_aspects_)
        return topic_representations
    else:
        return self.topic_representations_

load(path, embedding_model=None) classmethod

Loads the model from the specified path or directory.

Parameters:

Name	Type	Description	Default
path	str	Either load a BERTopic model from a file (.pickle) or a folder containing .safetensors or .bin files.	required
embedding_model		Additionally load in an embedding model if it was not saved in the BERTopic model file or directory.	None

Examples:

BERTopic.load("model_dir")

or if you did not save the embedding model:

BERTopic.load("model_dir", embedding_model="google/embeddinggemma-2")

Source code in bertopic\_bertopic.py

@classmethod
def load(cls, path: str, embedding_model=None):
    """Loads the model from the specified path or directory.

    Arguments:
        path: Either load a BERTopic model from a file (`.pickle`) or a folder containing
              `.safetensors` or `.bin` files.
        embedding_model: Additionally load in an embedding model if it was not saved
                         in the BERTopic model file or directory.

    Examples:
    ```python
    BERTopic.load("model_dir")
    ```

    or if you did not save the embedding model:

    ```python
    BERTopic.load("model_dir", embedding_model="google/embeddinggemma-2")
    ```
    """
    file_or_dir = Path(path)

    # Load from Pickle, which only works with the versions that saved it
    if file_or_dir.is_file():
        with open(file_or_dir, "rb") as file:
            try:
                topic_model = joblib.load(file)
            except (AttributeError, ModuleNotFoundError) as error:
                raise ValueError(
                    "This model could not be unpickled. A pickle needs BERTopic and the packages it "
                    "was saved with, at the same versions, so a model that BERTopic 0.17.4 or earlier "
                    "pickled does not load in 1.0. Load it with those versions, save it again with "
                    'serialization="safetensors", and load that folder instead. See '
                    "https://maartengr.github.io/BERTopic/migration.html#saved-models"
                ) from error
        if embedding_model:
            topic_model.embedding_model = select_backend(embedding_model, verbose=topic_model.verbose)
        return topic_model

    # Load from directory or HF
    if file_or_dir.is_dir():
        topics, params, tensors, ctfidf_tensors, ctfidf_config, summaries = save_utils.load_local_files(
            file_or_dir
        )
    elif "/" in str(path):
        topics, params, tensors, ctfidf_tensors, ctfidf_config, summaries = save_utils.load_files_from_hf(
            path
        )
    else:
        raise ValueError("Make sure to either pass a valid directory or HF model.")
    topic_model = _create_model_from_files(
        topics,
        params,
        tensors,
        ctfidf_tensors,
        ctfidf_config,
        summaries,
        load_embedding_model=(embedding_model is None),
    )

    # Replace embedding model if one is specifically chosen
    if embedding_model is not None:
        topic_model.embedding_model = select_backend(embedding_model, verbose=topic_model.verbose)

    return topic_model

merge_models(models, min_similarity=0.7, embedding_model=None) classmethod

Merge multiple pre-trained BERTopic models into a single model.

Topics are deduplicated based on embedding similarity. Topics with cosine similarity >= min_similarity are considered duplicates and merged. Dissimilar topics are added as new topics.

The resulting model can be used for inference (transform) but not for fitting new data, as it lacks UMAP and HDBSCAN models.

Parameters:

Name	Type	Description	Default
models	list[BERTopic]	A list of fitted BERTopic models to merge.	required
min_similarity	float	Minimum cosine similarity to deduplicate topics.	0.7
embedding_model		Optional embedding model to use for the merged model.	None

Returns:

Type	Description
BERTopic	A new BERTopic model containing topics from all input models.

Examples:

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups

docs = fetch_20newsgroups(subset='all',  remove=('headers', 'footers', 'quotes'))['data']

# Create three separate models
topic_model_1 = BERTopic(min_topic_size=5).fit(docs[:4000])
topic_model_2 = BERTopic(min_topic_size=5).fit(docs[4000:8000])
topic_model_3 = BERTopic(min_topic_size=5).fit(docs[8000:])

# Combine all models into one
merged_model = BERTopic.merge_models([topic_model_1, topic_model_2, topic_model_3])

Source code in bertopic\_bertopic.py

@classmethod
def merge_models(
    cls, models: list["BERTopic"], min_similarity: float = 0.7, embedding_model=None
) -> "BERTopic":
    """Merge multiple pre-trained BERTopic models into a single model.

    Topics are deduplicated based on embedding similarity. Topics with
    cosine similarity >= min_similarity are considered duplicates and
    merged. Dissimilar topics are added as new topics.

    The resulting model can be used for inference (transform) but not
    for fitting new data, as it lacks UMAP and HDBSCAN models.

    Arguments:
        models: A list of fitted BERTopic models to merge.
        min_similarity: Minimum cosine similarity to deduplicate topics.
        embedding_model: Optional embedding model to use for the merged model.

    Returns:
        A new BERTopic model containing topics from all input models.

    Examples:
    ```python
    from bertopic import BERTopic
    from sklearn.datasets import fetch_20newsgroups

    docs = fetch_20newsgroups(subset='all',  remove=('headers', 'footers', 'quotes'))['data']

    # Create three separate models
    topic_model_1 = BERTopic(min_topic_size=5).fit(docs[:4000])
    topic_model_2 = BERTopic(min_topic_size=5).fit(docs[4000:8000])
    topic_model_3 = BERTopic(min_topic_size=5).fit(docs[8000:])

    # Combine all models into one
    merged_model = BERTopic.merge_models([topic_model_1, topic_model_2, topic_model_3])
    ```
    """
    if not models:
        raise ValueError("At least one model is required")

    # Copy and merge topics
    merged_topics = models[0]._topics.copy()
    for model in models[1:]:
        merged_topics.merge_similar(model._topics, min_similarity)

    # Create model with minimal sub-models (no UMAP/HDBSCAN)
    merged_model = BERTopic(
        embedding_model=BaseEmbedder(),
        umap_model=BaseDimensionalityReduction(),
        hdbscan_model=BaseCluster(),
    )
    merged_model._topics = merged_topics
    merged_model._hierarchy = None

    # Each model counted words over its own vocabulary, so their c-TF-IDF rows do not fit together
    for topic in merged_model._topics:
        topic.c_tf_idf = csr_matrix([])

    # Set embedding model
    merged_model.embedding_model = models[0].embedding_model
    if embedding_model is not None:
        verbose = any(m.verbose for m in models)
        merged_model.embedding_model = select_backend(embedding_model, verbose=verbose)

    return merged_model

merge_topics(docs, topics_to_merge, images=None, *, audio=None, video=None, code=None)

Merge multiple topics into a single topic.

Parameters:

Name	Type	Description	Default
docs	list[str]	The documents you used when calling either fit or fit_transform	required
topics_to_merge	list[Iterable[int] | int]	Either a list of topics or a list of list of topics to merge. For example: [1, 2, 3] will merge topics 1, 2 and 3 [[1, 2], [3, 4]] will merge topics 1 and 2, and separately merge topics 3 and 4.	required
images	list | None	A list of paths to the images used when calling either fit or fit_transform.	None
audio	list | None	A list of paths to the audio used when calling either fit or fit_transform.	None
video	list | None	A list of paths to the video used when calling either fit or fit_transform.	None
code	list[str] | None	The source code used when calling either fit or fit_transform.	None

Examples: If you want to merge topics 1, 2, and 3:

topics_to_merge = [1, 2, 3]
topic_model.merge_topics(docs, topics_to_merge)

or if you want to merge topics 1 and 2, and separately merge topics 3 and 4:

topics_to_merge = [[1, 2],
                    [3, 4]]
topic_model.merge_topics(docs, topics_to_merge)

Source code in bertopic\_bertopic.py

def merge_topics(
    self,
    docs: list[str],
    topics_to_merge: list[Iterable[int] | int],
    images: list | None = None,
    *,
    audio: list | None = None,
    video: list | None = None,
    code: list[str] | None = None,
) -> None:
    """Merge multiple topics into a single topic.

    Arguments:
        docs: The documents you used when calling either `fit` or `fit_transform`
        topics_to_merge: Either a list of topics or a list of list of topics
                         to merge. For example:
                            [1, 2, 3] will merge topics 1, 2 and 3
                            [[1, 2], [3, 4]] will merge topics 1 and 2, and
                            separately merge topics 3 and 4.
        images: A list of paths to the images used when calling either
                `fit` or `fit_transform`.
        audio: A list of paths to the audio used when calling either
               `fit` or `fit_transform`.
        video: A list of paths to the video used when calling either
               `fit` or `fit_transform`.
        code: The source code used when calling either `fit` or `fit_transform`.

    Examples:
    If you want to merge topics 1, 2, and 3:

    ```python
    topics_to_merge = [1, 2, 3]
    topic_model.merge_topics(docs, topics_to_merge)
    ```

    or if you want to merge topics 1 and 2, and separately
    merge topics 3 and 4:

    ```python
    topics_to_merge = [[1, 2],
                        [3, 4]]
    topic_model.merge_topics(docs, topics_to_merge)
    ```
    """
    check_is_fitted(self)
    check_documents_type(docs)

    # Build mapping: all topics map to themselves, except merged topics map to target
    mapping = {topic: topic for topic in set(self.topics_)}
    if isinstance(topics_to_merge[0], int):
        for topic in sorted(topics_to_merge):
            mapping[topic] = topics_to_merge[0]
    elif isinstance(topics_to_merge[0], Iterable):
        for topic_group in sorted(topics_to_merge):
            for topic in topic_group:
                mapping[topic] = topic_group[0]
    else:
        raise ValueError(
            "Make sure that `topics_to_merge` is either a list of topics or a list of list of topics."
        )

    # Build Corpus BEFORE merge with current topic assignments and embeddings.
    # This ensures embeddings correspond to original topics, so after merge
    # the mean embedding correctly produces a weighted average.
    topic_embeddings = {topic.id: topic.embedding for topic in self._topics}
    doc_embeddings = np.array([topic_embeddings[topic_id] for topic_id in self.topics_])
    corpus = Corpus.from_inputs(
        documents=docs,
        images=images,
        audio=audio,
        video=video,
        code=code,
        topics=np.array(self.topics_),
        embeddings=doc_embeddings,
    )

    # Merge topics (updates topic IDs and cumulative mapping)
    self._topics.merge(mapping)

    # Map corpus topics to match merged state and then sort by frequency
    self._topics.sort_by_frequency()
    corpus.topics, corpus.probabilities = self._topics.predictions, self._topics.probabilities

    # Recalculate representations from merged documents
    self._extract_representations(corpus)
    self._save_representative_docs(corpus)

partial_fit(documents, embeddings=None, y=None)

Fit BERTopic on a subset of the data and perform online learning with batch-like data.

Online topic modeling in BERTopic is performed by using dimensionality reduction and cluster algorithms that support a partial_fit method in order to incrementally train the topic model.

Likewise, the bertopic.vectorizers.OnlineCountVectorizer is used to dynamically update its vocabulary when presented with new data. It has several parameters for modeling decay and updating the representations.

In other words, although the main algorithm stays the same, the training procedure now works as follows:

For each subset of the data:

1. Generate embeddings with a pre-trained language model
2. Incrementally update the dimensionality reduction algorithm with partial_fit
3. Incrementally update the cluster algorithm with partial_fit
4. Incrementally update the OnlineCountVectorizer and apply some form of decay

Note that it is advised to use partial_fit with batches and not single documents for the best performance.

After fitting, model.topics_ contains topic IDs for all documents seen across all batches (accumulated), and model._topics contains the Topics object with cumulative document counts per topic.

Parameters:

Name	Type	Description	Default
documents	List[str]	A list of documents to fit on	required
embeddings	ndarray	Pre-trained document embeddings. These can be used instead of the sentence-transformer model	None
y	Union[List[int], ndarray]	The target class for (semi)-supervised modeling. Use -1 if no class for a specific instance is specified.	None

Examples:

from sklearn.datasets import fetch_20newsgroups
from sklearn.cluster import MiniBatchKMeans
from sklearn.decomposition import IncrementalPCA
from bertopic.vectorizers import OnlineCountVectorizer
from bertopic import BERTopic

# Prepare documents
docs = fetch_20newsgroups(subset=subset,  remove=('headers', 'footers', 'quotes'))["data"]

# Prepare sub-models that support online learning
umap_model = IncrementalPCA(n_components=5)
cluster_model = MiniBatchKMeans(n_clusters=50, random_state=0)
vectorizer_model = OnlineCountVectorizer(stop_words="english", decay=.01)

topic_model = BERTopic(umap_model=umap_model,
                       hdbscan_model=cluster_model,
                       vectorizer_model=vectorizer_model)

# Incrementally fit the topic model by training on 1000 documents at a time
for index in range(0, len(docs), 1000):
    topic_model.partial_fit(docs[index: index+1000])

Source code in bertopic\_bertopic.py

def partial_fit(
    self,
    documents: List[str],
    embeddings: np.ndarray = None,
    y: Union[List[int], np.ndarray] = None,
):
    """Fit BERTopic on a subset of the data and perform online learning
    with batch-like data.

    Online topic modeling in BERTopic is performed by using dimensionality
    reduction and cluster algorithms that support a `partial_fit` method
    in order to incrementally train the topic model.

    Likewise, the `bertopic.vectorizers.OnlineCountVectorizer` is used
    to dynamically update its vocabulary when presented with new data.
    It has several parameters for modeling decay and updating the
    representations.

    In other words, although the main algorithm stays the same, the training
    procedure now works as follows:

    For each subset of the data:

    1. Generate embeddings with a pre-trained language model
    2. Incrementally update the dimensionality reduction algorithm with `partial_fit`
    3. Incrementally update the cluster algorithm with `partial_fit`
    4. Incrementally update the OnlineCountVectorizer and apply some form of decay

    Note that it is advised to use `partial_fit` with batches and
    not single documents for the best performance.

    After fitting, `model.topics_` contains topic IDs for all documents seen
    across all batches (accumulated), and `model._topics` contains the Topics
    object with cumulative document counts per topic.

    Arguments:
        documents: A list of documents to fit on
        embeddings: Pre-trained document embeddings. These can be used
                    instead of the sentence-transformer model
        y: The target class for (semi)-supervised modeling. Use -1 if no class for a
           specific instance is specified.

    Examples:
    ```python
    from sklearn.datasets import fetch_20newsgroups
    from sklearn.cluster import MiniBatchKMeans
    from sklearn.decomposition import IncrementalPCA
    from bertopic.vectorizers import OnlineCountVectorizer
    from bertopic import BERTopic

    # Prepare documents
    docs = fetch_20newsgroups(subset=subset,  remove=('headers', 'footers', 'quotes'))["data"]

    # Prepare sub-models that support online learning
    umap_model = IncrementalPCA(n_components=5)
    cluster_model = MiniBatchKMeans(n_clusters=50, random_state=0)
    vectorizer_model = OnlineCountVectorizer(stop_words="english", decay=.01)

    topic_model = BERTopic(umap_model=umap_model,
                           hdbscan_model=cluster_model,
                           vectorizer_model=vectorizer_model)

    # Incrementally fit the topic model by training on 1000 documents at a time
    for index in range(0, len(docs), 1000):
        topic_model.partial_fit(docs[index: index+1000])
    ```
    """
    if not hasattr(self.hdbscan_model, "partial_fit"):
        raise ValueError(
            "In order to use `.partial_fit`, the cluster model should have a `.partial_fit` function."
        )

    # Embed documents
    corpus = Corpus(documents=documents, embeddings=embeddings, y=y)
    is_first_fit = self._topics is None or len(self._topics) == 0

    if is_first_fit and (corpus.embeddings is None or self.embedding_model is not None):
        self.embedding_model = select_backend(
            self.embedding_model, language=self.language, verbose=self.verbose
        )

    if corpus.embeddings is None:
        corpus.embeddings = self._embed_corpus(corpus, verbose=self.verbose)

    # Guided Topic Modeling
    if self.seed_topic_list is not None and self.embedding_model is not None:
        corpus = guided.guided_tm(self, corpus)

    # Reduce dimensionality and cluster
    corpus = self._reduce_dimensionality(corpus, partial_fit=True)
    corpus = self._cluster_embeddings(corpus, partial_fit=True)

    # Use cluster labels directly as topic IDs
    if is_first_fit:
        self._topics = Topics().initialize(corpus.topics)

    # Add new topics and accumulate predictions/counts
    else:
        new_topic_ids = {int(topic) for topic in corpus.topics} - set(self._topics.topic_ids())

        for topic_id in new_topic_ids:
            self._topics.topics[topic_id] = Topic(id=topic_id, nr_documents=0)

        self._topics.predictions.extend(int(topic) for topic in corpus.topics)

        if corpus.probabilities is not None and self._topics.probabilities is not None:
            self._topics.probabilities = np.concatenate(
                [self._topics.probabilities, corpus.probabilities]
            )

        for topic_id in set(corpus.topics):
            count = int(np.sum(corpus.topics == topic_id))
            self._topics[topic_id].nr_documents += count

    # Update topic representations. Every topic keeps a row, in topic ID order, including topics
    # missing from this batch
    grouped = corpus.group_documents_by_topic()
    documents_per_topic = {topic_id: grouped.get(topic_id, " ") for topic_id in self._topics.topic_ids()}

    c_tf_idf, words = self._c_tf_idf(documents_per_topic, partial_fit=True)
    self._topics.set_data(c_tf_idf=c_tf_idf)

    topic_representations = self._extract_words_per_topic(
        words=words,
        corpus=Corpus(documents=list(documents_per_topic.values()), topics=list(documents_per_topic)),
        c_tf_idf=c_tf_idf,
        fine_tune=False,
        calculate_aspects=False,
    )
    self._topics.set_data(representations={"Main": topic_representations})
    self._create_topic_vectors(corpus)

    # A hierarchy made earlier describes topics that may no longer exist
    self._hierarchy = None

    return self

push_to_hf_hub(repo_id, commit_message='Add BERTopic model', token=None, revision=None, private=False, create_pr=False, model_card=True, serialization='safetensors', save_embedding_model=True, save_ctfidf=False)

Push your BERTopic model to a HuggingFace Hub.

Whenever you want to upload files to the Hub, you need to log in to your HuggingFace account:

• Log in to your HuggingFace account with the following command:

  huggingface-cli login
  
  # or using an environment variable
  huggingface-cli login --token $HUGGINGFACE_TOKEN
  

• Alternatively, you can programmatically login using login() in a notebook or a script:

  from huggingface_hub import login
  login()
  

• Or you can give a token with the token variable

Parameters:

Name	Type	Description	Default
repo_id	str	The name of your HuggingFace repository	required
commit_message	str	A commit message	'Add BERTopic model'
token	str | None	Token to add if not already logged in	None
revision	str | None	Repository revision	None
private	bool	Whether to create a private repository	False
create_pr	bool	Whether to upload the model as a Pull Request	False
model_card	bool	Whether to automatically create a modelcard	True
serialization	str	The type of serialization. Either safetensors or pytorch	'safetensors'
save_embedding_model	Union[str, bool]	A pointer towards a HuggingFace model to be loaded in with SentenceTransformers. E.g., google/embeddinggemma-2	True
save_ctfidf	bool	Whether to save c-TF-IDF information	False

Examples:

topic_model.push_to_hf_hub(
    repo_id="ArXiv",
    save_ctfidf=True,
    save_embedding_model="google/embeddinggemma-2"
)

Source code in bertopic\_bertopic.py

def push_to_hf_hub(
    self,
    repo_id: str,
    commit_message: str = "Add BERTopic model",
    token: str | None = None,
    revision: str | None = None,
    private: bool = False,
    create_pr: bool = False,
    model_card: bool = True,
    serialization: str = "safetensors",
    save_embedding_model: Union[str, bool] = True,
    save_ctfidf: bool = False,
):
    """Push your BERTopic model to a HuggingFace Hub.

    Whenever you want to upload files to the Hub, you need to log in to your HuggingFace account:

    * Log in to your HuggingFace account with the following command:
        ```bash
        huggingface-cli login

        # or using an environment variable
        huggingface-cli login --token $HUGGINGFACE_TOKEN
        ```
    * Alternatively, you can programmatically login using login() in a notebook or a script:
        ```python
        from huggingface_hub import login
        login()
        ```
    * Or you can give a token with the `token` variable

    Arguments:
        repo_id: The name of your HuggingFace repository
        commit_message: A commit message
        token: Token to add if not already logged in
        revision: Repository revision
        private: Whether to create a private repository
        create_pr: Whether to upload the model as a Pull Request
        model_card: Whether to automatically create a modelcard
        serialization: The type of serialization.
                       Either `safetensors` or `pytorch`
        save_embedding_model: A pointer towards a HuggingFace model to be loaded in with
                              SentenceTransformers. E.g.,
                              `google/embeddinggemma-2`
        save_ctfidf: Whether to save c-TF-IDF information


    Examples:
    ```python
    topic_model.push_to_hf_hub(
        repo_id="ArXiv",
        save_ctfidf=True,
        save_embedding_model="google/embeddinggemma-2"
    )
    ```
    """
    return save_utils.push_to_hf_hub(
        model=self,
        repo_id=repo_id,
        commit_message=commit_message,
        token=token,
        revision=revision,
        private=private,
        create_pr=create_pr,
        model_card=model_card,
        serialization=serialization,
        save_embedding_model=save_embedding_model,
        save_ctfidf=save_ctfidf,
    )

reduce_topics(docs, nr_topics=20, images=None, use_ctfidf=False, *, audio=None, video=None, code=None)

Reduce the number of topics to a fixed number of topics or automatically.

If nr_topics is an integer, then the number of topics is reduced to nr_topics using AgglomerativeClustering on the cosine distance matrix of the topic c-TF-IDF or semantic embeddings.

If nr_topics is "auto", then HDBSCAN is used to automatically reduce the number of topics by running it on the topic embeddings.

The topics, their sizes, and representations are updated.

Parameters:

Name	Type	Description	Default
docs	list[str]	The docs you used when calling either fit or fit_transform	required
nr_topics	int | str	The number of topics you want reduced to	20
images	list | None	A list of paths to the images used when calling either fit or fit_transform	None
audio	list | None	A list of paths to the audio used when calling either fit or fit_transform	None
video	list | None	A list of paths to the video used when calling either fit or fit_transform	None
code	list[str] | None	The source code used when calling either fit or fit_transform	None
use_ctfidf	bool	Whether to calculate distances between topics based on c-TF-IDF embeddings. If False, the embeddings from the embedding model are used.	False

Examples: You can further reduce the topics by passing the documents with their topics and probabilities (if they were calculated):

topic_model.reduce_topics(docs, nr_topics=30)

You can then access the updated topics and probabilities with:

topics = topic_model.topics_
probabilities = topic_model.probabilities_

Source code in bertopic\_bertopic.py

def reduce_topics(
    self,
    docs: list[str],
    nr_topics: int | str = 20,
    images: list | None = None,
    use_ctfidf: bool = False,
    *,
    audio: list | None = None,
    video: list | None = None,
    code: list[str] | None = None,
) -> "BERTopic":
    """Reduce the number of topics to a fixed number of topics
    or automatically.

    If nr_topics is an integer, then the number of topics is reduced
    to nr_topics using `AgglomerativeClustering` on the cosine distance matrix
    of the topic c-TF-IDF or semantic embeddings.

    If nr_topics is `"auto"`, then HDBSCAN is used to automatically
    reduce the number of topics by running it on the topic embeddings.

    The topics, their sizes, and representations are updated.

    Arguments:
        docs: The docs you used when calling either `fit` or `fit_transform`
        nr_topics: The number of topics you want reduced to
        images: A list of paths to the images used when calling either
                `fit` or `fit_transform`
        audio: A list of paths to the audio used when calling either
               `fit` or `fit_transform`
        video: A list of paths to the video used when calling either
               `fit` or `fit_transform`
        code: The source code used when calling either `fit` or `fit_transform`
        use_ctfidf: Whether to calculate distances between topics based on c-TF-IDF embeddings. If False, the
                    embeddings from the embedding model are used.

    Examples:
    You can further reduce the topics by passing the documents with their
    topics and probabilities (if they were calculated):

    ```python
    topic_model.reduce_topics(docs, nr_topics=30)
    ```

    You can then access the updated topics and probabilities with:

    ```python
    topics = topic_model.topics_
    probabilities = topic_model.probabilities_
    ```
    """
    check_is_fitted(self)
    check_documents_type(docs)

    self.nr_topics = nr_topics

    # Build Corpus with current topic assignments
    # Add embedings by duplicating the topic embedding for each document
    topic_embeddings = {topic.id: topic.embedding for topic in self._topics}
    doc_embeddings = np.array([topic_embeddings[topic_id] for topic_id in self.topics_])
    corpus = Corpus.from_inputs(
        documents=docs,
        images=images,
        audio=audio,
        video=video,
        code=code,
        topics=np.array(self.topics_),
        embeddings=doc_embeddings,
    )

    # Reduce number of topics
    corpus = self._reduce_topics(corpus, use_ctfidf)
    self._save_representative_docs(corpus)

    # TODO: Check if zeroshot probabilities need to be updated
    # corpus = zeroshot.update_probabilities(topic_model=self, corpus=corpus, zeroshot_docs=zeroshot_docs)

    return self

save(path, serialization='pickle', save_embedding_model=True, save_ctfidf=False)

Saves the model to the specified path or folder.

When saving the model, make sure to also keep track of the versions of dependencies and Python used. Loading and saving the model should be done using the same dependencies and Python. Moreover, models saved in one version of BERTopic should not be loaded in other versions.

Parameters:

Name	Type	Description	Default
path		If serialization is 'safetensors' or pytorch, this is a directory. If serialization is pickle, then this is a file.	required
serialization	Literal['safetensors', 'pickle', 'pytorch']	If pickle, the entire model will be pickled. If safetensors or pytorch the model will be saved without the embedding, dimensionality reduction, and clustering algorithms. This is a very efficient format and typically advised.	'pickle'
save_embedding_model	Union[bool, str]	If serialization is pickle, then you can choose to skip saving the embedding model. If serialization is safetensors or pytorch, this variable can be used as a string pointing towards a huggingface model.	True
save_ctfidf	bool	Whether to save c-TF-IDF information if serialization is safetensors or pytorch	False

Examples: To save the model in an efficient and safe format (safetensors) with c-TF-IDF information:

topic_model.save("model_dir", serialization="safetensors", save_ctfidf=True)

If you wish to also add a pointer to the embedding model, which will be downloaded from HuggingFace upon loading:

embedding_model = "google/embeddinggemma-2"
topic_model.save("model_dir", serialization="safetensors", save_embedding_model=embedding_model)

or if you want save the full model with pickle:

topic_model.save("my_model")

NOTE: Pickle can run arbitrary code and is generally considered to be less safe than safetensors.

Source code in bertopic\_bertopic.py

def save(
    self,
    path,
    serialization: Literal["safetensors", "pickle", "pytorch"] = "pickle",
    save_embedding_model: Union[bool, str] = True,
    save_ctfidf: bool = False,
):
    """Saves the model to the specified path or folder.

    When saving the model, make sure to also keep track of the versions
    of dependencies and Python used. Loading and saving the model should
    be done using the same dependencies and Python. Moreover, models
    saved in one version of BERTopic should not be loaded in other versions.

    Arguments:
        path: If `serialization` is 'safetensors' or `pytorch`, this is a directory.
              If `serialization` is `pickle`, then this is a file.
        serialization: If `pickle`, the entire model will be pickled. If `safetensors`
                       or `pytorch` the model will be saved without the embedding,
                       dimensionality reduction, and clustering algorithms.
                       This is a very efficient format and typically advised.
        save_embedding_model: If serialization is `pickle`, then you can choose to skip
                              saving the embedding model. If serialization is `safetensors`
                              or `pytorch`, this variable can be used as a string pointing
                              towards a huggingface model.
        save_ctfidf: Whether to save c-TF-IDF information if serialization is `safetensors`
                     or `pytorch`

    Examples:
    To save the model in an efficient and safe format (safetensors) with c-TF-IDF information:

    ```python
    topic_model.save("model_dir", serialization="safetensors", save_ctfidf=True)
    ```

    If you wish to also add a pointer to the embedding model, which will be downloaded from
    HuggingFace upon loading:

    ```python
    embedding_model = "google/embeddinggemma-2"
    topic_model.save("model_dir", serialization="safetensors", save_embedding_model=embedding_model)
    ```

    or if you want save the full model with pickle:

    ```python
    topic_model.save("my_model")
    ```

    NOTE: Pickle can run arbitrary code and is generally considered to be less safe than
    safetensors.
    """
    if serialization == "pickle":
        logger.warning(
            "When you use `pickle` to save/load a BERTopic model, "
            "please make sure that the environments in which you save "
            "and load the model are **exactly** the same. The version of BERTopic, "
            "its dependencies, and python need to remain the same."
        )

        with open(path, "wb") as file:
            # This prevents the vectorizer from being too large in size if `min_df` was
            # set to a value higher than 1
            self.vectorizer_model.stop_words_ = None

            if not save_embedding_model:
                embedding_model = self.embedding_model
                self.embedding_model = None
                joblib.dump(self, file)
                self.embedding_model = embedding_model
            else:
                joblib.dump(self, file)
    elif serialization == "safetensors" or serialization == "pytorch":
        # Directory
        save_directory = Path(path)
        save_directory.mkdir(exist_ok=True, parents=True)

        # Check embedding model
        if (
            save_embedding_model
            and hasattr(self.embedding_model, "_hf_model")
            and not isinstance(save_embedding_model, str)
        ):
            save_embedding_model = self.embedding_model._hf_model
        elif not save_embedding_model:
            logger.warning(
                "You are saving a BERTopic model without explicitly defining an embedding model."
                "If you are using a sentence-transformers model or a HuggingFace model supported"
                "by sentence-transformers, please save the model by using a pointer towards that model."
                "For example, `save_embedding_model='google/embeddinggemma-2'`"
            )

        # Minimal
        save_utils.save_hf(model=self, save_directory=save_directory, serialization=serialization)
        save_utils.save_topics(model=self, path=save_directory / "topics.json")
        save_utils.save_summaries(model=self, directory=save_directory)
        save_utils.save_config(
            model=self,
            path=save_directory / "config.json",
            embedding_model=save_embedding_model,
        )

        # Additional
        if save_ctfidf:
            if self.c_tf_idf_ is None:
                logger.warning(
                    "The c-TF-IDF matrix could not be saved as it was not found. "
                    "This typically occurs when merging BERTopic models with `BERTopic.merge_models`."
                )
            else:
                save_utils.save_ctfidf(
                    model=self,
                    save_directory=save_directory,
                    serialization=serialization,
                )
                save_utils.save_ctfidf_config(model=self, path=save_directory / "ctfidf_config.json")

set_topic_labels(topic_labels)

Set custom topic labels in your fitted BERTopic model.

Labels are stored directly on each Topic object via topic._label.

Parameters:

Name	Type	Description	Default
topic_labels	list[str] | dict[int, str]	If a list of topic labels, it should contain the same number of labels as there are topics. This must be ordered from the topic with the lowest ID to the highest ID, including topic -1 if it exists. If a dictionary of topic ID: topic_label, it can have any number of topics as it will only map the topics found in the dictionary.	required

Examples: First, we define our topic labels with .generate_topic_labels in which we can customize our topic labels:

topic_labels = topic_model.generate_topic_labels(
    nr_words=2,
    topic_prefix=True,
    word_length=10,
    separator=", "
)

Then, we pass these topic_labels to our topic model which can be accessed at any time with .custom_labels_:

topic_model.set_topic_labels(topic_labels)
topic_model.custom_labels_

You might want to change only a few topic labels instead of all of them. To do so, you can pass a dictionary where the keys are the topic IDs and its keys the topic labels:

topic_model.set_topic_labels({0: "Space", 1: "Sports", 2: "Medicine"})
topic_model.custom_labels_

Source code in bertopic\_bertopic.py

def set_topic_labels(self, topic_labels: list[str] | dict[int, str]) -> None:
    """Set custom topic labels in your fitted BERTopic model.

    Labels are stored directly on each `Topic` object via `topic._label`.

    Arguments:
        topic_labels: If a list of topic labels, it should contain the same number
                      of labels as there are topics. This must be ordered
                      from the topic with the lowest ID to the highest ID,
                      including topic -1 if it exists.
                      If a dictionary of `topic ID`: `topic_label`, it can have
                      any number of topics as it will only map the topics found
                      in the dictionary.

    Examples:
    First, we define our topic labels with `.generate_topic_labels` in which
    we can customize our topic labels:

    ```python
    topic_labels = topic_model.generate_topic_labels(
        nr_words=2,
        topic_prefix=True,
        word_length=10,
        separator=", "
    )
    ```

    Then, we pass these `topic_labels` to our topic model which
    can be accessed at any time with `.custom_labels_`:

    ```python
    topic_model.set_topic_labels(topic_labels)
    topic_model.custom_labels_
    ```

    You might want to change only a few topic labels instead of all of them.
    To do so, you can pass a dictionary where the keys are the topic IDs and
    its keys the topic labels:

    ```python
    topic_model.set_topic_labels({0: "Space", 1: "Sports", 2: "Medicine"})
    topic_model.custom_labels_
    ```
    """
    check_is_fitted(self)
    sorted_topics = list(self._topics)  # sorted by ID

    if isinstance(topic_labels, dict):
        for topic_id, label in topic_labels.items():
            selected_topic = self._topics.get(topic_id)
            if selected_topic is not None:
                selected_topic._label = label

    elif isinstance(topic_labels, list):
        if len(topic_labels) != len(sorted_topics):
            raise ValueError(
                "Make sure that `topic_labels` contains the same number of labels as there are topics."
            )
        for selected_topic, label in zip(sorted_topics, topic_labels):
            selected_topic._label = label

transform(documents=None, embeddings=None, images=None, *, audio=None, video=None, code=None)

After having fit a model, use transform to predict new instances.

Parameters:

Name	Type	Description	Default
documents	str | list[str] | None	A single document or a list of documents to predict on	None
embeddings	ndarray	Pre-trained document embeddings. These can be used instead of the sentence-transformer model.	None
images	list | None	A list of paths to the images to predict on, or the images themselves	None
audio	list | None	A list of paths to the audio to predict on, or the clips themselves	None
video	list | None	A list of paths to the video to predict on, or the clips themselves	None
code	list[str] | None	A list of source code snippets to predict on	None

Returns:

Name	Type	Description
predictions	list[int]	Topic predictions for each documents
probabilities	ndarray	The topic probability distribution which is returned by default. If calculate_probabilities in BERTopic is set to False, then the probabilities are not calculated to speed up computation and decrease memory usage.

Examples:

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups

docs = fetch_20newsgroups(subset='all')['data']
topic_model = BERTopic().fit(docs)
topics, probs = topic_model.transform(docs)

If you want to use your own embeddings:

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups
from sentence_transformers import SentenceTransformer

# Create embeddings
docs = fetch_20newsgroups(subset='all')['data']
sentence_model = SentenceTransformer("google/embeddinggemma-2", default_prompt_name="Clustering")
sentence_model.max_seq_length = 1024
embeddings = sentence_model.encode(docs, show_progress_bar=True)

# Create topic model
topic_model = BERTopic().fit(docs, embeddings)
topics, probs = topic_model.transform(docs, embeddings)

Source code in bertopic\_bertopic.py

def transform(
    self,
    documents: str | list[str] | None = None,
    embeddings: np.ndarray = None,
    images: list | None = None,
    *,
    audio: list | None = None,
    video: list | None = None,
    code: list[str] | None = None,
) -> tuple[list[int], np.ndarray]:
    """After having fit a model, use transform to predict new instances.

    Arguments:
        documents: A single document or a list of documents to predict on
        embeddings: Pre-trained document embeddings. These can be used
                    instead of the sentence-transformer model.
        images: A list of paths to the images to predict on, or the images themselves
        audio: A list of paths to the audio to predict on, or the clips themselves
        video: A list of paths to the video to predict on, or the clips themselves
        code: A list of source code snippets to predict on

    Returns:
        predictions: Topic predictions for each documents
        probabilities: The topic probability distribution which is returned by default.
                       If `calculate_probabilities` in BERTopic is set to False, then the
                       probabilities are not calculated to speed up computation and
                       decrease memory usage.

    Examples:
    ```python
    from bertopic import BERTopic
    from sklearn.datasets import fetch_20newsgroups

    docs = fetch_20newsgroups(subset='all')['data']
    topic_model = BERTopic().fit(docs)
    topics, probs = topic_model.transform(docs)
    ```

    If you want to use your own embeddings:

    ```python
    from bertopic import BERTopic
    from sklearn.datasets import fetch_20newsgroups
    from sentence_transformers import SentenceTransformer

    # Create embeddings
    docs = fetch_20newsgroups(subset='all')['data']
    sentence_model = SentenceTransformer("google/embeddinggemma-2", default_prompt_name="Clustering")
    sentence_model.max_seq_length = 1024
    embeddings = sentence_model.encode(docs, show_progress_bar=True)

    # Create topic model
    topic_model = BERTopic().fit(docs, embeddings)
    topics, probs = topic_model.transform(docs, embeddings)
    ```
    """
    check_is_fitted(self)

    # A single document may come with its embedding as a 1-D array
    if isinstance(embeddings, np.ndarray) and embeddings.ndim == 1:
        embeddings = embeddings.reshape(1, -1)
    corpus = Corpus.from_inputs(
        documents=documents,
        images=images,
        audio=audio,
        video=video,
        code=code,
        embeddings=embeddings,
    )

    # Extract embeddings
    if corpus.embeddings is None:
        corpus.embeddings = self._embed_corpus(corpus, verbose=self.verbose)

    # Check if an embedding model was found
    if corpus.embeddings is None:
        raise ValueError(
            "No embedding model was found to embed the documents."
            "Make sure when loading in the model using BERTopic.load()"
            "to also specify the embedding model."
        )

    # Transform without hdbscan_model and umap_model using only cosine similarity
    elif type(self.hdbscan_model) is BaseCluster:
        logger.info(
            "Predicting topic assignments through cosine similarity of topic and document embeddings."
        )
        sim_matrix = cosine_similarity(corpus.embeddings, np.array(self.topic_embeddings_))
        predictions = np.argmax(sim_matrix, axis=1) - self._outliers

        if self.calculate_probabilities:
            probabilities = sim_matrix
        else:
            probabilities = np.max(sim_matrix, axis=1)

    # Transform with full pipeline
    else:
        logger.info("Dimensionality - Reducing dimensionality of input embeddings.")
        corpus.umap_embeddings = self.umap_model.transform(corpus.embeddings).astype(np.float32)
        logger.info("Dimensionality - Completed \u2713")

        # Extract predictions and probabilities if it is a HDBSCAN-like model
        logger.info("Clustering - Approximating new points with `hdbscan_model`")
        if is_supported_hdbscan(self.hdbscan_model):
            predictions, probabilities = hdbscan_delegator(
                self.hdbscan_model, "approximate_predict", corpus.umap_embeddings
            )

            # Calculate probabilities
            if self.calculate_probabilities:
                logger.info("Probabilities - Start calculation of probabilities with HDBSCAN")
                probabilities = hdbscan_delegator(
                    self.hdbscan_model, "membership_vector", corpus.umap_embeddings
                )
                logger.info("Probabilities - Completed \u2713")
        else:
            predictions = self.hdbscan_model.predict(corpus.umap_embeddings)
            probabilities = None
        logger.info("Cluster - Completed \u2713")

        # Map probabilities and predictions
        predictions = self._topics.map_predictions(predictions)
        probabilities = self._topics.align_probabilities(probabilities)

    return predictions, probabilities

update_topics(docs, images=None, topics=None, top_n_words=10, n_gram_range=None, vectorizer_model=None, ctfidf_model=None, representation_model=None, embeddings=None, *, audio=None, video=None, code=None)

Updates the topic representation by recalculating c-TF-IDF with the new parameters as defined in this function.

When you have trained a model and viewed the topics and the words that represent them, you might not be satisfied with the representation. Perhaps you forgot to remove stop_words or you want to try out a different n_gram_range. This function allows you to update the topic representation after they have been formed. The vectorizer, c-TF-IDF and representation models you do not pass are kept as they are.

Parameters:

Name	Type	Description	Default
docs	list[str]	The documents you used when calling either fit or fit_transform	required
images	list | None	The images you used when calling either fit or fit_transform	None
audio	list | None	The audio you used when calling either fit or fit_transform	None
video	list | None	The video you used when calling either fit or fit_transform	None
code	list[str] | None	The source code you used when calling either fit or fit_transform	None
topics	list[int] | None	A list of topics where each topic is related to a document in docs. Use this variable to change or map the topics. NOTE: Using a custom list of topic assignments may lead to errors if topic reduction techniques are used afterwards. Make sure that manually assigning topics is the last step in the pipeline. Number them without gaps (-1 for outliers, then 0, 1, 2, ...); to merge topics, use merge_topics.	None
top_n_words	int	The number of words per topic to extract. Setting this too high can negatively impact topic embeddings as topics are typically best represented by at most 10 words.	10
n_gram_range	tuple[int, int] | None	The n-gram range for a new CountVectorizer, replacing the model's own.	None
vectorizer_model	CountVectorizer	Pass in your own CountVectorizer from scikit-learn	None
ctfidf_model	ClassTfidfTransformer	Pass in your own c-TF-IDF model to update the representations	None
representation_model	BaseRepresentation	Pass in a model that fine-tunes the topic representations calculated through c-TF-IDF. Models from bertopic.representation are supported.	None
embeddings	ndarray | None	The document embeddings, to recompute topic embeddings from. Without them, each document counts as the embedding of the topic it was in.	None

Examples: In order to update the topic representation, you will need to first fit the topic model and extract topics from them. Based on these, you can update the representation:

topic_model.update_topics(docs, n_gram_range=(2, 3))

You can also use a custom vectorizer to update the representation:

from sklearn.feature_extraction.text import CountVectorizer
vectorizer_model = CountVectorizer(ngram_range=(1, 2), stop_words="english")
topic_model.update_topics(docs, vectorizer_model=vectorizer_model)

You can also use this function to change or map the topics to something else. You can update them as follows:

topic_model.update_topics(docs, topics=my_updated_topics)

Source code in bertopic\_bertopic.py

def update_topics(
    self,
    docs: list[str],
    images: list | None = None,
    topics: list[int] | None = None,
    top_n_words: int = 10,
    n_gram_range: tuple[int, int] | None = None,
    vectorizer_model: CountVectorizer = None,
    ctfidf_model: ClassTfidfTransformer = None,
    representation_model: BaseRepresentation = None,
    embeddings: np.ndarray | None = None,
    *,
    audio: list | None = None,
    video: list | None = None,
    code: list[str] | None = None,
):
    """Updates the topic representation by recalculating c-TF-IDF with the new
    parameters as defined in this function.

    When you have trained a model and viewed the topics and the words that represent them,
    you might not be satisfied with the representation. Perhaps you forgot to remove
    stop_words or you want to try out a different `n_gram_range`. This function allows you
    to update the topic representation after they have been formed. The vectorizer, c-TF-IDF
    and representation models you do not pass are kept as they are.

    Arguments:
        docs: The documents you used when calling either `fit` or `fit_transform`
        images: The images you used when calling either `fit` or `fit_transform`
        audio: The audio you used when calling either `fit` or `fit_transform`
        video: The video you used when calling either `fit` or `fit_transform`
        code: The source code you used when calling either `fit` or `fit_transform`
        topics: A list of topics where each topic is related to a document in `docs`.
                Use this variable to change or map the topics.
                NOTE: Using a custom list of topic assignments may lead to errors if
                      topic reduction techniques are used afterwards. Make sure that
                      manually assigning topics is the last step in the pipeline.
                      Number them without gaps (-1 for outliers, then 0, 1, 2, ...);
                      to merge topics, use `merge_topics`.
        top_n_words: The number of words per topic to extract. Setting this
                     too high can negatively impact topic embeddings as topics
                     are typically best represented by at most 10 words.
        n_gram_range: The n-gram range for a new CountVectorizer, replacing the model's own.
        vectorizer_model: Pass in your own CountVectorizer from scikit-learn
        ctfidf_model: Pass in your own c-TF-IDF model to update the representations
        representation_model: Pass in a model that fine-tunes the topic representations
                              calculated through c-TF-IDF. Models from `bertopic.representation`
                              are supported.
        embeddings: The document embeddings, to recompute topic embeddings from. Without them,
                    each document counts as the embedding of the topic it was in.

    Examples:
    In order to update the topic representation, you will need to first fit the topic
    model and extract topics from them. Based on these, you can update the representation:

    ```python
    topic_model.update_topics(docs, n_gram_range=(2, 3))
    ```

    You can also use a custom vectorizer to update the representation:

    ```python
    from sklearn.feature_extraction.text import CountVectorizer
    vectorizer_model = CountVectorizer(ngram_range=(1, 2), stop_words="english")
    topic_model.update_topics(docs, vectorizer_model=vectorizer_model)
    ```

    You can also use this function to change or map the topics to something else.
    You can update them as follows:

    ```python
    topic_model.update_topics(docs, topics=my_updated_topics)
    ```
    """
    check_documents_type(docs)
    check_is_fitted(self)

    # Update models
    if top_n_words > 100:
        logger.warning(
            "Note that extracting more than 100 words from a sparse can slow down computation quite a bit."
        )
    self.top_n_words = top_n_words
    if n_gram_range:
        vectorizer_model = vectorizer_model or CountVectorizer(ngram_range=n_gram_range)
    self.vectorizer_model = vectorizer_model or self.vectorizer_model
    self.ctfidf_model = ctfidf_model or self.ctfidf_model
    self.representation_model = representation_model or self.representation_model

    # Without embeddings, approximate each document's embedding by that of its current topic, as
    # merge_topics does, so that topic embeddings follow the documents that change topic. Documents
    # the model was not fitted on have no current topic, so they count as their new one
    fitted = topics is None or len(topics) == len(self.topics_)
    if embeddings is None:
        current_topics = self.topics_ if fitted else topics
        topic_embeddings = {topic.id: topic.embedding for topic in self._topics}
        embeddings = np.array([topic_embeddings[topic_id] for topic_id in current_topics])

    # Determine topic assignments
    topics = [int(topic) for topic in (self.topics_ if topics is None else topics)]
    new_ids, old_ids = set(topics), set(self._topics.topic_ids())
    if new_ids != old_ids:
        logger.warning(
            "Using a custom list of topic assignments may lead to errors if "
            "topic reduction techniques are used afterwards. Make sure that "
            "manually assigning topics is the last step in the pipeline."
        )
        # Missing topics are moved to outliers
        self._topics.mapping.apply(
            {topic_id: topic_id if topic_id in new_ids else -1 for topic_id in old_ids}
        )
        for topic_id in old_ids - new_ids:
            del self._topics.topics[topic_id]
        for topic_id in new_ids - old_ids:
            self._topics.topics[topic_id] = Topic(id=topic_id)
        self._topics.probabilities = None

    # Move documents between topics. Fitted probabilities only describe the documents they were fitted on
    sizes = Counter(topics)
    self._topics.predictions = topics
    if not fitted:
        self._topics.probabilities = None
    for topic in self._topics:
        topic.nr_documents = sizes[topic.id]

    corpus = Corpus.from_inputs(
        documents=docs,
        images=images,
        audio=audio,
        video=video,
        code=code,
        topics=np.array(topics),
        embeddings=embeddings,
    )

    self._extract_representations(corpus, fine_tune=True)
    self._save_representative_docs(corpus)