event2vector 0.5.0

Interpretable, composable embeddings for sequences of discrete events.

event2vec.com · Paper · Changelog · Issues

What it is

Event2Vector learns one vector per event type and represents a whole sequence as the composition of its events. In the default Euclidean geometry that composition is a plain sum, so a sequence's embedding is exactly the sum of its events' vectors. This makes the representation interpretable by construction:

• Decomposition: every coordinate of a sequence is attributable to the events in it.
• Composition: sub-sequences combine by vector arithmetic.
• Counterfactuals: removing an event from a sequence is one subtraction.

Other geometries (hyperbolic, spherical, rotation, Heisenberg, affine, product) keep this compositional structure while capturing hierarchy, cycles or order. All of them sit behind one scikit-learn-style estimator.

Installation

pip install event2vector

From source:

git clone https://github.com/sulcantonin/event2vec_public.git
cd event2vec_public
pip install .

Requires Python 3.9+ and PyTorch 1.13+.

Quickstart

Sequences are lists of integer event ids (0 … num_event_types - 1) and can have different lengths.

import numpy as np
from event2vector import Event2Vec

vocab = ["start", "login", "search", "buy", "logout"]
sequences = [[0, 1, 2, 3, 4], [0, 1, 2, 2, 4], [0, 2, 3, 4], [0, 1, 4]] * 50

model = Event2Vec(
    num_event_types=len(vocab),
    embedding_dim=8,
    geometry="euclidean",
    pad_sequences=True,   # vectorized batches of variable-length sequences
    num_epochs=20,
    random_state=0,
)
model.fit(sequences)

embeddings = model.transform(sequences)          # (n_sequences, 8)

# A sequence is exactly the sum of its event vectors:
event_vectors = model.model.embedding.weight.detach().cpu().numpy()
assert np.allclose(embeddings[0], event_vectors[sequences[0]].sum(axis=0), atol=1e-5)

# gensim-style nearest events to an event or a whole sequence
print(model.most_similar(positive=3, topn=2))           # [(event_id, similarity), ...]
print(model.most_similar(positive=[[0, 1, 2]], topn=2))

How it works

A sequence is read one event at a time. The state starts at the identity and each event updates it, h_t = h_{t-1} ⊕ e_t, where ⊕ is the geometry's composition (vector addition in the Euclidean case). Training minimizes three terms at every step:

There is no attention and no hidden nonlinearity in the state update, which is what keeps every embedding a readable composition of its events. See the paper for details.

Geometries

Choose the composition with geometry=. Every geometry uses the same estimator and, apart from euclidean, a generic left-cancellation reconstruction loss.

The same three events composed by each geometry, in order a·b·c (blue) and c·b·a (red). The Euclidean sum ends in the same place either way; where the endpoints separate, the geometry remembers order. Drawn by the library's own model classes with python images/make_readme_figures.py.

Event2Vec(num_event_types=len(vocab), geometry="hyperbolic", curvature=1.0)
Event2Vec(num_event_types=len(vocab), geometry="stereographic", kappa=-1.0)
Event2Vec(num_event_types=len(vocab), geometry="rotation", rotation_n=3)
Event2Vec(num_event_types=len(vocab), geometry="product", product_kappas=(-1.0, 1.0))

Hyperbolic embeddings live in the Poincaré ball; use the matching operations on them:

from event2vector import HyperbolicUtils

hyp = Event2Vec(num_event_types=len(vocab), geometry="hyperbolic", curvature=1.0,
                pad_sequences=True, num_epochs=20).fit(sequences)
z = hyp.transform(sequences, as_numpy=False)
combined = HyperbolicUtils.mobius_add(z[0:1], z[1:2], hyp.curvature)
distance = HyperbolicUtils.poincare_dist_sq(z[0:1], z[1:2], hyp.curvature).sqrt()

Affine geometry

In the additive geometries an event always pushes the state the same way. With geometry="affine" each event is an invertible affine map x ↦ exp(M_e) x + v_e, so the same event contributes differently depending on what came before, while the model remains a group:

• with every M_e = 0 (the initialization) the result is exactly the Euclidean sum, so training starts from the additive model;
• every step is invertible, and the reconstruction loss recovers it exactly;
• any sub-sequence composes into a single affine map, so its effect on any history is one A x + v.

The state is the whole map [vec(A), b]; the point to plot is b, the image of the origin. The singular values of a sub-sequence's A measure how strongly it overrides what came before: 1 passes the history through, values below 1 erase it along that direction.

aff = Event2Vec(num_event_types=len(vocab), geometry="affine", embedding_dim=2,
                pad_sequences=True, num_epochs=20).fit(sequences)

states = aff.transform(sequences, as_numpy=False)   # [vec(A), b] per sequence
points = aff.model.point(states)                    # (n_sequences, 2), ready to plot

A, v = aff.model.compose([1, 2, 3])                 # one map for a sub-sequence
print(aff.model.override_strength([1, 2, 3]))       # its singular values

affine_readout="full" lets the decoder read A as well as b, and affine_max_log_scale bounds how strongly a single event can stretch or shrink the state.

API reference

Event2Vec parameters

Methods

The underlying PyTorch module is model.model (event vectors in model.model.embedding.weight).

Root-cause analysis

In the Euclidean geometry the state is an exact weighted sum of the event embeddings, h_T = Σ_i w_i e_{s_i}, and the decoder is linear. The weights w_i are the products of the later norm-clipping factors (all 1 with max_norm=None), so recent events weigh more once clipping fires. Each prediction therefore splits exactly into per-event terms, which the methods above expose:

est = Event2Vec(num_event_types=len(vocab), pad_sequences=True).fit(sequences)

out = est.attribute(history, target=vocab["job_loss"])
out["bias"] + out["contributions"].sum()   # equals out["logit"]: one term per event

est.counterfactual(history, remove=[2])["delta"]   # change in next-event probabilities
A = est.influence_matrix()                         # (V, V) event -> next-event influence
est.event_impact()                                 # one score per event
est.decompose(history, round_counts=True)          # which events a state contains
est.explain_difference(failing_run, healthy_run)   # +: more in the failing run

event2vector.metrics.transition_graph_auc(est, graph, vocab) scores influence_matrix() against a known transition graph (ROC AUC over all ordered event pairs), e.g. make_lifepath()["graph"].

These methods explain the model's predictions. They reflect associations learned from the data, not causal effects, and the sum-based ones cannot tell event orders apart when clipping does not fire.

Devices

By default the estimator uses CUDA, then Apple MPS, then the CPU. On Apple Silicon the rotation and affine geometries default to the CPU, because MPS has no matrix_exp kernel and the CPU is faster for them; pass device="mps" to override. Use use_gpu=False to force the CPU, or device="cuda:0" to pick a device.

Datasets, metrics and baselines

The package ships domains with exact ground truth for the additive structure, so interpretability can be measured rather than only visualized. Datasets live in event2vector.datasets and return a uniform record (sequences, processed_sequences, vocab, labels, graph):

• make_decay(): radioactive decay chains; each event is an exact (ΔZ, ΔN), so additivity coincides with conservation laws (metric: operator_recovery).
• make_group(name): Cayley-graph walks on abelian and non-abelian groups; the additive endpoint provably equals the abelianization (metric: abelianization_gap).
• make_lifepath(), load_brown(): a controlled synthetic workbench and real part-of-speech sequences.
• load_gdelt(), load_sec_8k(), load_synthea(), …: real-world event streams (each needs a public data download; see the loader's docstring).

Metrics are in event2vector.metrics, a seeded evaluation harness in event2vector.eval, and GRU / LSTM / Transformer / Word2Vec baselines in event2vector.baselines.

Examples

A minimal end-to-end run (loss, embeddings, nearest events):

python3 examples/minimal_example.py

Part-of-speech sequences from the Brown corpus (the scripts need a few extra packages: NLTK for the corpus, t-SNE and Word2Vec for the comparison plots):

pip install "event2vector[viz,manifold,nlp]" nltk
python3 -m examples.prepare_brown_data
python3 -m examples.train_brown_data
python3 -m examples.visualize_brown_corpus

Applications:

• The Geometry of Groceries
• The Geometry of Language Families

Development

pip install -e . pytest
pytest tests/ -q

Changes are listed in CHANGELOG.md. Bug reports and questions are welcome in the issue tracker.

Citation

If you use Event2Vector, please cite the paper, published in the Proceedings of Machine Learning Research (vol. 282, NeurIPS Workshops on Symmetry and Geometry in Neural Representations):

@InProceedings{pmlr-v282-sulc26a,
  title     = {Event2Vec: A Geometric Approach to Learning Composable Representations of Event Sequences},
  author    = {Sulc, Antonin},
  booktitle = {Proceedings of the 4th (2025) and 3rd (2024) NeurIPS Workshops on Symmetry and Geometry in Neural Representations},
  pages     = {492--512},
  year      = {2026},
  editor    = {Acosta, Francisco and Azeglio, Simone and Tolooshams, Bahareh and van de Geijn, Chase and Shewmake, Christian and Sanborn, Sophia and Miolane, Nina},
  volume    = {282},
  series    = {Proceedings of Machine Learning Research},
  publisher = {PMLR},
  url       = {https://proceedings.mlr.press/v282/sulc26a.html}
}

A preprint is on arXiv:2509.12188.

To cite the software itself, use its Zenodo DOI 10.5281/zenodo.23399003, which always resolves to the latest version (each release also has its own DOI). GitHub's "Cite this repository" button reads the same metadata from CITATION.cff.

License

MIT. See the license badge above.