MaartenGr / MaartenGr/BERTopic

Align Logger Output with Documented Pipeline

Open
#2,192 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
7.8k
Forks
920
Avg merge
22h 24m
Merged PRs (30d)
5

Description

### Feature request

Following some reflection based on a [closed PR](https://github.com/MaartenGr/BERTopic/pull/2180#issuecomment-2425958936), I want to suggest a change in the logger.info messages to align with the documentation and modular pipeline of the library.

Context: In the current implementation, the code's logging verbosity reflects a simplified version of the pipeline:

Embeddings -> Dim. Red. -> Clustering -> Representation

However, in the documentation and associated research papers, the pipeline is presented with more detailed later stages:

Embeddings -> Dim. Red. -> Clustering -> Bag of Words (vectorizer + c-TF-IDF) -> Fine Tuning Representations

This mismatch between the actual implementation steps and the documented process can create confusion, especially for non-CS researchers (like myself) or contributors who rely on logging to understand the modularity and steps of the implementation.

Problem Description:

There’s ambiguity in the logging related to the term “Representation,” which might be interpreted differently depending on the pipeline step.

The pipeline section involving the c-TF-IDF is currently not logged at all, despite being a core part of the pipeline.

The logging output skips from:
```
BERTopic - Cluster- Clustering the reduced embeddings.
BERTopic - Cluster - Completed ✓
BERTopic - Representation - Extracting topics from clusters using representation models.
BERTopic - Representation - Completed ✓
```

**Proposed Solution:** To better reflect the detailed process, I propose to align it with the current documentation. A more detailed logging flow might look like:

```
Embeddings - Transforming documents to embeddings.
Dim. Red. - Fitting the dimensionality reduction algorithm.
Clusterc- Clustering the reduced embeddings.
Bag of Words - Calculating c-TF-IDF (Vectorizer could be added here also)
Base Representation - Extracting top-n words per topic from c-TF-IDF
Fine Tuning Representation - Fine-tuning topics using representation models.
Fine Tuning Representation - Calculating different aspects.
```

Conceptual Clarification: It also comes to play that some concepts are still ambiguous an can be approached differently. For example, the definition of “topic” can be seen in two ways:

- As the clustering output, where documents are grouped and assigned a topic ID (but there are no topic keywords defined).
- At the end of the c-TF-IDF step, where top-n-keywords provide a more concrete representation or “definition” of each topic.

As such, the statement of "extracting topics from" is not a precise term, so I would avoid it in this new scheme, unless there is a clear cut point where topics are "defined".

Given that the c-TF-IDF step plays a foundational role in refining topic representations, I suggest treating it as a separate and essential component in the pipeline and reflecting this in the logger output.

### Motivation

I want to improve this library, since I will probably be using during my research (already used it for a paper).

### Your contribution

I can implement the solution, if agreed. I will probably start doing so for my own purposes, so a commit id will be available here for observation/comments when done.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the logger.info messages for the Embeddings, Dim. Red., Clustering, and Representation stages, then compare them with the documented pipeline described in the issue. Resolve the stage names and ordering before changing the output. Done means the logs separately and consistently reflect c-TF-IDF, base representation, fine-tuning, and aspects without the current ambiguity.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
machine-learning
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.