event2vector 0.4.1__tar.gz → 0.5.0__tar.gz

{event2vector-0.4.1 → event2vector-0.5.0}/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to `event2vector` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-10-21
+
+The Euclidean model gets a reconstruction objective that acts on whole histories
+and a set of root-cause analysis methods built on the exact decomposition of its
+state. Other geometries are unchanged; the API is backward compatible.
+
+### Added
+
+- Root-cause analysis methods on `Event2Vec`: `attribute` (exact per-event
+  logit contributions for Euclidean, leave-one-out otherwise), `counterfactual`,
+  `influence_matrix`, `event_impact`, and for Euclidean `decompose` and
+  `explain_difference` (event counts recovered from states by non-negative least
+  squares).
+- `metrics.transition_graph_auc`, which scores the influence matrix against a
+  known transition graph.
+- `lambda_difference` (experimental, off by default): a difference-reconstruction
+  term for the Euclidean model. Random pairs of histories in a padded batch must
+  have a state difference that decodes (with the same scale-invariant form) to
+  the events that differ. In our experiments it lowers the reconstruction error
+  and improves the decoding of sums, but does not improve the decoding of
+  differences; it is kept as an option for further work.
+- `max_norm=None` disables the Euclidean norm clipping, so the state is the exact
+  sum of its events.
+
+### Changed
+
+- The Euclidean reconstruction loss is upgraded to a history-level objective.
+  It reconstructs the normalized event histogram `c/n` of each history from its
+  additive embedding `Eᵀ c/n`, with the event-embedding matrix as a tied decoder:
+  `‖α* E Eᵀ c/n − c/n‖²`, where `α* = ⟨E Eᵀ c, c⟩ / ‖E Eᵀ c‖²` is the
+  closed-form best scale (no trainable parameter), so the loss does not compete
+  with prediction for the embedding norm. The embedding is rebuilt without dropout
+  or clipping so the gradient reaches `E`. The previous step-level term
+  `‖(h_t − e_t) − h_{t-1}‖²` is satisfied by construction of the additive update
+  (it acted only when `max_norm` clipping fired). The other geometries are
+  unchanged.
+
+### Fixed
+
+- An infinite `max_norm` previously produced NaN gradients (`0 · inf` in the
+  backward pass of the clip).
+
 ## [0.4.1] - 2026-10-15
 
 Documentation and metadata only; the code is unchanged from 0.4.0.

{event2vector-0.4.1 → event2vector-0.5.0}/CITATION.cff

@@ -5,9 +5,9 @@ type: software
 authors:
   - family-names: Sulc
     given-names: Antonin
-version: 0.4.1
+version: 0.5.0
 doi: 10.5281/zenodo.23399003
-date-released: 2026-10-15
+date-released: 2026-10-20
 license: MIT
 repository-code: "https://github.com/sulcantonin/event2vec_public"
 url: "https://event2vec.com"

{event2vector-0.4.1/event2vector.egg-info → event2vector-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: event2vector
-Version: 0.4.1
+Version: 0.5.0
 Summary: Scikit-learn-style geometric embeddings for event sequences.
 Author: Antonin Sulc
 License-Expression: MIT
@@ -18,6 +18,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: numpy>=1.21
 Requires-Dist: torch>=1.13
 Requires-Dist: scikit-learn>=1.0
+Requires-Dist: scipy>=1.5
 Requires-Dist: tqdm>=4.0
 Provides-Extra: viz
 Requires-Dist: matplotlib; extra == "viz"
@@ -131,7 +132,7 @@ step:
 | term | weight | what it enforces |
 |---|---|---|
 | next-event prediction | 1 | a linear decoder predicts event `t+1` from `h_t` (cross-entropy) |
-| reconstruction | `lambda_reconstruction` | the step `e_t` can be recovered from `h_{t-1}` and `h_t`, so the update stays invertible |
+| reconstruction | `lambda_reconstruction` | Euclidean: the history's event counts can be read back from its embedding with the tied decoder `E`, `‖α* E Eᵀ c/n − c/n‖²` with the closed-form best scale `α*`, so it does not fix the embedding norm; other geometries: the step `e_t` is recovered from `h_{t-1}` and `h_t` |
 | consistency | `lambda_consistency` | two dropout passes over the same step agree |
 
 There is no attention and no hidden nonlinearity in the state update, which is
@@ -141,7 +142,7 @@ what keeps every embedding a readable composition of its events. See the
 ## Geometries
 
 Choose the composition with `geometry=`. Every geometry uses the same estimator
-and a generic left-cancellation reconstruction loss.
+and, apart from `euclidean`, a generic left-cancellation reconstruction loss.
 
 | `geometry` | update | best for |
 |---|---|---|
@@ -230,9 +231,10 @@ the state.
 | `affine_max_log_scale` | `None` | bound on how much one event can stretch the `affine` state |
 | `product_kappas` | `(-1.0, 1.0)` | one curvature per factor for `product` |
 | `dropout_p` | `0.2` | dropout on each step's increment |
-| `max_norm` | `10.0` | norm clipping of the Euclidean state |
+| `max_norm` | `10.0` | norm clipping of the Euclidean state; `None` disables it, so the state is the exact sum of its events |
 | `lambda_reconstruction` | `0.2` | weight of the reconstruction loss |
 | `lambda_consistency` | `0.2` | weight of the consistency loss |
+| `lambda_difference` | `0.0` | weight of the difference-reconstruction loss (Euclidean, needs `pad_sequences=True`): the difference of two histories' states must decode to the events that differ |
 | `learning_rate` | `1e-3` | AdamW learning rate |
 | `batch_size` | `32` | sequences per batch |
 | `num_epochs` | `50` | training epochs |
@@ -250,10 +252,52 @@ the state.
 | `transform(sequences, as_numpy=True)` | one state per sequence (NumPy array or tensor) |
 | `fit_transform(sequences, ...)` | `fit`, then `transform` on the same sequences |
 | `most_similar(positive, negative=None, topn=10)` | nearest event ids to events or whole sequences, with similarities |
+| `attribute(sequence, target=None)` | each event's contribution to the logit of the next event `target` |
+| `counterfactual(sequence, remove)` | next-event probabilities with and without the events at positions `remove` |
+| `influence_matrix()` | `A[j, i]`: how much event `i` alone raises the logit of next event `j` |
+| `event_impact()` | how strongly one occurrence of each event moves the next-event distribution |
+| `decompose(sequence_or_state)` | event counts recovered from a state vector (Euclidean) |
+| `explain_difference(sequence_a, sequence_b)` | signed counts of the events that differ, read from the two states (Euclidean) |
 
 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:
+
+```python
+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
+```
+
+| method | geometries | exact when |
+|---|---|---|
+| `attribute` | all | Euclidean: always (the terms sum to the logit). Others: leave-one-out differences, which do not sum to the logit |
+| `counterfactual` | all | always (the edited sequence is re-encoded) |
+| `influence_matrix`, `event_impact` | all | Euclidean with `max_norm=None`: `A = W_dec Eᵀ` and every sequence's logits are `bias + A @ counts` |
+| `decompose`, `explain_difference` | Euclidean | `max_norm=None` and few enough distinct events for the embeddings to separate them; with clipping they estimate the clip-weighted counts |
+
+`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

{event2vector-0.4.1 → event2vector-0.5.0}/README.md

@@ -96,7 +96,7 @@ step:
 | term | weight | what it enforces |
 |---|---|---|
 | next-event prediction | 1 | a linear decoder predicts event `t+1` from `h_t` (cross-entropy) |
-| reconstruction | `lambda_reconstruction` | the step `e_t` can be recovered from `h_{t-1}` and `h_t`, so the update stays invertible |
+| reconstruction | `lambda_reconstruction` | Euclidean: the history's event counts can be read back from its embedding with the tied decoder `E`, `‖α* E Eᵀ c/n − c/n‖²` with the closed-form best scale `α*`, so it does not fix the embedding norm; other geometries: the step `e_t` is recovered from `h_{t-1}` and `h_t` |
 | consistency | `lambda_consistency` | two dropout passes over the same step agree |
 
 There is no attention and no hidden nonlinearity in the state update, which is
@@ -106,7 +106,7 @@ what keeps every embedding a readable composition of its events. See the
 ## Geometries
 
 Choose the composition with `geometry=`. Every geometry uses the same estimator
-and a generic left-cancellation reconstruction loss.
+and, apart from `euclidean`, a generic left-cancellation reconstruction loss.
 
 | `geometry` | update | best for |
 |---|---|---|
@@ -195,9 +195,10 @@ the state.
 | `affine_max_log_scale` | `None` | bound on how much one event can stretch the `affine` state |
 | `product_kappas` | `(-1.0, 1.0)` | one curvature per factor for `product` |
 | `dropout_p` | `0.2` | dropout on each step's increment |
-| `max_norm` | `10.0` | norm clipping of the Euclidean state |
+| `max_norm` | `10.0` | norm clipping of the Euclidean state; `None` disables it, so the state is the exact sum of its events |
 | `lambda_reconstruction` | `0.2` | weight of the reconstruction loss |
 | `lambda_consistency` | `0.2` | weight of the consistency loss |
+| `lambda_difference` | `0.0` | weight of the difference-reconstruction loss (Euclidean, needs `pad_sequences=True`): the difference of two histories' states must decode to the events that differ |
 | `learning_rate` | `1e-3` | AdamW learning rate |
 | `batch_size` | `32` | sequences per batch |
 | `num_epochs` | `50` | training epochs |
@@ -215,10 +216,52 @@ the state.
 | `transform(sequences, as_numpy=True)` | one state per sequence (NumPy array or tensor) |
 | `fit_transform(sequences, ...)` | `fit`, then `transform` on the same sequences |
 | `most_similar(positive, negative=None, topn=10)` | nearest event ids to events or whole sequences, with similarities |
+| `attribute(sequence, target=None)` | each event's contribution to the logit of the next event `target` |
+| `counterfactual(sequence, remove)` | next-event probabilities with and without the events at positions `remove` |
+| `influence_matrix()` | `A[j, i]`: how much event `i` alone raises the logit of next event `j` |
+| `event_impact()` | how strongly one occurrence of each event moves the next-event distribution |
+| `decompose(sequence_or_state)` | event counts recovered from a state vector (Euclidean) |
+| `explain_difference(sequence_a, sequence_b)` | signed counts of the events that differ, read from the two states (Euclidean) |
 
 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:
+
+```python
+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
+```
+
+| method | geometries | exact when |
+|---|---|---|
+| `attribute` | all | Euclidean: always (the terms sum to the logit). Others: leave-one-out differences, which do not sum to the logit |
+| `counterfactual` | all | always (the edited sequence is re-encoded) |
+| `influence_matrix`, `event_impact` | all | Euclidean with `max_norm=None`: `A = W_dec Eᵀ` and every sequence's logits are `bias + A @ counts` |
+| `decompose`, `explain_difference` | Euclidean | `max_norm=None` and few enough distinct events for the embeddings to separate them; with clipping they estimate the clip-weighted counts |
+
+`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

{event2vector-0.4.1 → event2vector-0.5.0}/event2vector/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.4.1"
+__version__ = "0.5.0"
 
 from .models import EuclideanModel, HyperbolicModel, HyperbolicUtils, Event2Vec
 from .geometries import (

{event2vector-0.4.1 → event2vector-0.5.0}/event2vector/metrics.py

@@ -459,3 +459,39 @@ def abelianization_gap(estimator, record, seed: int = 0, probe: str = "mlp") ->
         "n_abelian": record["n_abelian"],
         "is_abelian": record["is_abelian"],
     }
+
+
+# --------------------------------------------------------------------------- #
+# Root-cause analysis — does the influence matrix expose the generating graph?
+# --------------------------------------------------------------------------- #
+def transition_graph_auc(estimator, graph: dict, vocab: dict, influence=None) -> dict:
+    """Score the estimator's influence matrix against a known transition graph.
+
+    ``graph`` maps an event name to its successors, ``{name: [(next, prob), ...]}``
+    (as in ``make_lifepath()["graph"]``) and ``vocab`` maps names to event ids.
+    Every ordered pair ``i != j`` is a candidate edge ``i -> j`` scored by
+    ``A[j, i]`` from ``estimator.influence_matrix()`` (or the given ``influence``);
+    the true edges are the positives.
+
+    Returns ``auc`` (ROC AUC), ``average_precision``, ``n_edges`` and
+    ``n_pairs``. 0.5 AUC is chance.
+    """
+    from sklearn.metrics import average_precision_score, roc_auc_score
+
+    A = estimator.influence_matrix() if influence is None else np.asarray(influence)
+    V = A.shape[0]
+    truth = np.zeros((V, V), dtype=bool)  # truth[j, i]: edge i -> j
+    for src, succ in graph.items():
+        if src not in vocab:
+            continue
+        for dst, _ in succ:
+            if dst in vocab:
+                truth[vocab[dst], vocab[src]] = True
+    off = ~np.eye(V, dtype=bool)
+    y, s = truth[off], A[off]
+    return {
+        "auc": float(roc_auc_score(y, s)),
+        "average_precision": float(average_precision_score(y, s)),
+        "n_edges": int(y.sum()),
+        "n_pairs": int(y.size),
+    }

{event2vector-0.4.1 → event2vector-0.5.0}/event2vector/models.py

@@ -56,7 +56,9 @@ class EuclideanModel(nn.Module):
         e = self.dropout(self.embedding(x))
         h_next = e + h
 
-        if clipping:
+        # max_norm=None (or inf) disables clipping, keeping h_t an exact sum; an
+        # infinite coefficient would otherwise turn the gradient into 0 * inf = NaN.
+        if clipping and self.max_norm is not None and self.max_norm != float("inf"):
             norm = torch.norm(h_next, p=2, dim=1, keepdim=True)
             clip_coef = self.max_norm / (norm + 1e-6)
             clip_coef = torch.min(clip_coef, torch.ones_like(clip_coef))
@@ -69,8 +71,7 @@ class EuclideanModel(nn.Module):
 
     def forward(self, x, h=None):
         # Returns (logits, next_state, increment). `increment` is the vector
-        # actually added at this step (post-dropout), i.e. the quantity the
-        # reconstruction loss must be able to invert.
+        # actually added at this step (post-dropout).
         h, e = self.encoder(x, h)
         return self.decoder(h), h, e
 
@@ -179,6 +180,22 @@ class HyperbolicModel(nn.Module):
 SequenceType = Union[torch.Tensor, Sequence[int]]
 
 
+def _nonnegative_lstsq(A, b):
+    """``argmin_{x >= 0} ||A x - b||``.
+
+    The active-set NNLS returns a sparse minimizer, which is what decoding event
+    counts needs when ``A`` has more columns than rows. Its default iteration cap
+    (3x the columns) is too small for some embeddings, so it gets a larger one and,
+    if that still fails, falls back to bounded-variable least squares.
+    """
+    from scipy.optimize import lsq_linear, nnls
+
+    try:
+        return nnls(A, b, maxiter=50 * A.shape[1])[0]
+    except RuntimeError:
+        return lsq_linear(A, b, bounds=(0.0, np.inf), method="bvls").x
+
+
 class Event2Vec:
     """
     High-level estimator that follows the fit/transform conventions of scikit-learn
@@ -202,6 +219,7 @@ class Event2Vec:
         product_kappas: Sequence[float] = (-1.0, 1.0),
         lambda_reconstruction: float = 0.2,
         lambda_consistency: float = 0.2,
+        lambda_difference: float = 0.0,
         learning_rate: float = 1e-3,
         batch_size: int = 32,
         num_epochs: int = 50,
@@ -240,6 +258,7 @@ class Event2Vec:
         self.product_kappas = tuple(product_kappas)
         self.lambda_reconstruction = lambda_reconstruction
         self.lambda_consistency = lambda_consistency
+        self.lambda_difference = lambda_difference
         self.learning_rate = learning_rate
         self.batch_size = batch_size
         self.num_epochs = num_epochs
@@ -582,6 +601,186 @@ class Event2Vec:
             values, indices = torch.topk(sims, k=k)
         return [(idx.item(), float(val)) for idx, val in zip(indices, values)]
 
+    # ------------------------------------------------------------------ #
+    # Root-cause analysis
+    #
+    # For the Euclidean geometry the state is a (clip-weighted) sum of event
+    # embeddings and the decoder is linear, so every quantity below is an exact
+    # decomposition of the model's own logits. For the other geometries the
+    # generic methods fall back to re-encoding (leave-one-out / forward passes),
+    # which is exact for the model but not additive. All of them explain the
+    # model's predictions; they are associations learned from data, not causal
+    # effects.
+    # ------------------------------------------------------------------ #
+    def _as_ids(self, sequence: SequenceType) -> List[int]:
+        if isinstance(sequence, torch.Tensor):
+            sequence = sequence.tolist()
+        return [int(i) for i in sequence]
+
+    def _next_logits(self, sequence: SequenceType) -> torch.Tensor:
+        """Decoder logits for the event following ``sequence`` (dropout off)."""
+        ids = self._as_ids(sequence)
+        was_training = self.model.training
+        self.model.eval()
+        with torch.no_grad():
+            h = self.model.zero_state(1, self.device)
+            logits = self.model.decoder(h)
+            for i in ids:
+                logits, h, _ = self.model(torch.tensor([i], device=self.device), h)
+        if was_training:
+            self.model.train()
+        return logits[0]
+
+    def _clip_weights(self, ids: List[int]) -> torch.Tensor:
+        """Euclidean weights ``w_i`` with ``h_T = sum_i w_i e_{s_i}`` exactly.
+
+        Step ``k`` scales ``h_{k-1} + e_k`` by ``gamma_k = min(1, max_norm / ||.||)``,
+        so ``w_i = prod_{k >= i} gamma_k``; all ones when clipping never fires.
+        """
+        E = self.model.embedding.weight.detach()
+        max_norm = self.model.max_norm
+        h = torch.zeros(E.shape[1], device=E.device)
+        gammas = []
+        for i in ids:
+            v = h + E[i]
+            gamma = 1.0
+            if max_norm is not None and max_norm != float("inf"):
+                gamma = min(1.0, max_norm / (v.norm().item() + 1e-6))
+            gammas.append(gamma)
+            h = v * gamma
+        g = torch.tensor(gammas, device=E.device)
+        return torch.flip(torch.cumprod(torch.flip(g, [0]), 0), [0])
+
+    def _require_euclidean(self, method: str):
+        if self.geometry != "euclidean":
+            raise NotImplementedError(
+                f"{method} needs the state to be a sum of event embeddings, which only "
+                "holds for geometry='euclidean'."
+            )
+
+    def attribute(self, sequence: SequenceType, target: Optional[int] = None) -> dict:
+        """Contribution of each event in ``sequence`` to the logit of the next event ``target``.
+
+        ``target`` defaults to the most likely next event. Euclidean: the logit is
+        decomposed exactly, ``logit = bias + sum_i contributions[i]`` with
+        ``contributions[i] = weights[i] * (W_dec e_{s_i})[target]``, where ``weights``
+        are the norm-clipping weights (all ones with ``max_norm=None``), so recent
+        events weigh more when clipping fires. Other geometries: leave-one-out,
+        ``contributions[i] = logit(sequence) - logit(sequence without position i)``,
+        which does not sum to the logit.
+
+        Returns a dict with ``target``, ``logit``, ``contributions`` (one per
+        position), ``weights`` (Euclidean only, else ``None``), ``bias`` and
+        ``exact`` (whether the contributions sum to ``logit - bias``).
+        """
+        self._check_is_fitted()
+        ids = self._as_ids(sequence)
+        if not ids:
+            raise ValueError("sequence must be non-empty.")
+        logits = self._next_logits(ids)
+        if target is None:
+            target = int(logits.argmax())
+        logit = float(logits[target])
+        if self.geometry == "euclidean":
+            E = self.model.embedding.weight.detach()
+            W = self.model.linear_dec.weight.detach()
+            b = self.model.linear_dec.bias.detach()
+            weights = self._clip_weights(ids)
+            contributions = weights * (E[ids] @ W[target])
+            return {
+                "target": target,
+                "logit": logit,
+                "contributions": contributions.cpu().numpy(),
+                "weights": weights.cpu().numpy(),
+                "bias": float(b[target]) if b is not None else 0.0,
+                "exact": True,
+            }
+        contributions = np.array([
+            logit - float(self._next_logits(ids[:i] + ids[i + 1:])[target])
+            for i in range(len(ids))
+        ])
+        return {"target": target, "logit": logit, "contributions": contributions,
+                "weights": None, "bias": None, "exact": False}
+
+    def counterfactual(self, sequence: SequenceType, remove: Union[int, Sequence[int]]) -> dict:
+        """Next-event distribution with and without the events at positions ``remove``.
+
+        Re-encodes the edited sequence, so it is exact for every geometry. Returns
+        ``probs`` (factual), ``probs_counterfactual`` and ``delta`` (their
+        difference), each of length ``num_event_types``.
+        """
+        self._check_is_fitted()
+        ids = self._as_ids(sequence)
+        drop = {remove} if isinstance(remove, int) else set(remove)
+        kept = [i for p, i in enumerate(ids) if p not in drop]
+        p = torch.softmax(self._next_logits(ids), dim=0).cpu().numpy()
+        q = torch.softmax(self._next_logits(kept), dim=0).cpu().numpy()
+        return {"probs": p, "probs_counterfactual": q, "delta": q - p}
+
+    def influence_matrix(self) -> np.ndarray:
+        """``A[j, i]``: change in the logit of next event ``j`` caused by event ``i``
+        alone, ``A[j, i] = logit_j([i]) - logit_j([])``.
+
+        Euclidean without clipping this is exactly ``W_dec E^T``, and every
+        sequence's logits are ``bias + sum_i count_i A[:, i]``; with clipping it is
+        the single-event effect. Shape ``(num_event_types, num_event_types)``.
+        """
+        self._check_is_fitted()
+        base = self._next_logits([])
+        cols = [self._next_logits([i]) - base for i in range(self.num_event_types)]
+        return torch.stack(cols, dim=1).cpu().numpy()
+
+    def event_impact(self) -> np.ndarray:
+        """How strongly one occurrence of each event moves the next-event
+        distribution: the norm of its centered influence column
+        ``||A[:, i] - mean(A[:, i])||`` (centering removes the softmax-invariant
+        shift). Shape ``(num_event_types,)``.
+        """
+        A = self.influence_matrix()
+        return np.linalg.norm(A - A.mean(axis=0, keepdims=True), axis=0)
+
+    def decompose(self, item: Union[SequenceType, torch.Tensor], round_counts: bool = False) -> np.ndarray:
+        """Recover event counts from a Euclidean state by non-negative least squares,
+        ``min_{x >= 0} ||E^T x - h||``.
+
+        ``item`` is a sequence (encoded first) or a state vector. Without clipping
+        the true counts are the unique solution whenever the history is short
+        enough relative to the coherence of the embeddings; with clipping the
+        result estimates the clip-weighted counts. ``round_counts`` rounds to
+        integers. Shape ``(num_event_types,)``.
+        """
+        self._check_is_fitted()
+        self._require_euclidean("decompose")
+        h = self._state_of(item)
+        E = self.model.embedding.weight.detach().cpu().double().numpy()
+        x = _nonnegative_lstsq(E.T, h)
+        return np.round(x) if round_counts else x
+
+    def explain_difference(self, sequence_a: SequenceType, sequence_b: SequenceType,
+                           round_counts: bool = False) -> np.ndarray:
+        """Which events differ between two histories, read from their states alone.
+
+        Decodes ``h_a - h_b`` into signed counts (positive: more in ``a``) by
+        non-negative least squares on ``[E^T, -E^T]``. Without clipping
+        ``h_a - h_b = E^T (c_a - c_b)`` exactly, so a failing run can be compared
+        with a healthy one. Shape ``(num_event_types,)``.
+        """
+        self._check_is_fitted()
+        self._require_euclidean("explain_difference")
+        d = self._state_of(sequence_a) - self._state_of(sequence_b)
+        E = self.model.embedding.weight.detach().cpu().double().numpy()
+        x = _nonnegative_lstsq(np.concatenate([E.T, -E.T], axis=1), d)
+        diff = x[: self.num_event_types] - x[self.num_event_types:]
+        return np.round(diff) if round_counts else diff
+
+    def _state_of(self, item) -> np.ndarray:
+        if isinstance(item, torch.Tensor) and item.dtype.is_floating_point:
+            return item.detach().cpu().double().numpy()
+        if isinstance(item, np.ndarray) and np.issubdtype(item.dtype, np.floating):
+            return item.astype(np.float64)
+        ids = self._as_ids(item)
+        return self.transform([ids], as_numpy=True)[0].astype(np.float64)
+
     def _standardize_sequences(
         self, sequences: Iterable[SequenceType]
     ) -> List[torch.Tensor]:
@@ -598,12 +797,74 @@ class Event2Vec:
             raise ValueError("At least one sequence is required.")
         return processed
 
-    def _compute_losses(self, y1, h1, e_curr1, h_old, target, h2):
+    def _history_reconstruction_loss(self, counts):
+        """Euclidean event-history reconstruction ``||alpha* E E^T c / n - c / n||^2``.
+
+        ``counts`` is a ``(B, V)`` histogram of the events in each row's history
+        and ``n`` its length. The history embedding ``h = E^T c / n`` is rebuilt
+        from the counts (no dropout, no clipping, not detached) and decoded with
+        the same embedding matrix, so the gradient reaches ``E`` through both the
+        encoder and the decoder. Rows with an empty history are excluded; the
+        result is the mean over the remaining rows.
+
+        ``alpha* = <E E^T c, c> / ||E E^T c||^2`` is the closed-form best scale
+        per row (no trainable parameter). It makes the loss invariant to the scale
+        of ``E``, so it scores only how well the embedding preserves the histogram
+        and does not pin the embedding norm (``||c||^2 sin^2`` of the angle between
+        ``E E^T c`` and ``c``).
+        """
+        n = counts.sum(dim=1, keepdim=True)
+        valid = n.squeeze(1) > 0
+        if not torch.any(valid):
+            return counts.new_zeros(())
+        c = counts[valid] / n[valid]
+        E = self.model.embedding.weight
+        c_hat = (c @ E) @ E.t()
+        alpha = (c_hat * c).sum(dim=1, keepdim=True) / (
+            c_hat.pow(2).sum(dim=1, keepdim=True).clamp_min(1e-12)
+        )
+        return (alpha * c_hat - c).pow(2).sum(dim=1).mean()
+
+    def _difference_reconstruction_loss(self, counts):
+        """Euclidean difference reconstruction, the same scale-invariant form as
+        ``_history_reconstruction_loss`` applied to differences of histories.
+
+        ``counts`` is a ``(B, V)`` batch of histograms. Each row is paired with
+        another row of the batch (a random cyclic shift), both normalized by
+        their length, and the unit-normalized difference ``d`` must decode to
+        itself: ``min_alpha ||alpha E E^T d - d||^2``, which equals the squared
+        sine of the angle between ``E E^T d`` and ``d``. Pairs with identical
+        histograms are skipped. This trains ``h_a - h_b`` to be decodable into
+        the events that differ, which the history term alone does not.
+        """
+        n = counts.sum(dim=1, keepdim=True)
+        valid = n.squeeze(1) > 0
+        if valid.sum() < 2:
+            return counts.new_zeros(())
+        c = counts[valid] / n[valid]
+        shift = int(torch.randint(1, c.shape[0], (1,)).item())
+        d = c - torch.roll(c, shifts=shift, dims=0)
+        norm = d.norm(dim=1, keepdim=True)
+        keep = norm.squeeze(1) > 1e-8
+        if not torch.any(keep):
+            return counts.new_zeros(())
+        d = d[keep] / norm[keep]
+        E = self.model.embedding.weight
+        d_hat = (d @ E) @ E.t()
+        alpha = (d_hat * d).sum(dim=1, keepdim=True) / (
+            d_hat.pow(2).sum(dim=1, keepdim=True).clamp_min(1e-12)
+        )
+        return (alpha * d_hat - d).pow(2).sum(dim=1).mean()
+
+    def _compute_losses(self, y1, h1, e_curr1, h_old, target, h2, counts=None):
         """Per-step prediction / reconstruction / consistency losses.
 
-        Reconstruction enforces invertibility of the update:
-        - Euclidean: subtracting the increment recovers the previous state,
-          ``(h_t - e_t) == h_{t-1}`` (exact when norm clipping does not fire).
+        Reconstruction:
+        - Euclidean: reconstructs the normalized event histogram ``counts`` of
+          the history from its additive embedding with the tied decoder ``E``
+          (see ``_history_reconstruction_loss``). The previous
+          ``(h_t - e_t) == h_{t-1}`` form was identically zero by construction
+          of ``h_t = h_{t-1} + e_t`` (non-zero only when norm clipping fired).
         - Hyperbolic: the gyrogroup *left-cancellation* law recovers the
           increment exactly, ``(-h_{t-1}) ⊕_c h_t == e_t``. (The previous
           ``(h_t ⊕_c -e_t)`` form is a right-cancellation and carries a
@@ -612,8 +873,7 @@ class Event2Vec:
         """
         prediction_loss = self.ce_loss(y1, target)
         if self.geometry == "euclidean":
-            h_reconstructed = h1 - e_curr1
-            reconstruction_loss = self.mse_loss(h_reconstructed, h_old)
+            reconstruction_loss = self._history_reconstruction_loss(counts)
             consistency_loss = self.mse_loss(h1, h2)
         elif self.geometry == "hyperbolic":
             e_recovered = HyperbolicUtils.mobius_add(-h_old, h1, self.curvature)
@@ -633,6 +893,12 @@ class Event2Vec:
             consistency_loss = self.model.dist2(h1, h2).mean()
         return prediction_loss, reconstruction_loss, consistency_loss
 
+    def _zero_counts(self, batch):
+        """Empty event histograms for the Euclidean reconstruction loss (else None)."""
+        if self.geometry != "euclidean":
+            return None
+        return torch.zeros((batch, self.num_event_types), device=self.device)
+
     def _train_epoch(self, sequences, optimizer, use_padding: bool) -> float:
         shuffled = sequences.copy()
         self._rng.shuffle(shuffled)
@@ -660,15 +926,19 @@ class Event2Vec:
                 continue
             seq = seq.to(self.device)
             h = self.model.zero_state(1, self.device)
+            counts = self._zero_counts(1)
             for t in range(seq.numel() - 1):
                 x = seq[t].unsqueeze(0)
                 target = seq[t + 1].unsqueeze(0)
                 h_old = h.detach()
                 y1, h1, e_curr1 = self.model(x, h_old)
                 _, h2, _ = self.model(x, h_old)
+                if counts is not None:
+                    # Histogram of seq[: t + 1], the events summed into h1.
+                    counts = counts + nn.functional.one_hot(x, self.num_event_types)
 
                 prediction_loss, reconstruction_loss, consistency_loss = (
-                    self._compute_losses(y1, h1, e_curr1, h_old, target, h2)
+                    self._compute_losses(y1, h1, e_curr1, h_old, target, h2, counts)
                 )
                 combined_loss = (
                     prediction_loss
@@ -700,6 +970,7 @@ class Event2Vec:
         )
 
         h = self.model.zero_state(len(sequences), self.device)
+        counts = self._zero_counts(len(sequences))
         total_loss = torch.tensor(0.0, device=self.device)
         total_transitions = 0
 
@@ -714,15 +985,29 @@ class Event2Vec:
 
             y1, h1, e_curr1 = self.model(x, h_old)
             _, h2, _ = self.model(x, h_old)
+            step_counts = None
+            if counts is not None:
+                # Only rows still inside their sequence are updated, so padding
+                # never enters a histogram.
+                counts = counts.index_add(
+                    0, idx, nn.functional.one_hot(x, self.num_event_types).to(counts.dtype)
+                )
+                step_counts = counts[idx]
 
             prediction_loss, reconstruction_loss, consistency_loss = (
-                self._compute_losses(y1, h1, e_curr1, h_old, target, h2)
+                self._compute_losses(y1, h1, e_curr1, h_old, target, h2, step_counts)
             )
             combined_loss = (
                 prediction_loss
                 + self.lambda_reconstruction * reconstruction_loss
                 + self.lambda_consistency * consistency_loss
             )
+            if self.lambda_difference > 0 and step_counts is not None:
+                # Differences need at least two histories, which only the padded
+                # loop (several sequences per step) provides.
+                combined_loss = combined_loss + self.lambda_difference * (
+                    self._difference_reconstruction_loss(step_counts)
+                )
             step_transitions = idx.numel()
             total_loss = total_loss + combined_loss * step_transitions
             total_transitions += step_transitions

{event2vector-0.4.1 → event2vector-0.5.0/event2vector.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: event2vector
-Version: 0.4.1
+Version: 0.5.0
 Summary: Scikit-learn-style geometric embeddings for event sequences.
 Author: Antonin Sulc
 License-Expression: MIT
@@ -18,6 +18,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: numpy>=1.21
 Requires-Dist: torch>=1.13
 Requires-Dist: scikit-learn>=1.0
+Requires-Dist: scipy>=1.5
 Requires-Dist: tqdm>=4.0
 Provides-Extra: viz
 Requires-Dist: matplotlib; extra == "viz"
@@ -131,7 +132,7 @@ step:
 | term | weight | what it enforces |
 |---|---|---|
 | next-event prediction | 1 | a linear decoder predicts event `t+1` from `h_t` (cross-entropy) |
-| reconstruction | `lambda_reconstruction` | the step `e_t` can be recovered from `h_{t-1}` and `h_t`, so the update stays invertible |
+| reconstruction | `lambda_reconstruction` | Euclidean: the history's event counts can be read back from its embedding with the tied decoder `E`, `‖α* E Eᵀ c/n − c/n‖²` with the closed-form best scale `α*`, so it does not fix the embedding norm; other geometries: the step `e_t` is recovered from `h_{t-1}` and `h_t` |
 | consistency | `lambda_consistency` | two dropout passes over the same step agree |
 
 There is no attention and no hidden nonlinearity in the state update, which is
@@ -141,7 +142,7 @@ what keeps every embedding a readable composition of its events. See the
 ## Geometries
 
 Choose the composition with `geometry=`. Every geometry uses the same estimator
-and a generic left-cancellation reconstruction loss.
+and, apart from `euclidean`, a generic left-cancellation reconstruction loss.
 
 | `geometry` | update | best for |
 |---|---|---|
@@ -230,9 +231,10 @@ the state.
 | `affine_max_log_scale` | `None` | bound on how much one event can stretch the `affine` state |
 | `product_kappas` | `(-1.0, 1.0)` | one curvature per factor for `product` |
 | `dropout_p` | `0.2` | dropout on each step's increment |
-| `max_norm` | `10.0` | norm clipping of the Euclidean state |
+| `max_norm` | `10.0` | norm clipping of the Euclidean state; `None` disables it, so the state is the exact sum of its events |
 | `lambda_reconstruction` | `0.2` | weight of the reconstruction loss |
 | `lambda_consistency` | `0.2` | weight of the consistency loss |
+| `lambda_difference` | `0.0` | weight of the difference-reconstruction loss (Euclidean, needs `pad_sequences=True`): the difference of two histories' states must decode to the events that differ |
 | `learning_rate` | `1e-3` | AdamW learning rate |
 | `batch_size` | `32` | sequences per batch |
 | `num_epochs` | `50` | training epochs |
@@ -250,10 +252,52 @@ the state.
 | `transform(sequences, as_numpy=True)` | one state per sequence (NumPy array or tensor) |
 | `fit_transform(sequences, ...)` | `fit`, then `transform` on the same sequences |
 | `most_similar(positive, negative=None, topn=10)` | nearest event ids to events or whole sequences, with similarities |
+| `attribute(sequence, target=None)` | each event's contribution to the logit of the next event `target` |
+| `counterfactual(sequence, remove)` | next-event probabilities with and without the events at positions `remove` |
+| `influence_matrix()` | `A[j, i]`: how much event `i` alone raises the logit of next event `j` |
+| `event_impact()` | how strongly one occurrence of each event moves the next-event distribution |
+| `decompose(sequence_or_state)` | event counts recovered from a state vector (Euclidean) |
+| `explain_difference(sequence_a, sequence_b)` | signed counts of the events that differ, read from the two states (Euclidean) |
 
 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:
+
+```python
+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
+```
+
+| method | geometries | exact when |
+|---|---|---|
+| `attribute` | all | Euclidean: always (the terms sum to the logit). Others: leave-one-out differences, which do not sum to the logit |
+| `counterfactual` | all | always (the edited sequence is re-encoded) |
+| `influence_matrix`, `event_impact` | all | Euclidean with `max_norm=None`: `A = W_dec Eᵀ` and every sequence's logits are `bias + A @ counts` |
+| `decompose`, `explain_difference` | Euclidean | `max_norm=None` and few enough distinct events for the embeddings to separate them; with clipping they estimate the clip-weighted counts |
+
+`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

{event2vector-0.4.1 → event2vector-0.5.0}/event2vector.egg-info/SOURCES.txt

@@ -25,4 +25,6 @@ event2vector/eval/__init__.py
 event2vector/eval/figures.py
 event2vector/eval/harness.py
 tests/test_affine.py
-tests/test_device.py
+tests/test_device.py
+tests/test_reconstruction.py
+tests/test_root_cause.py

{event2vector-0.4.1 → event2vector-0.5.0}/event2vector.egg-info/requires.txt

@@ -1,6 +1,7 @@
 numpy>=1.21
 torch>=1.13
 scikit-learn>=1.0
+scipy>=1.5
 tqdm>=4.0
 
 [dev]

{event2vector-0.4.1 → event2vector-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "event2vector"
-version = "0.4.1"
+version = "0.5.0"
 description = "Scikit-learn-style geometric embeddings for event sequences."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -34,6 +34,7 @@ dependencies = [
   "numpy>=1.21",
   "torch>=1.13",
   "scikit-learn>=1.0",
+  "scipy>=1.5",
   "tqdm>=4.0"
 ]
 

event2vector-0.5.0/tests/test_reconstruction.py

@@ -0,0 +1,214 @@
+"""Tests for the Euclidean event-history reconstruction loss.
+
+``L_recon = sum_t ||alpha* E (h_t - e_{s_t}) / (t-1) - c_{t-1} / (t-1)||^2`` with
+``h_{t-1} = E^T c_{t-1}`` and the closed-form scale
+``alpha* = <E E^T c, c> / ||E E^T c||^2``. Run with `pytest tests/ -q`.
+"""
+import pytest
+import torch
+
+from event2vector import Event2Vec
+
+V, D = 6, 4
+
+
+def _est(**kw):
+    kw = dict(dict(num_event_types=V, embedding_dim=D, dropout_p=0.0,
+                   use_gpu=False, random_state=0), **kw)
+    est = Event2Vec(**kw)
+    torch.manual_seed(0)
+    with torch.no_grad():
+        est.model.embedding.weight.normal_(0.0, 0.5)
+    return est
+
+
+def _record_counts(est, monkeypatch):
+    """Capture every histogram handed to the reconstruction loss."""
+    seen = []
+    original = est._history_reconstruction_loss
+
+    def wrapper(counts):
+        seen.append(counts.detach().clone())
+        return original(counts)
+
+    monkeypatch.setattr(est, "_history_reconstruction_loss", wrapper)
+    return seen
+
+
+def _batch_loss(est, seqs, padded):
+    opt = torch.optim.SGD(est.model.parameters(), lr=0.0)
+    seqs = [torch.tensor(s) for s in seqs]
+    if padded:
+        return est._train_batch_padded(seqs, opt)
+    return est._train_batch_unpadded(seqs, opt)
+
+
+def test_loss_is_nonzero_for_random_embeddings():
+    est = _est()
+    counts = torch.randint(0, 3, (8, V)).float()
+    counts[:, 0] += 1  # no empty histories
+    assert est._history_reconstruction_loss(counts).item() > 1e-3
+
+
+def test_loss_has_nonzero_embedding_gradient():
+    est = _est()
+    counts = torch.tensor([[2.0, 1.0, 0.0, 0.0, 1.0, 0.0]])
+    est._history_reconstruction_loss(counts).backward()
+    assert est.model.embedding.weight.grad.norm().item() > 1e-4
+
+
+@pytest.mark.parametrize("padded", [False, True])
+def test_histogram_counts_repeated_events(monkeypatch, padded):
+    est = _est()
+    seen = _record_counts(est, monkeypatch)
+    _batch_loss(est, [[3, 3, 1, 3, 0]], padded)
+    expected = [{3: 1}, {3: 2}, {3: 2, 1: 1}, {3: 3, 1: 1}]  # last event is only a target
+    assert len(seen) == len(expected)
+    for counts, exp in zip(seen, expected):
+        target = torch.zeros(1, V)
+        for k, v in exp.items():
+            target[0, k] = v
+        assert torch.equal(counts, target)
+
+
+def test_loss_is_invariant_to_embedding_scale():
+    est = _est()
+    counts = torch.tensor([[1.0, 0.0, 2.0, 0.0, 3.0, 1.0], [0.0, 4.0, 0.0, 1.0, 0.0, 0.0]])
+    before = est._history_reconstruction_loss(counts)
+    with torch.no_grad():
+        est.model.embedding.weight.mul_(7.0)
+    assert torch.allclose(est._history_reconstruction_loss(counts), before, rtol=1e-4)
+
+
+def test_empty_histories_are_excluded():
+    est = _est()
+    counts = torch.tensor([[1.0, 0.0, 2.0, 0.0, 0.0, 1.0]])
+    with_empty = torch.cat([counts, torch.zeros(2, V)])
+    assert torch.allclose(est._history_reconstruction_loss(with_empty),
+                          est._history_reconstruction_loss(counts))
+    assert est._history_reconstruction_loss(torch.zeros(3, V)).item() == 0.0
+
+
+def test_padding_is_excluded(monkeypatch):
+    # pad_value=0 is also a real event id, so a leaked pad would change the counts.
+    seqs = [[0, 1, 2, 3, 4], [2, 2], [5, 0, 5]]
+    padded_est, unpadded_est = _est(pad_value=0), _est(pad_value=0)
+    seen = _record_counts(padded_est, monkeypatch)
+    loss_padded = _batch_loss(padded_est, seqs, padded=True)
+    loss_unpadded = _batch_loss(unpadded_est, seqs, padded=False)
+    assert loss_padded == pytest.approx(loss_unpadded, rel=1e-5)
+    # every row's histogram length equals its step index + 1, never more
+    for t, counts in enumerate(seen):
+        assert torch.all(counts.sum(dim=1) == t + 1)
+    assert seen[-1].shape[0] == 1  # only the longest sequence is left at the end
+
+
+def test_batched_loss_matches_definition():
+    seqs = [[0, 1, 1, 4, 2], [3, 3, 5], [2, 0, 2, 2]]
+    est = _est(lambda_consistency=0.0)
+    E = est.model.embedding.weight.detach()
+
+    # Reference: sum_{t=2}^{T} ||alpha* E (h_t - e_{s_t}) - c_{t-1}||^2 / (t-1)^2,
+    # with the additive state built step by step (no clipping, no dropout).
+    terms = []
+    for seq in seqs:
+        h = torch.zeros(D)
+        c = torch.zeros(V)
+        for t in range(1, len(seq)):  # s_t = seq[t] (0-based), history seq[:t]
+            h = h + E[seq[t - 1]]
+            c[seq[t - 1]] += 1
+            h_t = h + E[seq[t]]
+            c_hat = E @ (h_t - E[seq[t]])
+            alpha = (c_hat @ c) / (c_hat @ c_hat)
+            terms.append(((alpha * c_hat - c) / t).pow(2).sum())
+    reference = torch.stack(terms).mean().item()
+
+    for padded in (False, True):
+        est.lambda_reconstruction = 0.0
+        base = _batch_loss(est, seqs, padded)
+        est.lambda_reconstruction = 1.0
+        full = _batch_loss(est, seqs, padded)
+        assert full - base == pytest.approx(reference, rel=1e-4)
+
+
+def test_reconstruction_gradient_reaches_embedding_in_training():
+    est = _est(lambda_consistency=0.0)
+    seqs = [torch.tensor([0, 1, 2, 3])]
+    grads = {}
+    for lam in (0.0, 1.0):
+        est.lambda_reconstruction = lam
+        est.model.zero_grad()
+        opt = torch.optim.SGD(est.model.parameters(), lr=0.0)
+        opt.zero_grad = lambda *a, **k: None  # keep the grads for inspection
+        est._train_batch_unpadded(seqs, opt)
+        grads[lam] = est.model.embedding.weight.grad.clone()
+    assert (grads[1.0] - grads[0.0]).norm().item() > 1e-4
+
+
+@pytest.mark.parametrize("lam", [0.0, 0.2])
+def test_next_event_prediction_still_learns(lam):
+    seqs = [[0, 1, 2, 3, 4]] * 16
+    est = Event2Vec(num_event_types=5, embedding_dim=8, dropout_p=0.0,
+                    lambda_reconstruction=lam, num_epochs=60, learning_rate=1e-2,
+                    batch_size=8, use_gpu=False, random_state=0)
+    est.fit(seqs)
+    est.model.eval()
+    h = est.model.zero_state(1, est.device)
+    correct = 0
+    with torch.no_grad():
+        for t in range(4):
+            logits, h, _ = est.model(torch.tensor([t]), h)
+            correct += int(logits.argmax(dim=1).item() == t + 1)
+    assert correct == 4
+
+
+@pytest.mark.parametrize("max_norm", [None, float("inf")])
+def test_unclipped_state_is_exact_sum_and_trains(max_norm):
+    est = _est(max_norm=max_norm, num_epochs=2, batch_size=2)
+    E = est.model.embedding.weight.detach().clone()
+    h = est.model.zero_state(1, est.device)
+    for i in [3, 1, 3, 5]:
+        h = est.model(torch.tensor([i]), h)[1]
+    assert torch.allclose(h[0], E[[3, 1, 3, 5]].sum(0), atol=1e-5)
+    est.fit([[0, 1, 2, 3], [3, 3, 1], [5, 0, 5, 2]])
+    assert all(torch.isfinite(p).all() for p in est.model.parameters())
+
+
+def test_difference_loss_is_nonzero_scale_invariant_and_trains():
+    est = _est(lambda_difference=0.5)
+    counts = torch.tensor([[2.0, 1.0, 0.0, 0.0, 1.0, 0.0], [0.0, 1.0, 3.0, 0.0, 0.0, 1.0],
+                           [1.0, 0.0, 0.0, 2.0, 0.0, 0.0]])
+    torch.manual_seed(0)
+    loss = est._difference_reconstruction_loss(counts)
+    assert loss.item() > 1e-3
+    loss.backward()
+    assert est.model.embedding.weight.grad.norm().item() > 1e-4
+    with torch.no_grad():
+        est.model.embedding.weight.mul_(5.0)
+    torch.manual_seed(0)
+    assert torch.allclose(est._difference_reconstruction_loss(counts), loss, rtol=1e-4)
+    # identical histograms give no pair; fewer than two rows give no pair
+    same = counts[:1].repeat(3, 1)
+    assert est._difference_reconstruction_loss(same).item() == 0.0
+    assert est._difference_reconstruction_loss(counts[:1]).item() == 0.0
+    est = _est(lambda_difference=0.5, num_epochs=2, batch_size=3, pad_sequences=True)
+    est.fit([[0, 1, 2, 3], [3, 3, 1, 5], [5, 0, 5, 2, 4]])
+    assert all(torch.isfinite(p).all() for p in est.model.parameters())
+
+
+def test_difference_loss_only_in_padded_training():
+    seqs = [torch.tensor([0, 1, 2, 3]), torch.tensor([3, 3, 1, 5])]
+    est = _est(lambda_difference=1.0, lambda_consistency=0.0)
+    opt = torch.optim.SGD(est.model.parameters(), lr=0.0)
+    torch.manual_seed(0)
+    with_term = est._train_batch_padded(seqs, opt)
+    est.lambda_difference = 0.0
+    torch.manual_seed(0)
+    without = est._train_batch_padded(seqs, opt)
+    assert with_term > without
+    est.lambda_difference = 1.0
+    torch.manual_seed(0)
+    unpadded_with = est._train_batch_unpadded(seqs, opt)
+    est.lambda_difference = 0.0
+    torch.manual_seed(0)
+    assert unpadded_with == pytest.approx(est._train_batch_unpadded(seqs, opt))

event2vector-0.5.0/tests/test_root_cause.py

@@ -0,0 +1,128 @@
+"""Tests for the root-cause analysis API (``attribute``, ``counterfactual``,
+``influence_matrix``, ``event_impact``, ``decompose``, ``explain_difference``)
+and ``metrics.transition_graph_auc``. Run with `pytest tests/ -q`.
+"""
+import numpy as np
+import pytest
+import torch
+
+from event2vector import Event2Vec
+from event2vector.metrics import transition_graph_auc
+
+V = 8
+SEQS = [[0, 1, 2, 3], [0, 1, 4, 5], [6, 2, 3, 7], [0, 6, 1, 2]] * 4
+
+
+def _fit(**kw):
+    kw = dict(dict(num_event_types=V, embedding_dim=6, dropout_p=0.0, num_epochs=3,
+                   batch_size=4, use_gpu=False, random_state=0), **kw)
+    return Event2Vec(**kw).fit(SEQS)
+
+
+@pytest.mark.parametrize("max_norm", [None, 10.0, 0.01])
+def test_euclidean_attribution_is_exact(max_norm):
+    est = _fit(max_norm=max_norm)
+    seq = [0, 6, 1, 2, 1]
+    out = est.attribute(seq, target=3)
+    assert out["exact"] and len(out["contributions"]) == len(seq)
+    assert out["bias"] + out["contributions"].sum() == pytest.approx(out["logit"], abs=1e-4)
+    if max_norm is None:
+        assert np.allclose(out["weights"], 1.0)
+    if max_norm == 0.01:  # clipping fires: earlier events are down-weighted
+        assert np.all(np.diff(out["weights"]) >= -1e-6) and out["weights"][0] < 1.0
+
+
+def test_attribution_defaults_to_predicted_event():
+    est = _fit()
+    out = est.attribute([0, 1])
+    logits = est._next_logits([0, 1])
+    assert out["target"] == int(logits.argmax())
+
+
+@pytest.mark.parametrize("geometry,kw", [("hyperbolic", {}), ("rotation", {"rotation_n": 3})])
+def test_attribution_falls_back_to_leave_one_out(geometry, kw):
+    est = _fit(geometry=geometry, **kw)
+    seq = [0, 1, 2]
+    out = est.attribute(seq, target=3)
+    assert not out["exact"] and out["weights"] is None
+    expected = out["logit"] - float(est._next_logits([0, 2])[3])
+    assert out["contributions"][1] == pytest.approx(expected, abs=1e-5)
+
+
+@pytest.mark.parametrize("geometry", ["euclidean", "hyperbolic"])
+def test_counterfactual_matches_reencoding(geometry):
+    est = _fit(geometry=geometry)
+    out = est.counterfactual([0, 1, 2, 3], remove=[1, 3])
+    q = torch.softmax(est._next_logits([0, 2]), 0).numpy()
+    assert np.allclose(out["probs_counterfactual"], q, atol=1e-6)
+    assert np.allclose(out["delta"], out["probs_counterfactual"] - out["probs"])
+    assert out["probs"].sum() == pytest.approx(1.0, abs=1e-5)
+
+
+def test_influence_matrix_is_decoder_times_embeddings_without_clipping():
+    est = _fit(max_norm=None)
+    A = est.influence_matrix()
+    W = est.model.linear_dec.weight.detach().numpy()
+    E = est.model.embedding.weight.detach().numpy()
+    assert A.shape == (V, V) and np.allclose(A, W @ E.T, atol=1e-5)
+    # every sequence's logits are bias + A @ counts
+    counts = np.bincount([0, 1, 1, 5], minlength=V)
+    b = est.model.linear_dec.bias.detach().numpy()
+    assert np.allclose(est._next_logits([0, 1, 1, 5]).numpy(), b + A @ counts, atol=1e-4)
+
+
+def test_event_impact_is_centered_column_norm():
+    est = _fit(geometry="hyperbolic")
+    A = est.influence_matrix()
+    impact = est.event_impact()
+    assert impact.shape == (V,)
+    assert impact[2] == pytest.approx(np.linalg.norm(A[:, 2] - A[:, 2].mean()), rel=1e-5)
+
+
+def _orthogonal_estimator():
+    est = _fit(max_norm=None, embedding_dim=V)
+    with torch.no_grad():  # orthonormal embeddings: every history is identifiable
+        est.model.embedding.weight.copy_(torch.eye(V) * 2.0)
+    return est
+
+
+def test_decompose_recovers_counts_from_state():
+    est = _orthogonal_estimator()
+    seq = [3, 1, 3, 7, 3]
+    expected = np.bincount(seq, minlength=V)
+    assert np.array_equal(est.decompose(seq, round_counts=True), expected)
+    state = est.transform([seq], as_numpy=False)[0]
+    assert np.allclose(est.decompose(state), expected, atol=1e-6)
+
+
+def test_explain_difference_returns_signed_counts():
+    est = _orthogonal_estimator()
+    diff = est.explain_difference([0, 2, 2, 5], [0, 2, 6], round_counts=True)
+    expected = np.zeros(V)
+    expected[[2, 5, 6]] = [1, 1, -1]
+    assert np.array_equal(diff, expected)
+
+
+def test_sum_based_methods_reject_other_geometries():
+    est = _fit(geometry="hyperbolic")
+    with pytest.raises(NotImplementedError):
+        est.decompose([0, 1])
+    with pytest.raises(NotImplementedError):
+        est.explain_difference([0, 1], [1])
+
+
+def test_transition_graph_auc():
+    est = _fit()
+    vocab = {f"e{i}": i for i in range(V)}
+    graph = {"e0": [("e1", 0.5), ("e6", 0.5)], "e1": [("e2", 1.0)], "e2": [("e3", 1.0)]}
+    A = np.zeros((V, V))
+    A[1, 0] = A[6, 0] = A[2, 1] = A[3, 2] = 1.0  # a perfect score on the true edges
+    out = transition_graph_auc(est, graph, vocab, influence=A)
+    assert out["auc"] == 1.0 and out["n_edges"] == 4 and out["n_pairs"] == V * (V - 1)
+    assert 0.0 <= transition_graph_auc(est, graph, vocab)["auc"] <= 1.0
+
+
+def test_root_cause_methods_require_fit():
+    est = Event2Vec(num_event_types=V, use_gpu=False)
+    with pytest.raises(RuntimeError):
+        est.attribute([0, 1])