Skip to content

Add visualize_representative_images for image-only topic models#2521

Open
Gsebs wants to merge 1 commit into
MaartenGr:masterfrom
Gsebs:feat/2236-visualize-representative-images
Open

Add visualize_representative_images for image-only topic models#2521
Gsebs wants to merge 1 commit into
MaartenGr:masterfrom
Gsebs:feat/2236-visualize-representative-images

Conversation

@Gsebs

@Gsebs Gsebs commented Jul 10, 2026

Copy link
Copy Markdown

What does this PR do?

Implements the approach discussed in #2236: a Plotly visualization that steps through each topic's representative-image collage (as created by VisualRepresentation) with a slider, at readable resolution — using only existing dependencies (plotly + numpy; no dash, no backend switch, no custom HTML/CSS), as preferred in that thread.

topic_model.visualize_representative_images()

The slider selects a topic; the title subtitle updates to the selected topic's label and the topic's collage is shown at its original resolution.

How it's structured

Follows the existing plotting conventions:

  • standalone function in bertopic/plotting/_images.py, re-exported in bertopic.plotting
  • thin delegating method BERTopic.visualize_representative_images() (placed after visualize_documents)
  • API docs page (docs/api/plotting/representative_images.md) + mkdocs nav entry
  • short usage note in the multimodal docs, next to the existing base64/HTML-table example
  • supports topics= subsetting, custom_labels (bool or aspect name), and a configurable aspect name (default "Visual_Aspect")

Tests

tests/test_plotting/test_images.py mirrors the existing plotting-test idioms (parametrized over the fitted-model fixtures). Since the test extra doesn't include vision/PIL, tests inject numpy-array images into topic_aspects_ — the function consumes anything np.asarray accepts, so real PIL collages work identically.

Verified locally:

  • full test suite green on unmodified master first (273 passed), then 70/70 plotting tests (63 existing + 7 new) with this change
  • pre-commit (ruff format/check, whitespace, yaml) clean
  • figure behavior verified in a real browser: initial trace visibility, slider steps, and per-step title/visibility updates

Happy to rename the function or adjust scope however you prefer, @MaartenGr — and I can attach a demo HTML if helpful.

Fixes #2236

Adds a Plotly-based visualization that steps through each topic's
representative-image collage (as created by VisualRepresentation) with
a slider, at readable resolution. Mirrors the structure of the other
plotting functions: standalone function in bertopic/plotting/_images.py,
re-exported in the plotting namespace, and a thin delegating method on
BERTopic. Uses only existing dependencies (plotly + numpy).

Implements the approach discussed in MaartenGr#2236.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Better Topic Modeling Visualization/Saving for Image Only Analysis

1 participant