easy-detm 0.1.1__tar.gz

easy_detm-0.1.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jm Su
+Portions copyright (c) 2021 Adji Bousso Dieng, Francisco Ruiz, David Blei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

easy_detm-0.1.1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.1
+Name: easy-detm
+Version: 0.1.1
+Summary: A simple, easy-to-use toolkit for Dynamic Embedded Topic Models on temporal document collections.
+Author: Jm Su
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.7.0
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: scipy>=1.5.0
+Requires-Dist: pandas>=1.1.0
+Requires-Dist: scikit-learn>=0.23.0
+Requires-Dist: matplotlib>=3.3.0
+Requires-Dist: seaborn>=0.11.0
+Requires-Dist: umap-learn>=0.5.0
+Requires-Dist: plotly>=5.0.0
+Requires-Dist: scienceplots>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=20.0; extra == "dev"
+Requires-Dist: flake8>=3.8; extra == "dev"
+
+# easy-detm Package Document
+
+## Package Scope
+
+This package provides a Python interface for training and visualizing the Dynamic
+Embedded Topic Model (DETM).
+
+The current data API is intentionally simple:
+
+```python
+documents: List[str]
+timestamps: List[int]
+```
+
+
+## Main API
+
+### Model
+
+```python
+from easy_detm import DETMModel
+```
+
+`DETMModel` is the high-level class for:
+
+- creating the DETM model,
+- fitting it to temporal documents,
+- extracting topics,
+- inferring document-topic distributions,
+- saving and loading checkpoints,
+- evaluating topic coherence and topic diversity.
+
+### Data
+
+```python
+from easy_detm.data import create_dataset_from_list, DocumentCorpus
+```
+
+Use `create_dataset_from_list()` for most workflows. Use `DocumentCorpus` only
+when you need to manually control train/validation/test splits.
+
+### Visualization
+
+```python
+from easy_detm import (
+    configure_cjk_fonts,
+    visualize_embeddings,
+    visualize_embeddings_over_time,
+    visualize_topic_evolution,
+)
+```
+
+Visualization functions use the learned model parameters. They do not retrain or
+modify the model. `configure_cjk_fonts()` is called automatically by the
+visualization module and can also be called manually to inspect or reset CJK font
+support for Korean, Japanese, Chinese, and English labels.
+
+### Topic Metrics
+
+```python
+diversity = model.get_topic_diversity(num_words=10)
+coherence = model.get_topic_coherence(data=train, num_words=10)
+```
+
+`get_topic_diversity()` uses only the trained topic-word distributions.
+`get_topic_coherence()` also needs a reference corpus in DETM format, usually
+the training split. If you call it on a model restored with `load()`, pass
+`data=train` because checkpoints store model parameters and vocabulary, not the
+original corpus.
+
+
+## Input Requirements
+
+### Documents
+
+Documents should be strings where tokens are separated by whitespace:
+
+```python
+documents = [
+    "climate carbon emissions",
+    "trade market finance",
+]
+```
+
+The current package does not perform advanced NLP preprocessing. Recommended
+preprocessing before calling the package:
+
+- lowercase text,
+- remove or normalize punctuation,
+- remove domain-specific noise,
+- tokenize consistently,
+- optionally remove stopwords,
+- optionally lemmatize or stem terms.
+
+### Timestamps
+
+Timestamps should be integers:
+
+```python
+timestamps = [0, 0, 1, 1, 2, 2]
+```
+
+Recommended convention:
+
+- use zero-based indices,
+- keep time IDs contiguous,
+- make sure every document has one timestamp.
+
+## Hyperparameter Notes
+
+
+Important parameters:
+
+- `num_topics`: number of topics.
+- `num_times`: number of time periods.
+- `rho_size`: topic embedding dimension.
+- `emb_size`: word embedding dimension.
+- `t_hidden_size`: hidden size for the theta encoder.
+- `eta_hidden_size`: hidden size for the eta LSTM.
+- `eta_nlayers`: number of LSTM layers for eta.
+- `delta`: random-walk prior variance used by the original DETM implementation.
+- `enc_drop`: dropout in the theta encoder.
+- `batch_size`: minibatch size.
+- `learning_rate`: optimizer learning rate.
+
+## Output Interpretation
+
+### Topics
+
+`model.get_topics()` returns top words from the learned topic-word distributions.
+Because DETM is dynamic, each topic can have different top words at different
+time points.
+
+### Document-Topic Matrix
+
+`model.get_document_topics()` returns an array with shape:
+
+```text
+num_documents x num_topics
+```
+
+Each row is a topic-proportion vector for one input document.
+
+### Visualizations
+
+- Embedding plots show topics and words in a shared 2D projection.
+- Topic evolution plots show word probability changes over time for one topic.
+
+## Acknowledgements
+
+The core DETM model implementation is adapted from the original DETM code by
+Adji Bousso Dieng, Francisco J. R. Ruiz, and David M. Blei:
+https://github.com/adjidieng/DETM
+
+Please cite the original paper when using the DETM model:
+"The Dynamic Embedded Topic Model" (Dieng, Ruiz, and Blei, 2019).

easy_detm-0.1.1/README.md

@@ -0,0 +1,156 @@
+# easy-detm Package Document
+
+## Package Scope
+
+This package provides a Python interface for training and visualizing the Dynamic
+Embedded Topic Model (DETM).
+
+The current data API is intentionally simple:
+
+```python
+documents: List[str]
+timestamps: List[int]
+```
+
+
+## Main API
+
+### Model
+
+```python
+from easy_detm import DETMModel
+```
+
+`DETMModel` is the high-level class for:
+
+- creating the DETM model,
+- fitting it to temporal documents,
+- extracting topics,
+- inferring document-topic distributions,
+- saving and loading checkpoints,
+- evaluating topic coherence and topic diversity.
+
+### Data
+
+```python
+from easy_detm.data import create_dataset_from_list, DocumentCorpus
+```
+
+Use `create_dataset_from_list()` for most workflows. Use `DocumentCorpus` only
+when you need to manually control train/validation/test splits.
+
+### Visualization
+
+```python
+from easy_detm import (
+    configure_cjk_fonts,
+    visualize_embeddings,
+    visualize_embeddings_over_time,
+    visualize_topic_evolution,
+)
+```
+
+Visualization functions use the learned model parameters. They do not retrain or
+modify the model. `configure_cjk_fonts()` is called automatically by the
+visualization module and can also be called manually to inspect or reset CJK font
+support for Korean, Japanese, Chinese, and English labels.
+
+### Topic Metrics
+
+```python
+diversity = model.get_topic_diversity(num_words=10)
+coherence = model.get_topic_coherence(data=train, num_words=10)
+```
+
+`get_topic_diversity()` uses only the trained topic-word distributions.
+`get_topic_coherence()` also needs a reference corpus in DETM format, usually
+the training split. If you call it on a model restored with `load()`, pass
+`data=train` because checkpoints store model parameters and vocabulary, not the
+original corpus.
+
+
+## Input Requirements
+
+### Documents
+
+Documents should be strings where tokens are separated by whitespace:
+
+```python
+documents = [
+    "climate carbon emissions",
+    "trade market finance",
+]
+```
+
+The current package does not perform advanced NLP preprocessing. Recommended
+preprocessing before calling the package:
+
+- lowercase text,
+- remove or normalize punctuation,
+- remove domain-specific noise,
+- tokenize consistently,
+- optionally remove stopwords,
+- optionally lemmatize or stem terms.
+
+### Timestamps
+
+Timestamps should be integers:
+
+```python
+timestamps = [0, 0, 1, 1, 2, 2]
+```
+
+Recommended convention:
+
+- use zero-based indices,
+- keep time IDs contiguous,
+- make sure every document has one timestamp.
+
+## Hyperparameter Notes
+
+
+Important parameters:
+
+- `num_topics`: number of topics.
+- `num_times`: number of time periods.
+- `rho_size`: topic embedding dimension.
+- `emb_size`: word embedding dimension.
+- `t_hidden_size`: hidden size for the theta encoder.
+- `eta_hidden_size`: hidden size for the eta LSTM.
+- `eta_nlayers`: number of LSTM layers for eta.
+- `delta`: random-walk prior variance used by the original DETM implementation.
+- `enc_drop`: dropout in the theta encoder.
+- `batch_size`: minibatch size.
+- `learning_rate`: optimizer learning rate.
+
+## Output Interpretation
+
+### Topics
+
+`model.get_topics()` returns top words from the learned topic-word distributions.
+Because DETM is dynamic, each topic can have different top words at different
+time points.
+
+### Document-Topic Matrix
+
+`model.get_document_topics()` returns an array with shape:
+
+```text
+num_documents x num_topics
+```
+
+Each row is a topic-proportion vector for one input document.
+
+### Visualizations
+
+- Embedding plots show topics and words in a shared 2D projection.
+- Topic evolution plots show word probability changes over time for one topic.
+
+## Acknowledgements
+
+The core DETM model implementation is adapted from the original DETM code by
+Adji Bousso Dieng, Francisco J. R. Ruiz, and David M. Blei:
+https://github.com/adjidieng/DETM
+
+Please cite the original paper when using the DETM model:
+"The Dynamic Embedded Topic Model" (Dieng, Ruiz, and Blei, 2019).

easy_detm-0.1.1/easy_detm/__init__.py

@@ -0,0 +1,40 @@
+"""Dynamic Embedded Topic Model (DETM) package.
+
+This package provides a high-level API for training and using Dynamic Embedded
+Topic Models on temporal document collections.
+
+Example:
+    >>> from easy_detm import DETMModel
+    >>> from easy_detm.data import create_dataset_from_list
+    >>>
+    >>> vocab, train, valid, test = create_dataset_from_list(documents, timestamps)
+    >>> model = DETMModel(num_topics=50, vocab=vocab, num_times=len(set(timestamps)))
+    >>> model.fit(train, valid, test_data=test, epochs=100)
+    >>> topics = model.get_topics(num_words=10)
+"""
+
+from .detm_wrapper import DETMModel
+from .model import DETM
+from .utils import get_topic_coherence, get_topic_diversity
+from .visualization import (
+    configure_cjk_fonts,
+    visualize_embeddings,
+    visualize_embeddings_over_time,
+    visualize_topic_evolution,
+    plot_topic_sankey,
+    plot_topic_sankey_individual
+)
+
+__version__ = '0.1.1'
+__all__ = [
+    'DETMModel',
+    'DETM',
+    'get_topic_coherence',
+    'get_topic_diversity',
+    'configure_cjk_fonts',
+    'visualize_embeddings',
+    'visualize_embeddings_over_time',
+    'visualize_topic_evolution',
+    'plot_topic_sankey',
+    'plot_topic_sankey_individual'
+]

easy_detm-0.1.1/easy_detm/data/__init__.py

@@ -0,0 +1,29 @@
+"""Simplified data loading module for DETM.
+
+This module provides a simple interface for loading data from Python lists.
+
+Main entry point:
+    create_dataset_from_list() - Create dataset from list of documents and timestamps
+
+Example:
+    >>> from easy_detm.data import create_dataset_from_list
+    >>>
+    >>> # Your raw data
+    >>> documents = ["doc 1", "doc 2", "doc 3", ...]
+    >>> timestamps = [0, 0, 1, 1, 2, ...]
+    >>>
+    >>> # Create dataset (auto-splits and builds vocab)
+    >>> vocab, train, valid, test = create_dataset_from_list(documents, timestamps)
+    >>>
+    >>> # Use with model
+    >>> from easy_detm import DETMModel
+    >>> model = DETMModel(vocab_size=len(vocab), num_topics=10, num_times=len(set(timestamps)))
+    >>> model.fit(train, valid, epochs=100)
+"""
+
+from .loaders import create_dataset_from_list, DocumentCorpus
+
+__all__ = [
+    'create_dataset_from_list',
+    'DocumentCorpus',
+]