Top2Vec Documentation

You can install the base library using pip. Depending on your needs, you can also install optional dependencies for sentence encoders, BERT sentence transformers, or indexing.

# Base installation
pip install top2vec

# With universal sentence encoder support
pip install top2vec[sentence_encoders]

# With BERT sentence transformer support
pip install top2vec[sentence_transformers]

# With indexing support
pip install top2vec[indexing]

When initializing the Top2Vec class, you can tune the following parameters:

• documents: Input corpus (list of strings).
• speed: Determines training speed vs quality. Options are:
  • 'fast-learn': Fastest, lowest quality.
  • 'learn': Better quality, longer training.
  • 'deep-learn': Best quality, significant training time.
• workers: Number of worker threads to use for training (larger values speed up training).
• embedding_model: Specifies the pre-trained model for joint word/document embeddings. Options include:
  • 'universal-sentence-encoder'
  • 'universal-sentence-encoder-multilingual'
  • 'distiluse-base-multilingual-cased' (suggested for multilingual datasets).

When using a Contextual Top2Vec model, you can use the following methods to analyze topic distributions at the document level:

• get_document_topic_distribution(): Returns a numpy.ndarray of shape (num_documents, num_topics) representing the probability distribution of topics for each document.
• get_document_topic_relevance(): Returns a numpy.ndarray of shape (num_documents, num_topics) indicating the relevance scores of topics for each document.

Generate a word cloud visualization for a specific topic index.

model.generate_topic_wordcloud(topic_num)

model.generate_topic_wordcloud(topic)

For granular analysis in Contextual Top2Vec, use these methods:

• get_document_token_topic_assignment(): Returns a List[Document] where each Document object contains topic assignments and scores for every token.
• get_document_tokens(): Returns a List[List[str]] containing the tokens for each document.

Find topics that are semantically similar to a set of keywords.

Returns:

• topic_words: Top 50 words for each topic.
• word_scores: Cosine similarity scores of the top 50 words to the topic.
• topic_scores: Cosine similarity of each topic to the search keywords.
• topic_nums: Unique indices of the found topics.

topic_words, word_scores, topic_scores, topic_nums = model.search_topics(keywords=["medicine"], num_topics=5)

Search for words that are semantically similar to a given keyword.

Returns:

• words: List of similar words.
• word_scores: Similarity scores for each word.

words, word_scores = model.similar_words(keywords=["space"], keywords_neg=[], num_words=20)

You can persist trained models to disk and reload them later.

model.save("filename")
model = Top2Vec.load("filename")

Retrieve documents that are most similar to a specific topic index.

Returns:

• documents: List of documents (most similar first).
• document_scores: Semantic similarity (cosine similarity) of the document to the topic.
• document_ids: Unique IDs of the documents (or index in original corpus).

documents, document_scores, document_ids = model.search_documents_by_topic(topic_num=48, num_docs=5)

Contextual Top2Vec (currently in beta) allows for deeper topic modeling by generating contextual token embeddings. This enables identifying multiple topics per document and detecting topic segments (spans) within a document.

To use this mode, set contextual_top2vec=True. Note that only the following embedding models are supported:

• all-MiniLM-L6-v2
• all-mpnet-base-v2

from top2vec import Top2Vec

# Create a Contextual Top2Vec model
top2vec_model = Top2Vec(documents=documents,
                        ngram_vocab=True,
                        contextual_top2vec=True)

Use search_documents_by_keyword to find documents based on semantic similarity to a set of keywords. Supports negative keywords to refine results.

Parameters:

• keywords: List of keywords to search for.
• num_docs: Number of documents to return.
• keywords_neg: List of keywords to exclude from the search.

documents, document_scores, document_nums = top2vec.search_documents_by_keyword(keywords=keywords_input_kw.value.split(), num_docs=int(doc_num_input_kw.value), keywords_neg=keywords_neg_input_kw.value.split())

Load a previously trained Top2Vec model from a directory using the Top2Vec.load method.

top2vec = Top2Vec.load("../input/covid19top2vec/covid19_deep_learn_top2vec")