chronowords

Detect semantic shifts over time in word embeddings. Train small PPMI-based language models, create topic models using NMF, and analyze semantic changes using Procrustes alignment.

Features

• Memory-efficient word embedding training using Count-Min Sketch
• Topic modeling with Non-negative Matrix Factorization
• Temporal alignment of word embeddings using Procrustes analysis
• Cython-optimized PPMI matrix computation

Installation

pip install chronowords

Quick Start

from chronowords.algebra import SVDAlgebra
from chronowords.topics import TopicModel

# Train word embeddings on any iterable of text lines
# (a list, a generator, or an open file).
model = SVDAlgebra(n_components=300)
with open("corpus.txt", encoding="utf-8") as fh:
    model.train(fh)

# Find similar words
for hit in model.most_similar("computer", n=10):
    print(f"{hit.word}: {hit.similarity:.3f}")

# Topic model over the PPMI matrix that train() computed
topic_model = TopicModel(n_topics=10)
topic_model.fit(model._ppmi_sparse, model.vocabulary)
topic_model.print_topics()

See the quickstart for a complete runnable example and the tutorial for detecting semantic shift across time slices.

Links

• Documentation: https://chronowords.readthedocs.io/en/latest/
• PyPI: https://pypi.org/project/chronowords/

Requirements

Python ≥ 3.10 NumPy SciPy scikit-learn Cython

Roadmap / further work

The following are known limitations and improvements not yet addressed. They are documented in PRE-MORTEM.md (fragility analysis) and CHANGES_SUMMARY.md.

• Robustness / error reporting
  • CountMinSketch.estimate_error currently ignores its confidence argument (the result depends only on width and total) — decide the intended bound and honour the parameter.
  • Narrow the broad except Exception blocks in SVDAlgebra.train (the silent, noise-injecting dense-SVD fallback) and TopicModel._compute_topic_similarity (returns 0.0 on any failure) so real errors surface; log when a fallback fires.
  • Add a zero-norm guard to ProcrustesAligner.get_word_similarity (it can return nan today).
• Input validation — validate constructor and train/fit inputs (array shapes, positive counts, n_components / n_topics ranges) so invalid input fails early with a clear message instead of an opaque NumPy/scikit-learn error.
• Configurability — promote the hard-coded minimum-count threshold (> 5) in the PPMI kernel to a named constant / parameter.
• Determinism — seed the dense-SVD fallback so embeddings are reproducible.
• Tooling — wire mutation testing into CI (needs src-layout configuration for mutmut, or an alternative such as cosmic-ray).
• Coverage — extend property-based and mutation testing to the Cython PPMI kernel and the NMF topic-alignment path.

Contributing

Pull requests welcome. For major changes, open an issue first.

License

MIT

Made by

Built and maintained by Crow Intelligence.