← Back to TracePrism project page

Implementation Details and Reproducibility Appendix

Supplementary technical material accompanying the TVCG submission "TracePrism: Extending Semantic Trace Topics to Iterative, Encoding-Aware Trace Partitioning." This page holds detail that is either too mechanical to belong in the main paper's page budget, or that a reviewer wanting to reproduce a result would need but a reader following the argument would not.

1. Encoding library: complete token-family definitions

Expands the paper's §Approach, "Encoding library" (Table III) and the two parameter-definition paragraphs that follow it. The compressed version in the paper keeps only what is needed to read Table III; the full definitions, useful for anyone re-implementing a token family exactly, are here.

Ten token families

An encoding is a subset of the following ten token families, used in any combination. The plain activity token, max-gap tier, and case-attribute tier families are order-agnostic: each reduces a trace to a multiset of activities or to a small number of per-trace scalar summaries, independent of sequence position. The remaining families are order-sensitive: 2-grams, 3-grams, and gap-augmented 2-grams capture immediate or short-range transitions; lagged follow captures ordered-but-not-adjacent proximity; relative transition time is a per-transition norm. Attribute-augmented activity sits between the two groups: it names a specific position (the trace's final activity) but says nothing about what came before it.

Timing families: the shared quantile scheme

A gap tier discretizes a waiting time into n bins — three by default, labeled low, mid, high — using quantile cutoffs computed live from every occurrence of that quantity in the current subset, never from a global or dataset-wide reference. This matters because the same absolute waiting time can be "high" in a fast-moving working set and "low" in a slow-moving one; the tiers describe a distribution's own shape, not an absolute duration threshold fixed in advance.

• Temporal gap tier applies this tiering to the gap before every event in the trace, so a single trace can contribute several temporal-gap tokens, one per event.
• Max-gap tier instead emits exactly one token per trace, tiering only that trace's single longest gap. It is order-agnostic because it is a per-trace scalar summary, not a per-event annotation.
• Gap-augmented 2-gram attaches the same per-occurrence tier, computed from the same pooled cutoffs as temporal gap, to the 2-gram it belongs to. A single transition type (e.g. Send→Pay) can therefore contribute several distinct tokens, one per tier its instances fall into (Send→Pay[low], Send→Pay[high], etc.).

Lagged follow bounds a number of intervening events rather than elapsed time. With a window of w (two by default), it tokenizes every ordered pair of activities at trace positions i<j with j−i≤w, so a longer-range dependency such as "eventually notified, then eventually paid" is captured even when other events intervene — at the cost of no longer naming a specific position in the trace.

Relative transition time departs from the tiering scheme entirely. For each transition type (the ordered activity pair itself), it computes the median gap over every occurrence of that type in the current subset, then labels a specific occurrence early, on-time, or late according to whether its own gap falls below 70%, within, or above 130% of that type's own median. This ±30% band is a fixed constant, not a sweep parameter, because it describes a transition's pace relative to itself, not relative to a subset-wide distribution — there is no obvious "current subset" analogue to sweep it against.

Case-context families

Case-attribute tiers use the same live-quantile scheme as temporal gap, computed only from the traces in the current subset that carry a non-missing value for that attribute. A trace missing the attribute contributes no token for that family, rather than a synthetic "missing" tier. This choice is deliberate: a synthetic missing-tier would let a handful of incomplete traces distort the tier boundaries computed for everyone else, and would risk the system reading "no data recorded" as if it were a value in its own right.

Attribute-augmented activity tokens face a mismatch that all three of our logs share: every case attribute is recorded once per case, not once per event, so there is no single activity a general-purpose implementation can privilege as "the" one to fuse an attribute with. The implementation anchors every such token to the trace's final activity — a choice that needs no dataset-specific rule, since every trace has exactly one final activity by construction — and tiers numeric attributes into three bins for this family regardless of what n the case-attribute-tier family itself is using in the same encoding.

2. Interface walkthrough: all seven tabs

Expands the paper's §System. The paper's compressed version keeps design rationale; this page keeps the full click-level description, useful for someone trying to reproduce a session interaction-by-interaction rather than only reading the design intent.

Data

Supports T1 and, through rule-based groups, T4. Distribution plots over activities, durations, and case attributes are sortable and show exact counts on hover, so a first pass over a new working set is an overview-then-detail reading of the same population that the dataset table describes only in aggregate. A year-by-month heatmap of each trace's start and end date is part of this overview (see §4 below). Rule-based detection of exact-variant subsets that meet both a size and a purity threshold surfaces obvious groups directly in this view, each committed with one click. Every tab reads the same trace table, so a variant already claimed by an active knowledge-base entry is grayed out here rather than offered again — this is what keeps the set of unexplained traces consistent across tabs without the analyst tracking it by hand.

Encoding

Supports T2. Every token family above is a switch the analyst can turn on or off. Pressing "Score candidates against working set" runs the candidate-encoding scorer against the current working set and highlights the combinations it favors, top row first. Hovering a highlighted combination shows the three quantities behind its ranking as a tooltip: sharp, the mean per-trace share of weight held by that trace's largest topic in a quick K=4 fit (higher meaning traces land confidently in one topic); NMI, the normalized mutual information between that fit's dominant-topic assignment and the outcome (higher meaning the topic structure aligns with what actually happened); and score, the equally weighted combination 0.5·sharp + 0.5·NMI used to order the rows. This lets the heuristic be checked rather than simply trusted. The analyst reads these suggestions and then sets the switches manually, rather than accepting a ranking outright. Once the encoding is set, the analyst either moves on to the K-sweep tab with the current working set, or selects a different subset to score instead — either everything not yet explained, or an earlier recorded group to revisit.

K-sweep

Supports T1 and T3. Dragging the sweep's range control re-fits NMF once per value of K in a worker, without blocking the interface. Four coordinated views update together: a topic-stability (Sankey) diagram tracking which topics split or merge between adjacent values of K; a reconstruction-error (elbow) curve; a silhouette curve; and a coverage curve, the share of the working set covered by topics currently passing the coherence filter. All are linked by more than adjacency — hovering a node, a flow band, or an embedding dot highlights the same topic everywhere, and hovering a point on the curves reports the exact reconstruction error, silhouette score, and coverage for that K. Three range sliders, on dominant-outcome share, structural coherence S(G), and outcome coherence O(G), sit above the diagram and can be dragged independently at any time; each drag re-tints which topics currently qualify without triggering any new computation, so the coherence threshold is something the analyst explores rather than a fixed cutoff. Clicking any node of the stability diagram opens the Topics tab at that K.

Topics

Supports T4, T5, and T6. Selecting a topic — from the stability diagram, a small-multiples overview, or a term–topic heatmap — drives every other panel in the tab at once: its directly-follows graph, its S(G) and O(G) readout, and its attribute fingerprint (where the group is large enough to support one) all update together. The small-multiples overview draws every topic in the current fit side by side, resizable by trace count or by NMF weight with a single toggle. The term–topic heatmap gives the same overview at the vocabulary level: clicking a topic's row re-sorts every column by that topic's own weights, clicking the MAX or SUM row instead sorts by importance across the whole fit, and hovering any cell reports its exact weight to three decimal places. Within a single topic's detail view, its directly-follows graph is drawn twice, once sized by raw transition count and once by NMF weight, colored by which of the two dominates: gold where weight exceeds count (distinctive of this topic), blue where count exceeds weight (common across many topics), gray where the two agree. When the round's encoding includes 3-grams, the same graph adds a dashed edge from the first to the third activity of a salient triple; the gap, timing, and attribute-augmented families have no equivalent mark yet and are read through the fingerprint and coherence scores instead.

Trace groups

Supports T4 and T5; implements the two group-formation mechanisms other than a dominant topic. For k-means over the topic-weight vectors, an N-sweep slider previews candidate cluster counts N=3…20 against a live silhouette curve — the same elbow-reading interaction as the K-sweep tab one stage earlier, so choosing a cluster count and choosing a topic count are the same gesture. For manual selection, a two-dimensional UMAP embedding of the same topic-weight vectors is directly brushable: the analyst can lasso an arbitrary region as a candidate group, for cases where neither a single dominant topic nor an automatic cluster isolates a coherent subset cleanly (an irregular shape, or a partial overlap between two topics). The embedding's neighborhood size, minimum distance, and spread are exposed as controls, and its random seed is displayed and held fixed so a brushed region can be reproduced (exact defaults in §5 below). Both mechanisms report S(G) and O(G) live as N or the brushed region changes.

Knowledge

Supports T5 and T7. Committed groups are shown two ways at once: a two-dimensional arrangement in which each entry is a pie glyph, sized by the square root of its trace count, sliced by its outcome mix, and positioned by a PCA projection of that entry's own activity-type profile, so behaviorally similar entries land near each other; and a summary table listing every entry's size, outcome mix, dominant-outcome share, and S(G)/O(G), sortable by any column. The two views are linked: hovering a pie shows that entry's full card as a tooltip and highlights its table row, and vice versa. Reopening (T7) is a single button on any card. It restores the exact working set and encoding under which the group was originally formed, and marks the entry inactive rather than deleting it, so its card, statistics, and place in the arrangement all remain visible after reopening. Every entry, active or reopened, can be exported as CSV together with per-trace provenance.

Log

The only tab not tied to a specific task in its own right. It is a plain, chronologically ordered, timestamped list of every action taken in a session, with no filtering or aggregation. Its purpose is to make the provenance requirement checkable after the fact rather than only asserted: every number and figure in the paper's case studies is drawn directly from a session's log and knowledge-base export, not reconstructed from memory or from screenshots taken along the way.

3. Attribute-divergence chip examples

Expands the paper's fingerprint-chip table, moved here in full per the round-2 revision plan; the paper keeps one or two examples folded into a figure caption instead of a standalone table.

4. Reading the log's temporal shape (extended)

Expands the paper's Case Studies subsection of the same name, compressed there to 2–3 sentences justifying the max-gap token choice per the round-2 revision plan.

Before any modeling round, the Data tab's start- and end-date distributions already show an asymmetry that shapes the encoding choices that follow. Start dates spread almost continuously across the log's thirteen-year span, with a mild rise in the summer months. End dates do not: they cluster into a handful of discrete bands, months in which a disproportionate share of cases close at once. A fine's creation date tracks when a violation occurs — an effectively continuous process; its closing date tracks periodic batch processing on the administrative side. If cases close in batches, the waiting time before a case's last event carries more information than the identity of that event, which is why round B's top-ranked encoding (Table VI of the paper) adds a max-gap tier over activities and 2-grams: the scoring mechanism independently favors exactly the token family this reading of the heatmap would suggest by inspection, on the one working set (3,131 traces) where the batch-closing pattern is concentrated enough to matter for the score. Every later round, on the much larger main remainder, is instead topped by the simpler activities-plus-2-grams combination, without a gap tier — consistent with the batch-closing signal being a property of that specific near-obvious subset rather than of the log as a whole.

5. Algorithm parameters, defaults, and seeds

New content, not adapted from any paper section — written to address Reviewer 3's and Reviewer 4's request for exact algorithmic and reproducibility detail (solver, initialization, iterations, seeds) that the paper's Methods section does not state. Everything below is read directly from the shipped implementation (compute_worker.js, embed_worker.js, script.js, index.html), not asserted from memory, so it is exact as of the commit this page accompanies.

NMF

• Objective. Standard nonnegative matrix factorization minimizing Frobenius-norm reconstruction error ‖V − WH‖_F, via the multiplicative-update rule of Lee & Seung (1999).
• Initialization. NNDSVDa (nonnegative double singular value decomposition with the zero-entries-filled-by-average variant), a deterministic initialization. No random seed is involved in initializing W or H.
• Iterations. Every NMF fit in the shipped system — the quick K=4 scoring fit and every K-sweep/committed fit alike — runs for exactly 50 multiplicative-update iterations. The implementation supports an early-stopping tolerance, but every call site in the current code sets that tolerance to 0, so early stopping never actually triggers; all fits run the full 50 iterations regardless of dataset size.
• Restarts. None. NNDSVDa's determinism removes the need for multiple restarts to average over initialization variance, which is why the implementation does not offer one.

k-means (Trace-groups tab and cluster sweep)

• Initialization. Centers are chosen by uniform random sampling of distinct trace indices from the current working set, without replacement.
• Iterations. Exactly 30 Lloyd iterations (assign-then-recompute-centroid steps), unconditionally — there is no convergence check; the loop always runs all 30 iterations.
• Restarts. A single run per requested cluster count; no best-of-n restart.
• Seed. Fixed at 42 by default at every call site (single-K clustering, the N-sweep, and the K-sweep's own pooled-topic clustering used for the stability diagram); the analyst-facing seed field can be changed or randomized in the Trace-groups tab UI.

UMAP (Trace-groups tab manual selection)

• Library. umap-js v1.4.0, run inside a dedicated Web Worker.
• Default parameters (analyst-adjustable in the UI): neighbors (nNeighbors) = 15, range 2–50; minimum distance = 0.10, range 0.01–1; spread = 1.0, range 0.1–3.
• Seed. Fixed at 42 by default, both for the main brushable embedding and for the pooled two-dimensional embedding used in the K-sweep tab's stability diagram; displayed in the UI and changeable, with a randomize control, so a specific embedding can be reproduced or deliberately re-rolled.
• Reproducibility of a brushed group. The knowledge base stores the brushed group's trace IDs at commit time, not the lasso polygon. A saved entry is therefore exactly reproducible regardless of the embedding's own stability under a reseed; re-deriving the same brushed region from scratch under a different seed is a separate question the system does not need to answer to keep the commit itself reproducible.

Candidate-encoding scorer

• Uses the same NMF routine above at a fixed K=4, over the current working set, for every combination of token families scored.
• sharp = mean over traces of (largest topic weight ÷ sum of topic weights) at that K=4 fit.
• NMI = normalized mutual information between the K=4 fit's dominant-topic assignment and the outcome label, computed as 2·MI(T;Y) / (H(T) + H(Y)).
• score = 0.5·sharp + 0.5·NMI, the value used to rank the shortlist shown in the Encoding tab.

6. Artifact and archival checklist

New content, addressing Reviewer 3's supplementary-material checklist (source repository, license, frozen archive, dataset versions, hardware/browser specs).