tmplot 0.2.0__tar.gz → 0.3.0__tar.gz

{tmplot-0.2.0/src/tmplot.egg-info → tmplot-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: tmplot
-Version: 0.2.0
+Version: 0.3.0
 Summary: Visualization of Topic Modeling Results
 Author-email: Maksim Terpilovskii <maximtrp@gmail.com>
 License: MIT License
@@ -55,6 +55,7 @@ Provides-Extra: models
 Requires-Dist: tomotopy>=0.8.0; extra == "models"
 Requires-Dist: gensim; extra == "models"
 Requires-Dist: bitermplus; extra == "models"
+Dynamic: license-file
 
 # tmplot
 
@@ -66,35 +67,46 @@ Requires-Dist: bitermplus; extra == "models"
 [![PyPI](https://img.shields.io/pypi/v/tmplot)](https://pypi.org/project/tmplot)
 [![Issues](https://img.shields.io/github/issues/maximtrp/tmplot.svg)](https://github.com/maximtrp/tmplot/issues)
 
-**tmplot** is a Python package for analysis and visualization of topic modeling results. It provides the interactive report interface that borrows much from LDAvis/pyLDAvis and builds upon it offering a number of metrics for calculating topic distances and a number of algorithms for calculating scatter coordinates of topics. It can be used to select closest and stable topics across multiple models.
+**tmplot** is a comprehensive Python package for **topic modeling analysis and visualization**. Built for data scientists and researchers, it provides powerful interactive reports and advanced analytics that extend beyond traditional LDAvis/pyLDAvis capabilities.
+
+**Analyze** • **Visualize** • **Compare** multiple topic models with ease
 
 ![Plots](https://raw.githubusercontent.com/maximtrp/tmplot/main/images/topics_terms_plots.png)
 
-## Features
+## Key Features
+
+### Interactive Visualization
+
+- **Topic scatter plots** with customizable coordinates and sizing
+- **Term probability charts** with relevance weighting
+- **Document analysis** showing top documents per topic
+- **Interactive reports** with real-time parameter adjustment
+
+### Advanced Analytics
 
-- Supported models:
+- **Topic stability analysis** across multiple model runs
+- **Model comparison** with sophisticated distance metrics
+- **Saliency calculations** for term importance
+- **Entropy metrics** for model optimization
 
-  - [tomotopy](https://bab2min.github.io/tomotopy/): `LDAModel`, `LLDAModel`, `CTModel`, `DMRModel`, `HDPModel`, `PTModel`, `SLDAModel`, `GDMRModel`
-  - [gensim](https://radimrehurek.com/gensim/): `LdaModel`, `LdaMulticore`
-  - [bitermplus](https://github.com/maximtrp/bitermplus): `BTM`
+### Model Support
 
-- Supported distance metrics:
+- **[tomotopy](https://bab2min.github.io/tomotopy/)**: `LDAModel`, `LLDAModel`, `CTModel`, `DMRModel`, `HDPModel`, `PTModel`, `SLDAModel`, `GDMRModel`
+- **[gensim](https://radimrehurek.com/gensim/)**: `LdaModel`, `LdaMulticore`
+- **[bitermplus](https://github.com/maximtrp/bitermplus)**: `BTM`
 
-  - Kullback-Leibler (symmetric and non-symmetric) divergence
-  - Jenson-Shannon divergence
-  - Jeffrey's divergence
-  - Hellinger distance
-  - Bhattacharyya distance
-  - Total variation distance
-  - Jaccard inversed index
+### Distance Metrics
 
-- Supported [algorithms](https://scikit-learn.org/stable/modules/classes.html#module-sklearn.manifold) for calculating topics scatter coordinates:
+- Kullback-Leibler (symmetric & non-symmetric)
+- Jensen-Shannon divergence
+- Jeffrey's divergence
+- Hellinger & Bhattacharyya distances
+- Total variation distance
+- Jaccard index
 
-  - t-SNE
-  - SpectralEmbedding
-  - MDS
-  - LocallyLinearEmbedding
-  - Isomap
+### Dimensionality Reduction
+
+t-SNE, SpectralEmbedding, MDS, LocallyLinearEmbedding, Isomap
 
 ## Donate
 
@@ -102,55 +114,77 @@ If you find this package useful, please consider donating any amount of money. T
 
 <a href="https://www.buymeacoffee.com/maximtrp" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
 
-## Installation
+## Quick Start
 
-The package can be installed from PyPi:
+### Installation
 
 ```bash
+# From PyPI (recommended)
 pip install tmplot
-```
-
-Or directly from this repository:
 
-```bash
+# Development version
 pip install git+https://github.com/maximtrp/tmplot.git
 ```
 
-## Dependencies
+### Basic Usage
+
+```python
+import tmplot as tmp
+
+# Load your topic model and documents
+model = your_fitted_model  # tomotopy, gensim, or bitermplus
+docs = your_documents
 
-- `numpy`
-- `scipy`
-- `scikit-learn`
-- `pandas`
-- `altair`
-- `ipywidgets`
-- `tomotopy`, `gensim`, and `bitermplus` (optional)
+# Create interactive report
+tmp.report(model, docs=docs)
 
-## Quick example
+# Or create individual visualizations
+coords = tmp.prepare_coords(model)
+tmp.plot_scatter_topics(coords, size_col='size')
+```
+
+## Advanced Examples
+
+### Get Stable Topics
 
 ```python
-# Importing packages
 import tmplot as tmp
-import pickle as pkl
-import pandas as pd
 
-# Reading a model from a file
-with open('data/model.pkl', 'rb') as file:
-    model = pkl.load(file)
+# Find stable topics across multiple models
+models = [model1, model2, model3, model4]
+closest_topics, distances = tmp.get_closest_topics(models)
+stable_topics, stable_distances = tmp.get_stable_topics(closest_topics, distances)
+```
+
+### Analyze Model
+
+```python
+# Calculate entropy for model selection
+entropy_score = tmp.entropy(phi_matrix)
 
-# Reading documents from a file
-docs = pd.read_csv('data/docs.txt.gz', header=None).values.ravel()
+# Analyze topic stability
+saliency = tmp.get_salient_terms(phi, theta)
+```
 
-# Plotting topics as a scatter plot
-topics_coords = tmp.prepare_coords(model)
-tmp.plot_scatter_topics(topics_coords, size_col='size', label_col='label')
+### Visualize
 
-# Plotting terms probabilities
-terms_probs = tmp.calc_terms_probs_ratio(phi, topic=0, lambda_=1)
-tmp.plot_terms(terms_probs)
+```python
+# Create topic distance matrix with different metrics
+topic_dists = tmp.get_topics_dist(phi, method='jensen-shannon')
 
-# Running report interface
-tmp.report(model, docs=docs, width=250)
+# Generate coordinates with custom algorithm
+coords = tmp.get_topics_scatter(topic_dists, theta, method='tsne')
+tmp.plot_scatter_topics(coords, topic=3)  # Highlight topic 3
 ```
 
-You can find more examples in the [tutorial](https://tmplot.readthedocs.io/en/latest/tutorial.html).
+## Documentation & Examples
+
+- [Complete Tutorial](https://tmplot.readthedocs.io/en/latest/tutorial.html) - Step-by-step guide
+- [API Reference](https://tmplot.readthedocs.io/) - Full documentation
+- [Example Notebooks](https://github.com/maximtrp/tmplot/tree/main/examples) - Jupyter examples
+
+## Requirements
+
+**Core dependencies:** `numpy`, `scipy`, `scikit-learn`, `pandas`, `altair`, `ipywidgets`
+
+**Optional models:** `tomotopy`, `gensim`, `bitermplus`

tmplot-0.3.0/README.md

@@ -0,0 +1,131 @@
+# tmplot
+
+[![Codacy coverage](https://img.shields.io/codacy/coverage/5939b1cf99bc4f9d91de11c0d3ff9e50)](https://app.codacy.com/gh/maximtrp/tmplot/coverage)
+[![Codacy grade](https://img.shields.io/codacy/grade/5939b1cf99bc4f9d91de11c0d3ff9e50)](https://app.codacy.com/gh/maximtrp/tmplot)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/maximtrp/tmplot/python-package.yml?label=tests)](https://github.com/maximtrp/tmplot/actions/workflows/python-package.yml)
+[![Documentation Status](https://readthedocs.org/projects/tmplot/badge/?version=latest)](https://tmplot.readthedocs.io/en/latest/?badge=latest)
+[![Downloads](https://static.pepy.tech/badge/tmplot)](https://pepy.tech/project/tmplot)
+[![PyPI](https://img.shields.io/pypi/v/tmplot)](https://pypi.org/project/tmplot)
+[![Issues](https://img.shields.io/github/issues/maximtrp/tmplot.svg)](https://github.com/maximtrp/tmplot/issues)
+
+**tmplot** is a comprehensive Python package for **topic modeling analysis and visualization**. Built for data scientists and researchers, it provides powerful interactive reports and advanced analytics that extend beyond traditional LDAvis/pyLDAvis capabilities.
+
+**Analyze** • **Visualize** • **Compare** multiple topic models with ease
+
+![Plots](https://raw.githubusercontent.com/maximtrp/tmplot/main/images/topics_terms_plots.png)
+
+## Key Features
+
+### Interactive Visualization
+
+- **Topic scatter plots** with customizable coordinates and sizing
+- **Term probability charts** with relevance weighting
+- **Document analysis** showing top documents per topic
+- **Interactive reports** with real-time parameter adjustment
+
+### Advanced Analytics
+
+- **Topic stability analysis** across multiple model runs
+- **Model comparison** with sophisticated distance metrics
+- **Saliency calculations** for term importance
+- **Entropy metrics** for model optimization
+
+### Model Support
+
+- **[tomotopy](https://bab2min.github.io/tomotopy/)**: `LDAModel`, `LLDAModel`, `CTModel`, `DMRModel`, `HDPModel`, `PTModel`, `SLDAModel`, `GDMRModel`
+- **[gensim](https://radimrehurek.com/gensim/)**: `LdaModel`, `LdaMulticore`
+- **[bitermplus](https://github.com/maximtrp/bitermplus)**: `BTM`
+
+### Distance Metrics
+
+- Kullback-Leibler (symmetric & non-symmetric)
+- Jensen-Shannon divergence
+- Jeffrey's divergence
+- Hellinger & Bhattacharyya distances
+- Total variation distance
+- Jaccard index
+
+### Dimensionality Reduction
+
+t-SNE, SpectralEmbedding, MDS, LocallyLinearEmbedding, Isomap
+
+## Donate
+
+If you find this package useful, please consider donating any amount of money. This will help me spend more time on supporting open-source software.
+
+<a href="https://www.buymeacoffee.com/maximtrp" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+## Quick Start
+
+### Installation
+
+```bash
+# From PyPI (recommended)
+pip install tmplot
+
+# Development version
+pip install git+https://github.com/maximtrp/tmplot.git
+```
+
+### Basic Usage
+
+```python
+import tmplot as tmp
+
+# Load your topic model and documents
+model = your_fitted_model  # tomotopy, gensim, or bitermplus
+docs = your_documents
+
+# Create interactive report
+tmp.report(model, docs=docs)
+
+# Or create individual visualizations
+coords = tmp.prepare_coords(model)
+tmp.plot_scatter_topics(coords, size_col='size')
+```
+
+## Advanced Examples
+
+### Get Stable Topics
+
+```python
+import tmplot as tmp
+
+# Find stable topics across multiple models
+models = [model1, model2, model3, model4]
+closest_topics, distances = tmp.get_closest_topics(models)
+stable_topics, stable_distances = tmp.get_stable_topics(closest_topics, distances)
+```
+
+### Analyze Model
+
+```python
+# Calculate entropy for model selection
+entropy_score = tmp.entropy(phi_matrix)
+
+# Analyze topic stability
+saliency = tmp.get_salient_terms(phi, theta)
+```
+
+### Visualize
+
+```python
+# Create topic distance matrix with different metrics
+topic_dists = tmp.get_topics_dist(phi, method='jensen-shannon')
+
+# Generate coordinates with custom algorithm
+coords = tmp.get_topics_scatter(topic_dists, theta, method='tsne')
+tmp.plot_scatter_topics(coords, topic=3)  # Highlight topic 3
+```
+
+## Documentation & Examples
+
+- [Complete Tutorial](https://tmplot.readthedocs.io/en/latest/tutorial.html) - Step-by-step guide
+- [API Reference](https://tmplot.readthedocs.io/) - Full documentation
+- [Example Notebooks](https://github.com/maximtrp/tmplot/tree/main/examples) - Jupyter examples
+
+## Requirements
+
+**Core dependencies:** `numpy`, `scipy`, `scikit-learn`, `pandas`, `altair`, `ipywidgets`
+
+**Optional models:** `tomotopy`, `gensim`, `bitermplus`

{tmplot-0.2.0 → tmplot-0.3.0}/src/tmplot/__init__.py

@@ -5,4 +5,4 @@ from ._stability import *  # noqa: F401, F403
 from ._vis import *  # noqa: F401, F403
 from ._metrics import *  # noqa: F401, F403
 
-__version__ = '0.2.0'
+__version__ = "0.3.0"

{tmplot-0.2.0 → tmplot-0.3.0}/src/tmplot/_distance.py

@@ -21,12 +21,13 @@ def _dist_klb(a1: np.ndarray, a2: np.ndarray):
 
 
 def _dist_sklb(a1: np.ndarray, a2: np.ndarray):
-    dist = kl_div(a1, a2) + kl_div(a1, a2)
+    dist = kl_div(a1, a2) + kl_div(a2, a1)
     return dist[np.isfinite(dist)].sum()
 
 
 def _dist_jsd(a1: np.ndarray, a2: np.ndarray):
-    dist = 0.5 * kl_div(a1, a2) + 0.5 * kl_div(a1, a2)
+    m = 0.5 * (a1 + a2)
+    dist = 0.5 * kl_div(a1, m) + 0.5 * kl_div(a2, m)
     return dist[np.isfinite(dist)].sum()
 
 
@@ -36,16 +37,22 @@ def _dist_jef(a1: np.ndarray, a2: np.ndarray):
     return vals.sum()
 
 
+# Small value for numerical stability
+EPSILON = 1e-64
+
+
 def _dist_hel(a1: np.ndarray, a2: np.ndarray):
-    a1[(a1 <= 0) | ~np.isfinite(a1)] = 1e-64
-    a2[(a2 <= 0) | ~np.isfinite(a2)] = 1e-64
-    hel_val = distance.euclidean(np.sqrt(a1), np.sqrt(a2)) / np.sqrt(2)
+    a1_safe = a1.copy()
+    a2_safe = a2.copy()
+    a1_safe[(a1_safe <= 0) | ~np.isfinite(a1_safe)] = EPSILON
+    a2_safe[(a2_safe <= 0) | ~np.isfinite(a2_safe)] = EPSILON
+    hel_val = distance.euclidean(np.sqrt(a1_safe), np.sqrt(a2_safe)) / np.sqrt(2)
     return hel_val
 
 
 def _dist_bhat(a1: np.ndarray, a2: np.ndarray):
     pq = a1 * a2
-    pq[(pq <= 0) | ~np.isfinite(pq)] = 1e-64
+    pq[(pq <= 0) | ~np.isfinite(pq)] = EPSILON
     dist = -np.log(np.sum(np.sqrt(pq)))
     return dist
 
@@ -92,6 +99,14 @@ def get_topics_dist(
         Topics distances matrix.
     """
     phi_copy = np.array(phi)
+
+    if phi_copy.ndim != 2:
+        raise ValueError("phi must be a 2D array (words x topics)")
+    if np.any(phi_copy < 0):
+        raise ValueError("phi must contain non-negative probability values")
+    if not np.allclose(phi_copy.sum(axis=0), 1.0, atol=1e-6):
+        raise ValueError("phi columns must sum to 1 (probability distributions)")
+
     topics_num = phi_copy.shape[1]
     topics_pairs = combinations(range(topics_num), 2)
 
@@ -165,6 +180,7 @@ def get_topics_scatter(
     elif method == "mds":
         method_kws.setdefault("dissimilarity", "precomputed")
         method_kws.setdefault("normalized_stress", "auto")
+        method_kws.setdefault("n_init", 1)
         transformer = MDS(**method_kws)
 
     elif method == "lle":

{tmplot-0.2.0 → tmplot-0.3.0}/src/tmplot/_helpers.py

@@ -156,6 +156,8 @@ def get_theta(model: object, corpus: Optional[List] = None) -> Optional[DataFram
     elif _is_gensim(model):
         if corpus is None:
             raise ValueError("`corpus` must be supplied for a gensim model")
+        if len(corpus) == 0:
+            raise ValueError("corpus cannot be empty")
         tdd = list(map(model.get_document_topics, corpus))
         theta = DataFrame(zeros((len(tdd), model.num_topics)))
         for doc_id, doc_topic in enumerate(tdd):
@@ -165,6 +167,8 @@ def get_theta(model: object, corpus: Optional[List] = None) -> Optional[DataFram
 
     elif _is_btmplus(model):
         theta = DataFrame(model.matrix_topics_docs_)
+    else:
+        raise ValueError(f"Unsupported model type: {type(model)}")
 
     if isinstance(theta, DataFrame):
         theta.index.name = "topics"
@@ -264,9 +268,19 @@ def calc_topics_marg_probs(
     Union[pandas.DataFrame, numpy.ndarray]
         Marginal topics probabilities.
     """
-    p_t = array(theta).sum(axis=1)
-    p_t /= p_t.sum()
+    theta_arr = array(theta)
+    if theta_arr.size == 0:
+        raise ValueError("theta matrix cannot be empty")
+
+    p_t = theta_arr.sum(axis=1)
+    total_sum = p_t.sum()
+    if total_sum == 0:
+        raise ValueError("theta matrix contains all zeros - cannot normalize")
+
+    p_t /= total_sum
     if topic_id is not None:
+        if topic_id < 0 or topic_id >= len(p_t):
+            raise IndexError(f"topic_id {topic_id} out of bounds for {len(p_t)} topics")
         return p_t[topic_id]
     return p_t
 
@@ -282,6 +296,8 @@ def calc_terms_marg_probs(
     ----------
     phi : Union[numpy.ndarray, pandas.DataFrame]
         Words vs topics matrix.
+    p_t : Union[numpy.ndarray, pandas.Series]
+        Topic marginal probabilities.
     word_id: Optional[int]
         Word index.
 
@@ -290,8 +306,20 @@ def calc_terms_marg_probs(
     Union[numpy.ndarray, pandas.Series]
         Marginal terms probabilities.
     """
-    p_w = (array(phi) * array(p_t)).sum(axis=1)
+    phi_arr = array(phi)
+    p_t_arr = array(p_t)
+
+    if phi_arr.size == 0:
+        raise ValueError("phi matrix cannot be empty")
+    if p_t_arr.size == 0:
+        raise ValueError("p_t array cannot be empty")
+    if phi_arr.shape[1] != p_t_arr.shape[0]:
+        raise ValueError(f"phi topics dimension {phi_arr.shape[1]} must match p_t length {p_t_arr.shape[0]}")
+
+    p_w = (phi_arr * p_t_arr).sum(axis=1)
     if word_id is not None:
+        if word_id < 0 or word_id >= len(p_w):
+            raise IndexError(f"word_id {word_id} out of bounds for {len(p_w)} words")
         return p_w[word_id]
     return p_w
 
@@ -315,10 +343,17 @@ def get_salient_terms(phi: ndarray, theta: ndarray) -> ndarray:
     numpy.ndarray
         Terms saliency values.
     """
+    if phi.size == 0 or theta.size == 0:
+        raise ValueError("phi and theta matrices cannot be empty")
+    if phi.shape[1] != theta.shape[0]:
+        raise ValueError(f"phi topics dimension {phi.shape[1]} must match theta topics dimension {theta.shape[0]}")
+
     p_t = calc_topics_marg_probs(theta)
     p_w = calc_terms_marg_probs(phi, p_t)
 
     def _p_tw(phi, w, t):
+        if p_w[w] == 0:
+            return 0  # Avoid division by zero
         return array(phi)[w, t] * p_t[t] / p_w[w]
 
     saliency = array(
@@ -327,6 +362,8 @@ def get_salient_terms(phi: ndarray, theta: ndarray) -> ndarray:
             * sum(
                 (
                     _p_tw(phi, w, t) * log(_p_tw(phi, w, t) / p_t[t])
+                    if _p_tw(phi, w, t) > 0 and p_t[t] > 0
+                    else 0  # Handle log(0) cases
                     for t in range(phi.shape[1])
                 )
             )

{tmplot-0.2.0 → tmplot-0.3.0}/src/tmplot/_report.py

@@ -105,6 +105,9 @@ def report(
     ipywidgets.widgets.widget_box.VBox
         Report interface as a VBox instance.
     """
+    # Input validation
+    if not docs or len(docs) == 0:
+        raise ValueError("docs cannot be empty")
 
     _topics_kws = (
         {"chart_kws": {"height": height, "width": width}}
@@ -117,7 +120,7 @@ def report(
         if not words_kws
         else deepcopy(words_kws)
     )
-    _top_docs_kws = {} if not docs_kws else deepcopy(top_docs_kws)
+    _top_docs_kws = {} if not top_docs_kws else deepcopy(top_docs_kws)
     _docs_kws = {} if not docs_kws else deepcopy(docs_kws)
 
     # Headers init
@@ -162,8 +165,10 @@ def report(
             }
         )
 
+    # Cache phi matrix to avoid repeated calls
+    phi = get_phi(model)
+
     if "terms_probs" not in _words_kws:
-        phi = get_phi(model)
         terms_probs = calc_terms_probs_ratio(phi, topic=0)
         _words_kws.update({"terms_probs": terms_probs})
 

{tmplot-0.2.0 → tmplot-0.3.0}/src/tmplot/_stability.py

@@ -106,6 +106,9 @@ def get_closest_topics(
         if mid == ref:
             continue
 
+        # Get phi matrix for current model
+        current_phi = get_phi(model)
+
         # Distance matrix for all topic pairs
         all_vs_all_dists = np.zeros((topics_num, topics_num))
 
@@ -113,7 +116,7 @@ def get_closest_topics(
         for t_ref in range(topics_num):
             for t in range(topics_num):
                 all_vs_all_dists[t_ref, t] = dist_func(
-                    model_ref_phi.iloc[:, t_ref], get_phi(model).iloc[:, t]
+                    model_ref_phi.iloc[:, t_ref], current_phi.iloc[:, t]
                 )
 
         # Creating two arrays for the closest topics ids and distance values

{tmplot-0.2.0 → tmplot-0.3.0}/src/tmplot/_vis.py

@@ -128,11 +128,15 @@ def plot_scatter_topics(
             else {"condition": {"test": f"datum['topic'] == {topic}", "value": "red"}}
         )
 
-    data = (
-        DataFrame(topics_coords, columns=[x_col, y_col])
-        if isinstance(topics_coords, ndarray)
-        else topics_coords.copy()
-    )
+    # Input validation
+    if isinstance(topics_coords, ndarray):
+        if topics_coords.size == 0:
+            raise ValueError("topics_coords cannot be empty")
+        data = DataFrame(topics_coords, columns=[x_col, y_col])
+    else:
+        if topics_coords.empty:
+            raise ValueError("topics_coords DataFrame cannot be empty")
+        data = topics_coords.copy()
 
     if not topic_col:
         topic_col = "topic"
@@ -225,6 +229,13 @@ def plot_terms(
     altair.Chart
         Terms probabilities chart.
     """
+    # Input validation
+    if terms_probs.empty:
+        raise ValueError("terms_probs DataFrame cannot be empty")
+    required_cols = [x_col, y_col, color_col]
+    missing_cols = [col for col in required_cols if col not in terms_probs.columns]
+    if missing_cols:
+        raise ValueError(f"Missing required columns: {missing_cols}")
     if not x_kws:
         x_kws = {"stack": None}
     if not y_kws:

{tmplot-0.2.0 → tmplot-0.3.0/src/tmplot.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: tmplot
-Version: 0.2.0
+Version: 0.3.0
 Summary: Visualization of Topic Modeling Results
 Author-email: Maksim Terpilovskii <maximtrp@gmail.com>
 License: MIT License
@@ -55,6 +55,7 @@ Provides-Extra: models
 Requires-Dist: tomotopy>=0.8.0; extra == "models"
 Requires-Dist: gensim; extra == "models"
 Requires-Dist: bitermplus; extra == "models"
+Dynamic: license-file
 
 # tmplot
 
@@ -66,35 +67,46 @@ Requires-Dist: bitermplus; extra == "models"
 [![PyPI](https://img.shields.io/pypi/v/tmplot)](https://pypi.org/project/tmplot)
 [![Issues](https://img.shields.io/github/issues/maximtrp/tmplot.svg)](https://github.com/maximtrp/tmplot/issues)
 
-**tmplot** is a Python package for analysis and visualization of topic modeling results. It provides the interactive report interface that borrows much from LDAvis/pyLDAvis and builds upon it offering a number of metrics for calculating topic distances and a number of algorithms for calculating scatter coordinates of topics. It can be used to select closest and stable topics across multiple models.
+**tmplot** is a comprehensive Python package for **topic modeling analysis and visualization**. Built for data scientists and researchers, it provides powerful interactive reports and advanced analytics that extend beyond traditional LDAvis/pyLDAvis capabilities.
+
+**Analyze** • **Visualize** • **Compare** multiple topic models with ease
 
 ![Plots](https://raw.githubusercontent.com/maximtrp/tmplot/main/images/topics_terms_plots.png)
 
-## Features
+## Key Features
+
+### Interactive Visualization
+
+- **Topic scatter plots** with customizable coordinates and sizing
+- **Term probability charts** with relevance weighting
+- **Document analysis** showing top documents per topic
+- **Interactive reports** with real-time parameter adjustment
+
+### Advanced Analytics
 
-- Supported models:
+- **Topic stability analysis** across multiple model runs
+- **Model comparison** with sophisticated distance metrics
+- **Saliency calculations** for term importance
+- **Entropy metrics** for model optimization
 
-  - [tomotopy](https://bab2min.github.io/tomotopy/): `LDAModel`, `LLDAModel`, `CTModel`, `DMRModel`, `HDPModel`, `PTModel`, `SLDAModel`, `GDMRModel`
-  - [gensim](https://radimrehurek.com/gensim/): `LdaModel`, `LdaMulticore`
-  - [bitermplus](https://github.com/maximtrp/bitermplus): `BTM`
+### Model Support
 
-- Supported distance metrics:
+- **[tomotopy](https://bab2min.github.io/tomotopy/)**: `LDAModel`, `LLDAModel`, `CTModel`, `DMRModel`, `HDPModel`, `PTModel`, `SLDAModel`, `GDMRModel`
+- **[gensim](https://radimrehurek.com/gensim/)**: `LdaModel`, `LdaMulticore`
+- **[bitermplus](https://github.com/maximtrp/bitermplus)**: `BTM`
 
-  - Kullback-Leibler (symmetric and non-symmetric) divergence
-  - Jenson-Shannon divergence
-  - Jeffrey's divergence
-  - Hellinger distance
-  - Bhattacharyya distance
-  - Total variation distance
-  - Jaccard inversed index
+### Distance Metrics
 
-- Supported [algorithms](https://scikit-learn.org/stable/modules/classes.html#module-sklearn.manifold) for calculating topics scatter coordinates:
+- Kullback-Leibler (symmetric & non-symmetric)
+- Jensen-Shannon divergence
+- Jeffrey's divergence
+- Hellinger & Bhattacharyya distances
+- Total variation distance
+- Jaccard index
 
-  - t-SNE
-  - SpectralEmbedding
-  - MDS
-  - LocallyLinearEmbedding
-  - Isomap
+### Dimensionality Reduction
+
+t-SNE, SpectralEmbedding, MDS, LocallyLinearEmbedding, Isomap
 
 ## Donate
 
@@ -102,55 +114,77 @@ If you find this package useful, please consider donating any amount of money. T
 
 <a href="https://www.buymeacoffee.com/maximtrp" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
 
-## Installation
+## Quick Start
 
-The package can be installed from PyPi:
+### Installation
 
 ```bash
+# From PyPI (recommended)
 pip install tmplot
-```
-
-Or directly from this repository:
 
-```bash
+# Development version
 pip install git+https://github.com/maximtrp/tmplot.git
 ```
 
-## Dependencies
+### Basic Usage
+
+```python
+import tmplot as tmp
+
+# Load your topic model and documents
+model = your_fitted_model  # tomotopy, gensim, or bitermplus
+docs = your_documents
 
-- `numpy`
-- `scipy`
-- `scikit-learn`
-- `pandas`
-- `altair`
-- `ipywidgets`
-- `tomotopy`, `gensim`, and `bitermplus` (optional)
+# Create interactive report
+tmp.report(model, docs=docs)
 
-## Quick example
+# Or create individual visualizations
+coords = tmp.prepare_coords(model)
+tmp.plot_scatter_topics(coords, size_col='size')
+```
+
+## Advanced Examples
+
+### Get Stable Topics
 
 ```python
-# Importing packages
 import tmplot as tmp
-import pickle as pkl
-import pandas as pd
 
-# Reading a model from a file
-with open('data/model.pkl', 'rb') as file:
-    model = pkl.load(file)
+# Find stable topics across multiple models
+models = [model1, model2, model3, model4]
+closest_topics, distances = tmp.get_closest_topics(models)
+stable_topics, stable_distances = tmp.get_stable_topics(closest_topics, distances)
+```
+
+### Analyze Model
+
+```python
+# Calculate entropy for model selection
+entropy_score = tmp.entropy(phi_matrix)
 
-# Reading documents from a file
-docs = pd.read_csv('data/docs.txt.gz', header=None).values.ravel()
+# Analyze topic stability
+saliency = tmp.get_salient_terms(phi, theta)
+```
 
-# Plotting topics as a scatter plot
-topics_coords = tmp.prepare_coords(model)
-tmp.plot_scatter_topics(topics_coords, size_col='size', label_col='label')
+### Visualize
 
-# Plotting terms probabilities
-terms_probs = tmp.calc_terms_probs_ratio(phi, topic=0, lambda_=1)
-tmp.plot_terms(terms_probs)
+```python
+# Create topic distance matrix with different metrics
+topic_dists = tmp.get_topics_dist(phi, method='jensen-shannon')
 
-# Running report interface
-tmp.report(model, docs=docs, width=250)
+# Generate coordinates with custom algorithm
+coords = tmp.get_topics_scatter(topic_dists, theta, method='tsne')
+tmp.plot_scatter_topics(coords, topic=3)  # Highlight topic 3
 ```
 
-You can find more examples in the [tutorial](https://tmplot.readthedocs.io/en/latest/tutorial.html).
+## Documentation & Examples
+
+- [Complete Tutorial](https://tmplot.readthedocs.io/en/latest/tutorial.html) - Step-by-step guide
+- [API Reference](https://tmplot.readthedocs.io/) - Full documentation
+- [Example Notebooks](https://github.com/maximtrp/tmplot/tree/main/examples) - Jupyter examples
+
+## Requirements
+
+**Core dependencies:** `numpy`, `scipy`, `scikit-learn`, `pandas`, `altair`, `ipywidgets`
+
+**Optional models:** `tomotopy`, `gensim`, `bitermplus`

tmplot-0.2.0/README.md

@@ -1,98 +0,0 @@
-# tmplot
-
-[![Codacy coverage](https://img.shields.io/codacy/coverage/5939b1cf99bc4f9d91de11c0d3ff9e50)](https://app.codacy.com/gh/maximtrp/tmplot/coverage)
-[![Codacy grade](https://img.shields.io/codacy/grade/5939b1cf99bc4f9d91de11c0d3ff9e50)](https://app.codacy.com/gh/maximtrp/tmplot)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/maximtrp/tmplot/python-package.yml?label=tests)](https://github.com/maximtrp/tmplot/actions/workflows/python-package.yml)
-[![Documentation Status](https://readthedocs.org/projects/tmplot/badge/?version=latest)](https://tmplot.readthedocs.io/en/latest/?badge=latest)
-[![Downloads](https://static.pepy.tech/badge/tmplot)](https://pepy.tech/project/tmplot)
-[![PyPI](https://img.shields.io/pypi/v/tmplot)](https://pypi.org/project/tmplot)
-[![Issues](https://img.shields.io/github/issues/maximtrp/tmplot.svg)](https://github.com/maximtrp/tmplot/issues)
-
-**tmplot** is a Python package for analysis and visualization of topic modeling results. It provides the interactive report interface that borrows much from LDAvis/pyLDAvis and builds upon it offering a number of metrics for calculating topic distances and a number of algorithms for calculating scatter coordinates of topics. It can be used to select closest and stable topics across multiple models.
-
-![Plots](https://raw.githubusercontent.com/maximtrp/tmplot/main/images/topics_terms_plots.png)
-
-## Features
-
-- Supported models:
-
-  - [tomotopy](https://bab2min.github.io/tomotopy/): `LDAModel`, `LLDAModel`, `CTModel`, `DMRModel`, `HDPModel`, `PTModel`, `SLDAModel`, `GDMRModel`
-  - [gensim](https://radimrehurek.com/gensim/): `LdaModel`, `LdaMulticore`
-  - [bitermplus](https://github.com/maximtrp/bitermplus): `BTM`
-
-- Supported distance metrics:
-
-  - Kullback-Leibler (symmetric and non-symmetric) divergence
-  - Jenson-Shannon divergence
-  - Jeffrey's divergence
-  - Hellinger distance
-  - Bhattacharyya distance
-  - Total variation distance
-  - Jaccard inversed index
-
-- Supported [algorithms](https://scikit-learn.org/stable/modules/classes.html#module-sklearn.manifold) for calculating topics scatter coordinates:
-
-  - t-SNE
-  - SpectralEmbedding
-  - MDS
-  - LocallyLinearEmbedding
-  - Isomap
-
-## Donate
-
-If you find this package useful, please consider donating any amount of money. This will help me spend more time on supporting open-source software.
-
-<a href="https://www.buymeacoffee.com/maximtrp" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
-
-## Installation
-
-The package can be installed from PyPi:
-
-```bash
-pip install tmplot
-```
-
-Or directly from this repository:
-
-```bash
-pip install git+https://github.com/maximtrp/tmplot.git
-```
-
-## Dependencies
-
-- `numpy`
-- `scipy`
-- `scikit-learn`
-- `pandas`
-- `altair`
-- `ipywidgets`
-- `tomotopy`, `gensim`, and `bitermplus` (optional)
-
-## Quick example
-
-```python
-# Importing packages
-import tmplot as tmp
-import pickle as pkl
-import pandas as pd
-
-# Reading a model from a file
-with open('data/model.pkl', 'rb') as file:
-    model = pkl.load(file)
-
-# Reading documents from a file
-docs = pd.read_csv('data/docs.txt.gz', header=None).values.ravel()
-
-# Plotting topics as a scatter plot
-topics_coords = tmp.prepare_coords(model)
-tmp.plot_scatter_topics(topics_coords, size_col='size', label_col='label')
-
-# Plotting terms probabilities
-terms_probs = tmp.calc_terms_probs_ratio(phi, topic=0, lambda_=1)
-tmp.plot_terms(terms_probs)
-
-# Running report interface
-tmp.report(model, docs=docs, width=250)
-```
-
-You can find more examples in the [tutorial](https://tmplot.readthedocs.io/en/latest/tutorial.html).