TopMost

https://topmost.readthedocs.io/en/latest/
Admin
TopMost provides complete lifecycles of topic modeling, including datasets, preprocessing, models,...
Tokens:176,833
Snippets:687
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install TopMost using pip

Source: https://topmost.readthedocs.io/en/latest/_sources/quick_start

This command installs the TopMost Python package using pip. Ensure you have pip installed and configured correctly on your system.

```console
pip install topmost
```

--------------------------------

### Install TopMost Stable Release via Pip

Source: https://topmost.readthedocs.io/en/latest/installation

Installs the most recent stable release of TopMost using pip. This is the recommended installation method.

```bash
$ pip install topmost
```

--------------------------------

### Install TopMost from GitHub Sources

Source: https://topmost.readthedocs.io/en/latest/installation

Installs TopMost directly from its GitHub repository using pip. This method is useful for installing development versions or specific commits.

```bash
$ pip install git+https://github.com/bobxwu/TopMost.git
```

--------------------------------

### Download Preprocessed Dataset in Python

Source: https://topmost.readthedocs.io/en/latest/_sources/quick_start

Shows how to download a preprocessed dataset, '20NG', using the topmost library. The dataset will be saved to the specified cache path.

```python
import topmost

topmost.download_dataset('20NG', cache_path='./datasets')
```

--------------------------------

### Install TopMost with Pip

Source: https://topmost.readthedocs.io/en/latest/quick_start

Installs the TopMost Python package using pip. This is the primary method for getting the library onto your system.

```bash
$ pip install topmost

```

--------------------------------

### Train ProdLDA Model in Python

Source: https://topmost.readthedocs.io/en/latest/_sources/quick_start

Illustrates training a ProdLDA topic model using the topmost library. This involves loading a preprocessed dataset, initializing the ProdLDA model, and then training it using a BasicTrainer.

```python
device = "cuda" # or "cpu"

# load a preprocessed dataset
dataset = topmost.BasicDataset("./datasets/20NG", device=device, read_labels=True)
# create a model
model = topmost.ProdLDA(dataset.vocab_size)
model = model.to(device)

# create a trainer
trainer = topmost.BasicTrainer(model, dataset)

# train the model
top_words, train_theta = trainer.train()
```

--------------------------------

### Test New Documents with Trained Model in Python

Source: https://topmost.readthedocs.io/en/latest/_sources/quick_start

Demonstrates how to process and test new, unseen documents using a pre-trained TopMost model. It involves preprocessing the new documents, converting them into a bag-of-words representation, and then using the trainer to predict their topic distributions.

```python
import torch
from topmost import Preprocess

new_docs = [
    "This is a new document about space, including words like space, satellite, launch, orbit.",
    "This is a new document about Microsoft Windows, including words like windows, files, dos."
]

preprocess = Preprocess()
new_parsed_docs, new_bow = preprocess.parse(new_docs, vocab=dataset.vocab)
new_theta = trainer.test(torch.as_tensor(new_bow.toarray(), device=device).float())
```

--------------------------------

### SawETM Class Initialization

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/index

Initializes the SawETM (Sawtooth Factorial Topic Embeddings Guided Gamma Belief Network) model. This class is designed for hierarchical topic modeling using a guided gamma belief network and sawtooth connections.

```python
class _SawETM(_vocab_size_ , _num_topics_list_ , _device ='cpu'_, _embed_size =100_, _hidden_size =256_, _pretrained_WE =None_):
    """
    Bases: `torch.nn.Module`
    Sawtooth Factorial Topic Embeddings Guided Gamma Belief Network. ICML 2021.
    Zhibin Duan, Dongsheng Wang, Bo Chen, Chaojie Wang, Wenchao Chen, Yewen Li, Jie Ren, Mingyuan Zhou.
    https://github.com/ZhibinDuan/SawETM 
    """
    pass
```

--------------------------------

### FASTopicTrainer for Topic Modeling in Python

Source: https://topmost.readthedocs.io/en/latest/_sources/quick_start

Demonstrates using FASTopicTrainer from the topmost library to extract top words and document topic distributions from a dataset. It involves preprocessing text data and training a model, then testing with new documents to predict their topic distributions.

```python
from topmost import RawDataset, Preprocess, FASTopicTrainer
from sklearn.datasets import fetch_20newsgroups

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

dataset = RawDataset(docs, preprocess, device="cuda")

trainer = FASTopicTrainer(dataset, verbose=True)
top_words, doc_topic_dist = trainer.train()

new_docs = [
    "This is a document about space, including words like space, satellite, launch, orbit.",
    "This is a document about Microsoft Windows, including words like windows, files, dos."
]

new_theta = trainer.test(new_docs)
print(new_theta.argmax(1))
```

--------------------------------

### Train FASTopic Model and Test New Documents

Source: https://topmost.readthedocs.io/en/latest/quick_start

Demonstrates training a FASTopic model using the TopMost library and then testing new documents to get their topic distributions. It utilizes scikit-learn's fetch_20newsgroups for sample data and requires a CUDA-enabled device for optimal performance.

```python
from topmost import RawDataset, Preprocess, FASTopicTrainer
from sklearn.datasets import fetch_20newsgroups

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

dataset = RawDataset(docs, preprocess, device="cuda")

trainer = FASTopicTrainer(dataset, verbose=True)
top_words, doc_topic_dist = trainer.train()

new_docs = [
    "This is a document about space, including words like space, satellite, launch, orbit.",
    "This is a document about Microsoft Windows, including words like windows, files, dos."
]

new_theta = trainer.test(new_docs)
print(new_theta.argmax(1))

```

--------------------------------

### Evaluate Topic Model Performance in Python

Source: https://topmost.readthedocs.io/en/latest/_sources/quick_start

Provides code for evaluating a trained topic model. It calculates topic diversity (TD) and coherence (TC), obtains document-topic distributions for testing samples, and performs clustering and classification based on these distributions.

```python
from topmost import eva

# topic diversity and coherence
TD = eva._diversity(top_words)
TC = eva._coherence(dataset.train_texts, dataset.vocab, top_words)

# get doc-topic distributions of testing samples
test_theta = trainer.test(dataset.test_data)
# clustering
clustering_results = eva._clustering(test_theta, dataset.test_labels)
# classification
cls_results = eva._cls(train_theta, test_theta, dataset.train_labels, dataset.test_labels)
```

--------------------------------

### SawETM Class Initialization

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/models/hierarchical/SawETM/SawETM/index

Initializes the SawETM model, a Sawtooth Factorial Topic Embeddings Guided Gamma Belief Network. It takes vocabulary size, topic number list, and device as primary arguments, with optional parameters for embedding and hidden layer sizes, and pre-trained word embeddings.

```python
SawETM(vocab_size, num_topics_list, device='cpu', embed_size=100, hidden_size=256, pretrained_WE=None)
```

--------------------------------

### SawETM Model Initialization and Core Methods (Python)

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/index

The SawETM class, a PyTorch module, implements the Sawtooth Factorial Topic Embeddings Guided Gamma Belief Network. It includes methods for reparameterization, KL divergence calculation, negative likelihood estimation, and retrieving topic embeddings and factor loading matrices.

```python
class SawETM(_vocab_size_ , _num_topics_list_ , _device ='cpu'_, _embed_size =100_, _hidden_size =256_, _pretrained_WE =None_):
    Bases: `torch.nn.Module`
    ...
    device _ = 'cpu'_
    gam_prior
    real_min
    theta_max
    wei_shape_min
    wei_shape_max
    num_topics_list
    num_hiddens_list
    num_layers
    alpha
    h_encoder
    q_theta

    def log_max(_x_):
        ...

    def reparameterize(_shape_ , _scale_ , _sample_num =50_):
        """Returns a sample from a Weibull distribution via reparameterization."""
        ...

    def kl_weibull_gamma(_wei_shape_ , _wei_scale_ , _gam_shape_ , _gam_scale_):
        """Returns the Kullback-Leibler divergence between a Weibull distribution and a Gamma distribution."""
        ...

    def get_nll(_x_ , _x_reconstruct_):
        """Returns the negative Poisson likelihood of observational count data."""
        ...

    @property
    def bottom_word_embeddings:
        ...

    @property
    def topic_embeddings_list:
        ...

    def get_phis():
        """Returns the factor loading matrix by utilizing sawtooth connection."""
        ...

    def get_beta():
        ...

    def get_phi_list():
        ...

    def get_theta(_x_):
        ...

    def forward(_x_ , _times_):
        ...
```

--------------------------------

### FASTopicTrainer Initialization

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/trainers/basic/FASTopic_trainer/index

Details the constructor for the FASTopicTrainer class, outlining the parameters used to initialize the topic modeling process.

```APIDOC
## FASTopicTrainer Initialization

### Description
Initializes the FASTopicTrainer with a dataset and various parameters to configure the topic modeling process.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **dataset** (object) - Required - The dataset to be used for training.
- **num_topics** (int) - Optional - The number of topics to discover. Defaults to 50.
- **num_top_words** (int) - Optional - The number of top words to display for each topic. Defaults to 15.
- **preprocess** (callable) - Optional - A preprocessing function to apply to the texts.
- **epochs** (int) - Optional - The number of training epochs. Defaults to 200.
- **DT_alpha** (float) - Optional - Parameter for the document-topic distribution. Defaults to 3.0.
- **TW_alpha** (float) - Optional - Parameter for the topic-word distribution. Defaults to 2.0.
- **theta_temp** (float) - Optional - Temperature parameter for theta. Defaults to 1.0.
- **verbose** (bool) - Optional - Whether to display verbose output during training. Defaults to False.

### Request Example
```json
{
  "dataset": "<your_dataset_object>",
  "num_topics": 100,
  "epochs": 300,
  "verbose": true
}
```

### Response
#### Success Response (200)
Initializes the FASTopicTrainer object.

#### Response Example
(No direct response, object is instantiated)
```

--------------------------------

### SawETM - Sawtooth Factorial Topic Embeddings

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/models/index

Documentation for the SawETM model, which uses sawtooth factorial topic embeddings guided by a Gamma belief network.

```APIDOC
## SawETM Model Details

### Description
Sawtooth Factorial Topic Embeddings Guided Gamma Belief Network. Published in ICML 2021.

### Authors
Zhibin Duan, Dongsheng Wang, Bo Chen, Chaojie Wang, Wenchao Chen, Yewen Li, Jie Ren, Mingyuan Zhou.

### Repository
https://github.com/ZhibinDuan/SawETM

### Initialization Parameters
- `vocab_size` (int) - The size of the vocabulary.
- `num_topics_list` (list) - A list specifying the number of topics for each layer.
- `device` (str, optional) - The device to use ('cpu' or 'cuda'). Defaults to 'cpu'.
- `embed_size` (int, optional) - Dimension of word embeddings. Defaults to 100.
- `hidden_size` (int, optional) - Dimension of hidden layers in the encoder. Defaults to 256.
- `pretrained_WE` (object, optional) - Pretrained word embeddings. Defaults to None.

### Attributes
- `device` (str) - The device used by the model.
- `gam_prior` (object) - Gamma prior distribution parameters.
- `real_min` (float) - Minimum real value for numerical stability.
- `theta_max` (float) - Maximum value for topic proportions.
- `wei_shape_min` (float) - Minimum shape parameter for Weibull distribution.
- `wei_shape_max` (float) - Maximum shape parameter for Weibull distribution.
- `num_topics_list` (list) - Number of topics for each layer.
- `num_hiddens_list` (list) - Number of hidden units for each layer.
- `num_layers` (int) - The number of layers in the model.
- `alpha` (object) - Parameter alpha.
- `h_encoder` (object) - The hierarchical encoder.
- `q_theta` (object) - Variational distribution for topic proportions.

### Methods
- `log_max(x)`: Computes the logarithm, ensuring numerical stability.
- `reparameterize(shape, scale, sample_num=50)`: Reparameterizes a Weibull distribution.
- `kl_weibull_gamma(wei_shape, wei_scale, gam_shape, gam_scale)`: Computes KL divergence between Weibull and Gamma distributions.
- `get_nll(x, x_reconstruct)`: Computes the negative Poisson likelihood.
- `bottom_word_embeddings` (property): Word embeddings for the bottom layer.
- `topic_embeddings_list` (property): Topic embeddings for each layer.
- `get_phis()`: Returns the factor loading matrix.
- `get_beta()`: Returns the topic matrix.
- `get_phi_list()`: Returns the factor loading matrices for each layer.
- `get_theta(x)`: Computes topic proportions.
- `forward(x)`: Forward pass: computes KL loss and data likelihood.
```

--------------------------------

### Get Topic Embeddings

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/hierarchical/SawETM/SawETM/index

Retrieves the topic embeddings from the SawETM model. This method is crucial for interpreting the learned topics and their relationship to words.

```python
def get_phi_list():
    """Returns the factor loading matrix by utilizing sawtooth connection."""
    pass
```

```python
def get_beta():
    pass
```

```python
def get_phi_list():
    pass
```

--------------------------------

### Get Document-Topic Distribution

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/models/hierarchical/SawETM/SawETM/index

Computes and returns the document-topic distribution (theta) for a given input document representation 'x'. This indicates the topic mixture for each document.

```python
get_theta(x)
```

--------------------------------

### Basic Trainer Initialization and Methods (Python)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/trainers/index

Demonstrates the initialization of the BasicTrainer class and its core methods for training, testing, and retrieving topic information. This trainer is suitable for general topic modeling tasks.

```python
from topmost.trainers import BasicTrainer

# Assuming 'model' and 'dataset' are pre-defined objects
basic_trainer = BasicTrainer(model=my_model, dataset=my_dataset, num_top_words=10, epochs=300)

# Train the model
basic_trainer.train()

# Test the model with a bag-of-words representation
bow_data = preprocess_data(my_data)
results = basic_trainer.test(bow=bow_data)

# Get topic-word distributions
beta_values = basic_trainer.get_beta()

# Get top words for each topic
top_words = basic_trainer.get_top_words(num_top_words=10)

# Export topic-document distributions
theta_export = basic_trainer.export_theta()
```

--------------------------------

### FASTopicTrainer Class Initialization

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/trainers/basic/FASTopic_trainer/index

Initializes the FASTopicTrainer with specified parameters for topic modeling. Accepts dataset, number of topics, top words, preprocessing options, training epochs, alpha values for document-topic and topic-word distributions, temperature, and verbosity. Dependencies include the dataset object and optional preprocessing functions.

```python
class _FASTopicTrainer(_dataset_ , _num_topics =50_, _num_top_words =15_, _preprocess =None_, _epochs =200_, _DT_alpha =3.0_, _TW_alpha =2.0_, _theta_temp =1.0_, _verbose =False_):
    pass
```

--------------------------------

### Get Topic-Word Distributions

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/trainers/basic/BERTopic_trainer/index

The get_beta method retrieves the topic-word distributions (beta) from the trained BERTopic model. This is useful for understanding the composition of each topic.

```python
BERTopicTrainer.get_beta()
```

--------------------------------

### Get Topics Difference

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/eva/hierarchy_quality/index

Extracts the differences between topic pairs within specified groups. This function aggregates and analyzes the differences identified between topics.

```python
def get_topics_difference(_topic_pair_groups_):
    """
    Get the differences between topic pairs.

    Parameters:
        topic_pair_groups (list): Groups of topic pairs.

    Returns:
        Any: The differences between topics.
    """
    pass
```

--------------------------------

### FASTopicTrainer Initialization and Methods (Python)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/trainers/index

Details the initialization and methods of the FASTopicTrainer, designed for FastTopics, a faster topic modeling algorithm. It supports custom preprocessing and various training parameters.

```python
from topmost.trainers import FASTopicTrainer

# Assuming 'dataset' is a pre-defined object
fast_trainer = FASTopicTrainer(dataset=my_dataset, num_topics=40, num_top_words=10, epochs=250, DT_alpha=2.5, theta_temp=0.8)

# Train the FastTopics model
fast_trainer.train()

# Test the model with a list of texts
text_data = load_texts(my_data)
results = fast_trainer.test(texts=text_data)

# Get topic-word distributions
beta_values = fast_trainer.get_beta()

# Get top words for each topic
top_words = fast_trainer.get_top_words(num_top_words=10)

# Export topic-document distributions
theta_export = fast_trainer.export_theta()
```

--------------------------------

### Get Activation Function (Python)

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/hierarchical/SawETM/block/index

A utility function to retrieve PyTorch activation functions based on a string name. It supports 'relu' and 'gelu'.

```python
def _get_activation_fn(activation):
    if activation == 'relu':
        return torch.nn.ReLU()
    elif activation == 'gelu':
        return torch.nn.GELU()
    else:
        raise ValueError(f"Unknown activation function: {activation}")
```

--------------------------------

### Train ProdLDA Model with TopMost

Source: https://topmost.readthedocs.io/en/latest/quick_start

Illustrates training a ProdLDA topic model using a preprocessed dataset. It covers loading the dataset, initializing the model and trainer, and performing the training process. Supports both 'cuda' and 'cpu' devices.

```python
device = "cuda" # or "cpu"

# load a preprocessed dataset
dataset = topmost.BasicDataset("./datasets/20NG", device=device, read_labels=True)
# create a model
model = topmost.ProdLDA(dataset.vocab_size)
model = model.to(device)

# create a trainer
trainer = topmost.BasicTrainer(model, dataset)

# train the model
top_words, train_theta = trainer.train()

```

--------------------------------

### Get Topic Distribution (HyperMiner)

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/hierarchical/HyperMiner/HyperMiner/index

Retrieves the topic distribution parameter (beta) for the HyperMiner model. This parameter typically represents the probability of words belonging to topics.

```python
def get_beta(self):
    pass
```

--------------------------------

### Get Child Topic Index - Python

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/eva/build_hierarchy/index

Retrieves the index of a child topic given a phi value and a topic index. This function is part of the build_hierarchy module.

```python
def get_child_topic_idx(_phi_ , _topic_idx_):
     pass
```

--------------------------------

### BasicTrainer Class Initialization

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/trainers/basic/basic_trainer/index

Defines the constructor for the BasicTrainer class. It takes a model, dataset, and various training parameters like the number of top words, epochs, learning rate, batch size, and learning rate scheduler configurations. Verbosity and logging intervals are also configurable.

```python
class BasicTrainer(_model_, _dataset_, _num_top_words_=15, _epochs=200, _learning_rate=0.002, _batch_size=200, _lr_scheduler=None, _lr_step_size=125, _log_interval=5, _verbose=False_):
    """
    Initializes the BasicTrainer.

    Args:
        _model_: The model to be trained.
        _dataset_: The dataset to use for training.
        _num_top_words (int): The number of top words to consider.
        _epochs (int): The number of training epochs.
        _learning_rate (float): The learning rate for the optimizer.
        _batch_size (int): The batch size for training.
        _lr_scheduler: The learning rate scheduler to use (optional).
        _lr_step_size (int): The step size for the learning rate scheduler.
        _log_interval (int): The interval for logging training progress.
        _verbose (bool): Whether to enable verbose output during training.
    """
    pass
```

--------------------------------

### Get All Topic-Word Distributions (Phi List)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/models/hierarchical/SawETM/SawETM/index

Returns a list of all topic-word distributions (phi) across different layers or components of the model. This provides a comprehensive view of the topic representations.

```python
get_phi_list()
```

--------------------------------

### NMFSklearnTrainer Initialization and Methods (Python)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/trainers/index

Explains the NMFSklearnTrainer for NMF using Scikit-learn. This trainer requires a pre-configured Scikit-learn NMF model and offers functionalities for training and analysis.

```python
from sklearn.decomposition import NMF
from topmost.trainers import NMFSklearnTrainer

# Initialize Scikit-learn NMF model
sklearn_nmf_model = NMF(n_components=45, init='nndsvd', random_state=42)

# Assuming 'dataset' is a pre-defined object
nmf_sklearn_trainer = NMFSklearnTrainer(model=sklearn_nmf_model, dataset=my_dataset, num_top_words=12)

# Train the NMF model
nmf_sklearn_trainer.train()

# Test the model with a bag-of-words representation
bow_data = preprocess_data(my_data)
results = nmf_sklearn_trainer.test(bow=bow_data)

# Get topic-word distributions
beta_values = nmf_sklearn_trainer.get_beta()

# Get top words for each topic
top_words = nmf_sklearn_trainer.get_top_words(num_top_words=12)

# Export topic-document distributions
theta_export = nmf_sklearn_trainer.export_theta()
```

--------------------------------

### Initialize Basic Dataset for Topic Modeling

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/index

The `BasicDataset` class is used to load and prepare text data for topic modeling tasks. It handles reading data from a directory, optionally reading labels, and can convert the data into tensors. It supports device selection ('cpu' or 'cuda') and can optionally use contextual embeddings.

```python
from topmost import BasicDataset

# Initialize BasicDataset
basic_dataset = BasicDataset(
    dataset_dir='path/to/your/dataset',
    batch_size=200,
    read_labels=True,
    as_tensor=True,
    device='cpu'
)

# The dataset object can now be used for training or evaluation.
```

--------------------------------

### Get Top Words for Topics

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/trainers/basic/BERTopic_trainer/index

The get_top_words method returns the most representative words for each topic in the trained BERTopic model. This provides a concise summary of each topic's content.

```python
BERTopicTrainer.get_top_words()
```

--------------------------------

### Exponential Map from Origin

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/hierarchical/HyperMiner/manifolds/index

Computes the exponential map from the tangent space at the origin to a point on the PoincareBall manifold. This is a specific case of the exponential map starting from the manifold's identity element.

```python
def expmap0(self, v, c):
    """Map a point v in the tangent space of origin point to the manifold. :param v: A point in the tangent space of origin point. :type v: tensor :param c: The manifold curvature. :type c: tensor Returns: The result of mapping tangent point v to the manifold. Return type: tensor """
    pass
```

--------------------------------

### FASTopicTrainer Class Initialization and Methods - Python

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/trainers/basic/FASTopic_trainer/index

Defines the FASTopicTrainer class for topic modeling. It accepts a dataset and various parameters to control the training process, including the number of topics, epochs, and hyperparameters. Key methods allow for training, testing, retrieving topic-word distributions, top words, and document-topic distributions.

```python
class FASTopicTrainer(dataset, num_topics=50, num_top_words=15, preprocess=None, epochs=200, DT_alpha=3.0, TW_alpha=2.0, theta_temp=1.0, verbose=False):
    """
    Initializes the FASTopicTrainer.

    Args:
        dataset: The input dataset for training.
        num_topics (int): The number of topics to model.
        num_top_words (int): The number of top words to display for each topic.
        preprocess (callable, optional): A function for preprocessing text data.
        epochs (int): The number of training epochs.
        DT_alpha (float): Hyperparameter for document-topic distribution.
        TW_alpha (float): Hyperparameter for topic-word distribution.
        theta_temp (float): Temperature parameter for theta.
        verbose (bool): Whether to display training progress.
    """
    pass

    def train():
        """Trains the topic model."""
        pass

    def test(texts):
        """Tests the model with given texts."""
        pass

    def get_beta():
        """Retrieves the topic-word distribution (beta)."""
        pass

    def get_top_words(num_top_words=None):
        """Gets the top words for each topic."""
        pass

    def export_theta():
        """Exports the document-topic distribution (theta)."""
        pass
```

--------------------------------

### SawETM Class Initialization and Parameters

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/hierarchical/SawETM/SawETM/index

Initializes the SawETM module, a PyTorch model for topic modeling. It takes vocabulary size, a list of topic numbers, and various network architecture parameters as input. It also handles device placement and optional pre-trained embeddings.

```python
class _SawETM(_vocab_size_ , _num_topics_list_ , _device ='cpu'_, _embed_size =100_, _hidden_size =256_, _pretrained_WE =None_):
    pass
```

--------------------------------

### Get Document Embeddings

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/hierarchical/SawETM/SawETM/index

Calculates and returns the document embeddings (theta) given input data. This is a core part of the topic modeling process, representing each document as a distribution over topics.

```python
def get_theta(_x_):
    pass
```

--------------------------------

### BERTopic Trainer Initialization and Methods (Python)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/trainers/index

Illustrates the usage of the BERTopicTrainer for topic modeling using the BERTopic library. It covers model initialization, training, testing with text data, and accessing topic representations.

```python
from topmost.trainers import BERTopicTrainer

# Assuming 'dataset' is a pre-defined object
bertopic_trainer = BERTopicTrainer(dataset=my_dataset, num_topics=30, num_top_words=12)

# Train the BERTopic model
bertopic_trainer.train()

# Test the model with a list of texts
text_data = load_texts(my_data)
results = bertopic_trainer.test(texts=text_data)

# Get topic-word distributions
beta_values = bertopic_trainer.get_beta()

# Get top words for each topic
top_words = bertopic_trainer.get_top_words()

# Export topic-document distributions
theta_export = bertopic_trainer.export_theta()
```

--------------------------------

### Get Topic-Word Distribution (Beta)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/models/hierarchical/SawETM/SawETM/index

Returns the beta matrix, which represents the parameters of the topic-word distributions. This is another way to access the model's learned word probabilities per topic.

```python
get_beta()
```

--------------------------------

### FASTopicTrainer API

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/index

Documentation for the FASTopicTrainer class, implementing a Fast Approximate Topic Model. It includes training, testing, and topic information retrieval methods.

```APIDOC
## FASTopicTrainer

### Description
Trainer for Fast Approximate Topic Models.

### Methods
- `train()`: Trains the topic model.
- `test(texts)`: Tests the model with a list of texts.
- `get_beta()`: Retrieves the topic-word distributions.
- `get_top_words(num_top_words=None)`: Gets the top words for each topic.
- `export_theta()`: Exports the document-topic distributions.

### Attributes
- `dataset`: The dataset used for training.
- `num_top_words` (int): The number of top words to display per topic (default: 15).
- `model`: The underlying topic modeling model.
- `epochs` (int): The number of training epochs (default: 200).
- `preprocess`: A preprocessing function to apply to the data.
- `DT_alpha` (float): Alpha parameter for document-topic distribution (default: 3.0).
- `TW_alpha` (float): Alpha parameter for topic-word distribution (default: 2.0).
- `theta_temp` (float): Temperature for document-topic distribution sampling (default: 1.0).
- `verbose` (bool): Whether to enable verbose output during training (default: False).
```

--------------------------------

### Get Sibling Topic Difference (TD)

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/eva/hierarchy_quality/index

Calculates the Topic Difference (TD) metric for groups of sibling topics. This function quantifies the distinctiveness among topics at the same hierarchical level.

```python
def get_Sibling_TD(_sibling_groups_):
    """
    Get the Topic Difference (TD) for sibling groups.

    Parameters:
        sibling_groups (list): Groups of sibling topics.

    Returns:
        Any: The computed TD for sibling groups.
    """
    pass
```

--------------------------------

### DynamicTrainer Class Initialization

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/trainers/dynamic/dynamic_trainer/index

Initializes the DynamicTrainer class with various parameters to configure the training process. Key parameters include the model, dataset, number of top words to consider, training epochs, learning rate, batch size, and optional learning rate scheduler configurations. Verbose flag controls the output during training.

```python
class _DynamicTrainer(_model_, _dataset_, _num_top_words=15, _epochs=200, _learning_rate=0.002, _batch_size=200, _lr_scheduler=None, _lr_step_size=125, _log_interval=5, _verbose=False):
    pass
```

--------------------------------

### ETC (Evolution-Tracking Contrastive Learning)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/index

Documentation for the ETC model, which focuses on modeling dynamic topics in a chain-free fashion.

```APIDOC
## ETC Model Documentation

### Description
Models dynamic topics using Evolution-Tracking Contrastive Learning and Unassociated Word Exclusion.

### Attributes
- **num_topics** (int) - The number of topics.
- **beta_temp** (float) - Temperature parameter for beta distribution.
- **train_time_wordfreq** (object) - Word frequency during training.
- **encoder** (object) - Encoder network.
- **a** (object) - Parameter a.
- **mu2** (object) - Parameter mu2.
- **var2** (object) - Parameter var2.
- **decoder_bn** (object) - Decoder batch normalization.
- **topic_embeddings** (object) - Topic embeddings.
- **ETC** (object) - ETC specific component.
- **UWE** (object) - Unassociated Word Exclusion component.

### Methods
- **get_beta()**: Returns the beta parameter.
- **pairwise_euclidean_dist(x, y)**: Computes pairwise Euclidean distance between two tensors.
- **get_theta(x, times=None)**: Computes topic distributions.
- **get_KL(mu, logvar)**: Computes Kullback-Leibler divergence.
- **get_NLL(theta, beta, x, recon_x=None)**: Computes negative log-likelihood.
- **decode(theta, beta)**: Decodes topic distributions back to word distributions.
- **forward(x, times)**: Forward pass of the model.
```

--------------------------------

### Get Topic-Word Distribution (Factor Loading Matrix)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/models/hierarchical/SawETM/SawETM/index

Retrieves the topic-word distribution, represented as a factor loading matrix, by employing a sawtooth connection mechanism. This method defines how topics are composed of words.

```python
get_phis()
```

--------------------------------

### Parallel Transport from Origin

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/hierarchical/HyperMiner/manifolds/index

Performs parallel transport of a vector 'v' from the tangent space at the origin to the tangent space at 'y' on the PoincareBall manifold. This is a specialized parallel transport starting from the manifold's identity element.

```python
def ptransp0(self, v, x, c):
    """Parallel transport function, used to move point v in the tangent space of origin point to the tangent space of y. :param v: A point in the tangent space of origin point. :type v: tensor :param x: A point on the manifold. :type x: tensor :param c: The manifold curvature. :type c: tensor Returns: The result of transporting v from the tangent space at origin point to the tangent space at y. Return type: tensor """
    pass
```

--------------------------------

### BasicTrainer Training Methods

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/trainers/basic/basic_trainer/index

Contains methods for training, testing, and optimizing the model within the BasicTrainer class. These include functions to create an optimizer, set up a learning rate scheduler, execute the training loop, and perform tests using a bag-of-words representation.

```python
def make_optimizer(self):
    """Creates the optimizer for the model."""
    pass

def make_lr_scheduler(self, _optimizer_):
    """Creates the learning rate scheduler."""
    pass

def train(self):
    """Trains the model."""
    pass

def test(self, _bow_):
    """Tests the model with a bag-of-words representation."""
    pass
```

--------------------------------

### TraCo Parameter Retrieval Methods (PyTorch)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/models/index

These methods allow retrieval of key parameters from the TraCo model. They include methods to get the factor loading matrix (phi), the beta parameter, and lists of embeddings or parameters.

```python
def get_phi(self):
    """Returns the factor loading matrix by utilizing sawtooth connection."""
    # ... implementation details ...

def get_beta(self):
    """Returns the beta parameter."""
    # ... implementation details ...

def get_phi_list(self):
    """Returns a list of phi parameters."""
    # ... implementation details ...

def get_theta(self, input_bow):
    """Returns the theta parameter."""
    # ... implementation details ...

```

--------------------------------

### BasicTrainer Class for Topic Modeling

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/index

The BasicTrainer class provides a foundational structure for training topic models. It initializes with a model and dataset, and allows configuration of training parameters like epochs, learning rate, and batch size. Key methods include training, testing, and retrieving top words and model parameters.

```python
class BasicTrainer(model, dataset, num_top_words=15, epochs=200, learning_rate=0.002, batch_size=200, lr_scheduler=None, lr_step_size=125, log_interval=5, verbose=False):
    """Basic trainer class for topic modeling."""
    pass
```

--------------------------------

### Get Sibling Groups

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/eva/hierarchy_quality/index

Groups topics that are siblings within a given topic hierarchy. It processes the hierarchy structure to identify and collect topics at the same level, optionally for a specific layer ID.

```python
def get_sibling_groups(_topic_hierarchy_ , _sibling_groups_ , _layer_id =0_):
    """
    Get groups of sibling topics.

    Parameters:
        topic_hierarchy (dict): The topic hierarchy structure.
        sibling_groups (list): Existing sibling groups.
        layer_id (int, optional): The specific layer ID to consider. Defaults to 0.

    Returns:
        list: A list of sibling groups.
    """
    pass
```

--------------------------------

### HDPGensimTrainer Class

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/index

Documentation for the HDPGensimTrainer class, integrating with Gensim's HDP implementation.

```APIDOC
## HDPGensimTrainer Class

### Description
This class provides an interface for training Hierarchical Dirichlet Process (HDP) models using Gensim.

### Parameters
- **dataset**: The dataset to train on.
- **num_top_words** (int) - The number of top words to display per topic. Defaults to 15.
- **max_chunks** (int) - Maximum number of chunks to process. Defaults to None.
- **max_time** (float) - Maximum training time in seconds. Defaults to None.
- **chunksize** (int) - Size of mini-batches (chunks) for online training. Defaults to 256.
- **kappa** (float) - Learning rate decay factor. Defaults to 1.0.
- **tau** (float) - Burn-in period for learning rate. Defaults to 64.0.
- **K** (int) - Number of topics. Defaults to 15.
- **T** (int) - Number of top-level topics. Defaults to 150.
- **alpha** (float) - Dirichlet prior parameter for topic distributions. Defaults to 1.
- **gamma** (float) - Dirichlet prior parameter for document-topic distributions. Defaults to 1.
- **eta** (float) - Dirichlet prior parameter for topic-word distributions. Defaults to 0.01.
- **scale** (float) - Scaling factor for topic-word distributions. Defaults to 1.0.
- **var_converge** (float) - Convergence threshold for variational inference. Defaults to 0.0001.
- **verbose** (bool) - Whether to print verbose output. Defaults to False.

### Attributes
- **dataset**
- **num_top_words** (int) - Defaults to 15.
- **vocab_size**
- **max_chunks** (float or None) - Defaults to None.
- **max_time** (float or None) - Defaults to None.
- **chunksize** (int) - Defaults to 256.
- **kappa** (float) - Defaults to 1.0.
- **tau** (float) - Defaults to 64.0.
- **K** (int) - Defaults to 15.
- **T** (int) - Defaults to 150.
- **alpha** (float) - Defaults to 1.
- **gamma** (float) - Defaults to 1.
- **eta** (float) - Defaults to 0.01.
- **scale** (float) - Defaults to 1.0.
- **var_converge** (float) - Defaults to 0.0001.
- **verbose** (bool) - Defaults to False.

### Methods
- **train()**: Trains the HDP model.
- **test(bow)**: Tests the model with a given bag-of-words.
- **get_beta()**: Retrieves the word distribution for topics.
- **get_top_words(num_top_words=None)**: Gets the top words for each topic.
- **export_theta()**: Exports the theta values.
```

--------------------------------

### Get Document Topic Distributions (HyperMiner)

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/hierarchical/HyperMiner/HyperMiner/index

Computes and returns the topic distribution (theta) for a given input document (x) using the HyperMiner model. This represents the mixture of topics present in the document.

```python
def get_theta(self, _x_):
    pass
```

--------------------------------

### Get List of Topic Factor Loading Matrices (HyperMiner)

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/models/hierarchical/HyperMiner/HyperMiner/index

Returns a list of factor loading matrices (phi) for each topic level, as computed by the HyperMiner model. This is useful for hierarchical topic analysis.

```python
def get_phi_list(self):
    pass
```

--------------------------------

### BasicTrainer Class

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/trainers/basic/basic_trainer/index

Details about the BasicTrainer class constructor and its parameters.

```APIDOC
## BasicTrainer Class

### Description
Represents a basic trainer for a model and dataset.

### Parameters
#### Constructor Parameters
- **model** (object) - Required - The model to be trained.
- **dataset** (object) - Required - The dataset to use for training.
- **num_top_words** (int) - Optional - The number of top words to consider. Defaults to 15.
- **epochs** (int) - Optional - The number of training epochs. Defaults to 200.
- **learning_rate** (float) - Optional - The learning rate for the optimizer. Defaults to 0.002.
- **batch_size** (int) - Optional - The batch size for training. Defaults to 200.
- **lr_scheduler** (object) - Optional - The learning rate scheduler. Defaults to None.
- **lr_step_size** (int) - Optional - The step size for the learning rate scheduler. Defaults to 125.
- **log_interval** (int) - Optional - The interval for logging training progress. Defaults to 5.
- **verbose** (bool) - Optional - Whether to enable verbose output. Defaults to False.

### Methods
- **make_optimizer()**: Creates the optimizer for the model.
- **make_lr_scheduler(optimizer)**: Creates the learning rate scheduler.
- **train()**: Trains the model.
- **test(bow)**: Tests the model with the given bag of words.
- **get_beta()**: Retrieves the beta values.
- **get_top_words(num_top_words=None)**: Retrieves the top words.
- **export_theta()**: Exports the theta values.
```

--------------------------------

### Get HyperMiner Factor Loading Matrix (phi)

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/models/hierarchical/HyperMiner/HyperMiner/index

Retrieves the factor loading matrix (phi) for the HyperMiner model. This method utilizes a sawtooth connection, as described in the NeurIPS 2022 paper associated with HyperMiner.

```python
def get_phi(self):
    """Returns the factor loading matrix by utilizing sawtooth connection."""
    pass
```

--------------------------------

### ProdLDA Class

Source: https://topmost.readthedocs.io/en/latest/_sources/autoapi/topmost/index

Documentation for the ProdLDA class, implementing Production-like Topic Models.

```APIDOC
## ProdLDA Class

### Description
Implements Autoencoding Variational Inference for Topic Models (ICLR 2017).

### Parameters
- **vocab_size** (int) - The size of the vocabulary.
- **num_topics** (int) - The number of topics to discover. Defaults to 50.
- **en_units** (int) - Number of units in the encoder. Defaults to 200.
- **dropout** (float) - Dropout rate. Defaults to 0.4.

### Attributes
- **num_topics** (int) - Defaults to 50.
- **a**
- **mu2**
- **var2**
- **fc11**
- **fc12**
- **fc21**
- **fc22**
- **mean_bn**
- **logvar_bn**
- **decoder_bn**
- **fc1_drop**
- **theta_drop**
- **fcd1**

### Methods
- **get_beta()**: Retrieves the word distribution for topics.
- **get_theta(x)**: Retrieves the topic distribution for a given input.
- **reparameterize(mu, logvar)**: Reparameterization trick for sampling.
- **encode(x)**: Encodes the input into a latent representation.
- **decode(theta)**: Decodes the latent representation.
- **forward(x)**: Forward pass of the model.
- **loss_function(x, recon_x, mu, logvar)**: Calculates the loss function.
```

--------------------------------

### Get Topic Groups

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/eva/hierarchy_quality/index

Organizes topics into groups based on a hierarchical topic dictionary and other parameters like beta list. This function is essential for structuring and analyzing related topics within a corpus.

```python
def get_topic_groups(_hierarchical_topic_dict_ , _topic_hierarchy_ , _beta_list_):
    """
    Get groups of topics.

    Parameters:
        hierarchical_topic_dict (dict): Dictionary representing hierarchical topics.
        topic_hierarchy (dict): The topic hierarchy structure.
        beta_list (list): List of beta values (topic proportions).

    Returns:
        Any: The organized topic groups.
    """
    pass
```

--------------------------------

### Download Preprocessed Dataset with TopMost

Source: https://topmost.readthedocs.io/en/latest/quick_start

Shows how to download a preprocessed dataset (e.g., '20NG') using the TopMost library, specifying a local cache path for storage.

```python
import topmost

topmost.download_dataset('20NG', cache_path='./datasets')

```

--------------------------------

### BERTopicTrainer Class Initialization and Methods

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/trainers/basic/BERTopic_trainer/index

Defines the BERTopicTrainer class with parameters for dataset, number of topics, and number of top words. Includes methods for training, testing, and retrieving model-specific data.

```python
class BERTopicTrainer(_dataset_, _num_topics=50_, _num_top_words=15_):
    """"""
    model
    dataset

    train()

    test(_texts_)

    get_beta()

    get_top_words()

    export_theta()
    """"""
```

--------------------------------

### BasicTrainer Data Retrieval Methods

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/trainers/basic/basic_trainer/index

Provides methods to retrieve specific information from the trained model. This includes functions to get the beta values, the top words based on a specified number, and to export the theta matrix.

```python
def get_beta(self):
    """Returns the beta values of the model."""
    pass

def get_top_words(self, _num_top_words=None):
    """Returns the top words from the model."""
    pass

def export_theta(self):
    """Exports the theta matrix of the model."""
    pass
```

--------------------------------

### Get Stopwords Set (Python)

Source: https://topmost.readthedocs.io/en/latest/autoapi/topmost/utils/_utils/index

Generates a set of stopwords, which are common words to be excluded from text analysis. It accepts an optional list of custom stopwords. The function returns a set data structure for efficient lookup.

```python
get_stopwords_set(_stopwords =[])
```
Tokens:
Raw