MuSTDrifter

Multi-Source Temporal Drifter

Unsupervised multidimensional discourse drift detection in Python.

---

Overview

MuSTDrifter is a Python framework for quantifying how discourse evolves over time through multidimensional data drift analysis.

The framework models discourse evolution across:

• Semantic dimensions
• Lexical dimensions
• Syntactic content
• Syntactic style
• Thematic distributions

and estimates temporal drift using complementary forms of:

• Covariate shift detection
• Prior probability shift detection

---

Features

• Multidimensional discourse representations
• Multiple drift metrics
• Permutation-based significance estimation
• Parallelized drift computation
• Automatic heatmap reporting
• Modular architecture
• Reproducible analysis pipelines

---

Installation

Requires Python 3.12+.

git clone https://github.com/oeg-upm/mustdrifter.git
cd mustdrifter
poetry install

---

Quick Example

import pandas as pd

from mustdrifter import MuSTDrifter

df = pd.DataFrame({
    "doc_id": [1, 2, 3],
    "content": [
        "Political text A",
        "Political text B",
        "Political text C",
    ],
    "period_id": [1, 1, 2]
})

drifter = MuSTDrifter(
    df=df,
    df_name="example",
    results_path="./results",
)

# Generate discourse representations
drifter.generate_drift_dimensions()

# Compute multidimensional drift
drifter.calculate_drift()

# Generate heatmaps
drifter.report_heatmaps(
    export=True,
    aggregate_by="dimension"
)

---

Documentation

Full documentation is available here.

Including:

• Installation
• Quickstart
• API Reference
• Drift metrics
• Reporting utilities

---

Drift Dimensions

Dimension	Description
Semantic	Embedding distribution drift
Lexical	Content-word lemma drift
Syntactic Content	POS-rule structural drift
Syntactic Style	Conditional POS transition drift
Thematic	Topic distribution drift

---

Drift Metrics

Semantic Drift

• Maximum Mean Discrepancy (MMD)
• Cosine Drift
• Kolmogorov–Smirnov (KS)

Lexical, Syntactic, and Thematic Drift

• Jensen–Shannon Divergence (JS)
• Kullback–Leibler Divergence (KL)
• Log-Likelihood divergence

---

Citation

TBD

---

License

Creative Commons Attribution 4.0 International License

---

Author

Ibai Guillén Pacho