openprocess 0.7.0__py3-none-any.whl

openprocess/mining/layout.py

@@ -0,0 +1,279 @@
+"""Automatic left-to-right layout of process graphs (Sugiyama's method).
+
+Discovered models have no coordinates, so the app must place every node
+itself.  ProM and PM4Py hand this to Graphviz; we do it in pure Python so the
+app needs no external binary.  The method is the classic *layered* drawing
+of Sugiyama, Tagawa & Toda (1981), which is also what Graphviz ``dot`` uses:
+
+1. **Break cycles.**  Layering needs a DAG, so a depth-first search reverses
+   every back edge (loops in the process).  Reversed edges are drawn in
+   their original direction afterwards.
+2. **Assign layers** (columns).  Longest-path layering from the sources, so
+   the start of the process is on the left.
+3. **Insert dummy nodes** on edges spanning several layers, so every edge
+   connects adjacent layers and can be routed around other nodes.
+4. **Reduce crossings.**  Reorder nodes within each layer by the barycentre
+   (average position) of their neighbours, sweeping left-to-right and back;
+   keep the best ordering seen.
+5. **Assign coordinates.**  x from the layer, y by repeatedly pulling each
+   node towards the median of its neighbours while keeping a minimum gap.
+
+The result gives a centre point per node and a polyline per edge (through
+its dummy nodes), which the canvas turns into smooth curves.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+
+@dataclass
+class LayoutResult:
+    positions: dict[str, tuple[float, float]]                   # node -> centre
+    routes: dict[int, list[tuple[float, float]]] = field(default_factory=dict)  # edge index -> points
+    width: float = 0.0
+    height: float = 0.0
+
+
+def layered_layout(nodes: dict[str, tuple[float, float]], edges: list[tuple[str, str]],
+                   layer_gap: float = 70.0, node_gap: float = 28.0,
+                   sweeps: int = 16, soft_edges: frozenset[int] | set[int] = frozenset()
+                   ) -> LayoutResult:
+    """Lay out ``nodes`` (id -> (width, height)) connected by ``edges``.
+
+    Self-loops are ignored for layering (the canvas draws them as small
+    arcs).  Returns centre positions and a route per edge index.
+
+    ``soft_edges`` (indices into ``edges``) do not decide the layers.  A node
+    reached *only* through soft edges -- a resource place that a transition
+    reads and writes back, say -- is put in the layer of its neighbours,
+    right next to them, instead of dragging the whole drawing out of shape.
+    """
+    ids = list(nodes)
+    if not ids:
+        return LayoutResult({})
+    hard = [(a, b) for index, (a, b) in enumerate(edges) if index not in soft_edges]
+
+    # -- 1. break cycles ----------------------------------------------------
+    successors: dict[str, list[str]] = defaultdict(list)
+    for a, b in hard:
+        if a != b:
+            successors[a].append(b)
+    order = {node: i for i, node in enumerate(ids)}
+    # Start the DFS from nodes without predecessors (process starts) so that
+    # the natural direction of the process is kept and loops get reversed.
+    has_pred = {b for a, b in hard if a != b}
+    roots = [n for n in ids if n not in has_pred] + [n for n in ids if n in has_pred]
+    state: dict[str, int] = {}          # 1 = on stack, 2 = done
+    back_edges: set[tuple[str, str]] = set()
+    for root in roots:
+        if root in state:
+            continue
+        stack = [(root, iter(sorted(successors[root], key=order.get)))]
+        state[root] = 1
+        while stack:
+            node, children = stack[-1]
+            for child in children:
+                if state.get(child) == 1:
+                    back_edges.add((node, child))
+                elif child not in state:
+                    state[child] = 1
+                    stack.append((child, iter(sorted(successors[child], key=order.get))))
+                    break
+            else:
+                state[node] = 2
+                stack.pop()
+
+    dag: list[tuple[str, str]] = []
+    for a, b in hard:
+        if a == b:
+            continue
+        dag.append((b, a) if (a, b) in back_edges else (a, b))
+
+    # -- 2. layers: longest path from sources ------------------------------
+    preds: dict[str, set[str]] = defaultdict(set)
+    succs: dict[str, set[str]] = defaultdict(set)
+    for a, b in dag:
+        preds[b].add(a)
+        succs[a].add(b)
+    layer: dict[str, int] = {}
+    pending = {n: len(preds[n]) for n in ids}
+    ready = [n for n in ids if pending[n] == 0]
+    while ready:
+        node = ready.pop(0)
+        layer[node] = max((layer[p] + 1 for p in preds[node]), default=0)
+        for child in sorted(succs[node], key=order.get):
+            pending[child] -= 1
+            if pending[child] == 0:
+                ready.append(child)
+    for n in ids:  # safety net; cannot happen after cycle breaking
+        layer.setdefault(n, 0)
+
+    # Nodes attached by soft edges only join the layer of their neighbours.
+    in_hard = {n for edge in hard for n in edge if edge[0] != edge[1]}
+    free = [n for n in ids if n not in in_hard]
+    soft_neighbours: dict[str, list[str]] = defaultdict(list)
+    for index in soft_edges:
+        a, b = edges[index]
+        soft_neighbours[a].append(b)
+        soft_neighbours[b].append(a)
+    placed = set(in_hard)
+    for _ in range(3):                  # a few rounds settle chains of free nodes
+        for n in free:
+            known = sorted(layer[x] for x in soft_neighbours[n] if x in placed)
+            if known:
+                layer[n] = known[len(known) // 2]
+                placed.add(n)
+    # Soft edges between nodes in different layers are drawn like any other;
+    # within one layer they are "side" edges: no dummies, but they still pull
+    # the two nodes next to each other.
+    back_edges |= {(a, b) for index, (a, b) in enumerate(edges)
+                   if index in soft_edges and layer[a] > layer[b]}
+    side: dict[str, list[str]] = defaultdict(list)
+    same_layer: set[int] = set()
+    for index, (a, b) in enumerate(edges):
+        if a != b and layer[a] == layer[b]:
+            same_layer.add(index)
+            side[a].append(b)
+            side[b].append(a)
+
+    # -- 3. dummy nodes -------------------------------------------------------
+    chain_of: dict[int, list[str]] = {}
+    adjacency: list[tuple[str, str]] = []
+    dummy_count = 0
+    all_nodes = list(ids)
+    for index, (a, b) in enumerate(edges):
+        if a == b or index in same_layer:
+            continue
+        u, v = (b, a) if (a, b) in back_edges else (a, b)
+        chain = [u]
+        for level in range(layer[u] + 1, layer[v]):
+            dummy = f"\x00d{dummy_count}"
+            dummy_count += 1
+            layer[dummy] = level
+            all_nodes.append(dummy)
+            chain.append(dummy)
+        chain.append(v)
+        for x, y in zip(chain, chain[1:]):
+            adjacency.append((x, y))
+        chain_of[index] = chain if (a, b) not in back_edges else chain[::-1]
+
+    layers: list[list[str]] = [[] for _ in range(max(layer.values()) + 1)]
+    for node in all_nodes:
+        layers[layer[node]].append(node)
+
+    up: dict[str, list[str]] = defaultdict(list)
+    down: dict[str, list[str]] = defaultdict(list)
+    for x, y in adjacency:
+        down[x].append(y)
+        up[y].append(x)
+
+    # -- 4. crossing reduction --------------------------------------------
+    def position_map(current: list[list[str]]) -> dict[str, int]:
+        return {n: i for level in current for i, n in enumerate(level)}
+
+    def crossings(current: list[list[str]]) -> int:
+        pos = position_map(current)
+        total = 0
+        for level in current[:-1]:
+            pairs = sorted((pos[x], pos[y]) for x in level for y in down[x])
+            # count inversions of the second coordinate (O(n^2) is fine here)
+            for i in range(len(pairs)):
+                for j in range(i + 1, len(pairs)):
+                    if pairs[i][0] < pairs[j][0] and pairs[i][1] > pairs[j][1]:
+                        total += 1
+        return total
+
+    best = [list(level) for level in layers]
+    best_score = crossings(best)
+    current = [list(level) for level in layers]
+    for sweep in range(sweeps):
+        pos = position_map(current)
+        rng = range(1, len(current)) if sweep % 2 == 0 else range(len(current) - 2, -1, -1)
+        for i in rng:
+            neighbours = up if sweep % 2 == 0 else down
+            def barycentre(node: str, i=i) -> float:
+                linked = [pos[x] for x in neighbours[node]]
+                # Same-layer partners count too, so a node sits beside them.
+                linked += [pos[x] + 0.5 for x in side[node]]
+                if not linked:
+                    return pos[node]
+                return sum(linked) / len(linked)
+            current[i].sort(key=barycentre)
+            for k, node in enumerate(current[i]):
+                pos[node] = k
+        score = crossings(current)
+        if score < best_score:
+            best, best_score = [list(level) for level in current], score
+            if score == 0:
+                break
+    layers = best
+
+    # -- 5. coordinates -----------------------------------------------------
+    size = {n: nodes.get(n, (0.0, 0.0)) for n in all_nodes}
+    widths = [max((size[n][0] for n in level), default=0) for level in layers]
+    xs: list[float] = []
+    cursor = 0.0
+    for w in widths:
+        xs.append(cursor + w / 2)
+        cursor += w + layer_gap
+
+    def gap_between(a: str, b: str) -> float:
+        dummy_a, dummy_b = a.startswith("\x00"), b.startswith("\x00")
+        pad = node_gap * (0.45 if dummy_a and dummy_b else 0.7 if (dummy_a or dummy_b) else 1)
+        return size[a][1] / 2 + size[b][1] / 2 + pad
+
+    y: dict[str, float] = {}
+    for level in layers:
+        cursor = 0.0
+        for k, node in enumerate(level):
+            if k:
+                cursor += gap_between(level[k - 1], node)
+            y[node] = cursor
+
+    def pack(level: list[str], wanted: dict[str, float]) -> None:
+        """Place nodes near their wanted y without overlap, preserving order."""
+        placed: list[float] = []
+        for k, node in enumerate(level):
+            value = wanted[node]
+            if k:
+                value = max(value, placed[-1] + gap_between(level[k - 1], node))
+            placed.append(value)
+        # shift the block so that its mean displacement is zero
+        shift = sum(wanted[n] - p for n, p in zip(level, placed)) / len(level)
+        for k in range(len(level) - 1, -1, -1):
+            candidate = placed[k] + shift
+            if k < len(level) - 1:
+                candidate = min(candidate, placed[k + 1] - gap_between(level[k], level[k + 1]))
+            placed[k] = candidate
+        for node, value in zip(level, placed):
+            y[node] = value
+
+    for iteration in range(24):
+        forward = iteration % 2 == 0
+        sequence = layers if forward else layers[::-1]
+        for level in sequence:
+            wanted = {}
+            for node in level:
+                linked = (up[node] if forward else down[node]) + \
+                         (down[node] if forward else up[node]) + side[node]
+                if linked:
+                    values = sorted(y[x] for x in linked)
+                    mid = len(values) // 2
+                    median = values[mid] if len(values) % 2 else (values[mid - 1] + values[mid]) / 2
+                    wanted[node] = 0.5 * y[node] + 0.5 * median
+                else:
+                    wanted[node] = y[node]
+            pack(level, wanted)
+
+    top = min(y[n] - size[n][1] / 2 for n in all_nodes)
+    positions = {n: (xs[layer[n]], y[n] - top) for n in ids}
+    routes: dict[int, list[tuple[float, float]]] = {}
+    for index, chain in chain_of.items():
+        routes[index] = [(xs[layer[n]], y[n] - top) for n in chain]
+    for index in same_layer:
+        a, b = edges[index]
+        routes[index] = [(xs[layer[a]], y[a] - top), (xs[layer[b]], y[b] - top)]
+    height = max(y[n] - top + size[n][1] / 2 for n in all_nodes)
+    return LayoutResult(positions, routes, xs[-1] + widths[-1] / 2, height)

openprocess/mining/log.py

@@ -0,0 +1,364 @@
+"""Event logs: the data every process mining technique starts from.
+
+Vocabulary (as in van der Aalst, *Process Mining*, ch. 2 and 5)
+---------------------------------------------------------------
+event
+    One recorded occurrence of an activity, carrying attributes such as the
+    activity name (``concept:name``), a timestamp (``time:timestamp``), a
+    resource (``org:resource``) and a lifecycle transition
+    (``lifecycle:transition``: *start*, *complete*, ...).
+trace (case)
+    The ordered list of events belonging to one process instance, e.g. one
+    passenger boarding a plane.  A trace also has attributes of its own; its
+    ``concept:name`` is the *case id*.
+event log
+    A collection of traces.
+
+Two views of the same log
+-------------------------
+The *rich* view (:class:`EventLog`) keeps every attribute, because the dotted
+chart, performance analysis and the case browser need timestamps and
+resources.
+
+Most discovery algorithms, however, only look at the *control-flow* view: each
+trace reduced to its sequence of activity names, and the log reduced to a
+**multiset of such sequences**, written in the course as::
+
+    L = [ <a,b,c,d>^3, <a,c,b,d>^2, <a,e,d> ]
+
+A multiset (not a set) because the same sequence can occur many times, and
+frequency matters for filtering and for the quality measures.  In Python a
+multiset is a :class:`collections.Counter`; we call it :data:`SimpleLog`.
+
+Large logs
+----------
+A log read with ``read_xes(path, columnar=True)`` (the default above a
+size threshold) keeps its events in a :class:`~.columns.ColumnStore`, one
+array per attribute, and ``traces`` is a :class:`~.columns.LazyTraces`
+that builds each ``Trace`` on first access.  The API is the same; the
+sequences, the event count and the variants come straight from the
+arrays, so discovery on a million events does not create a million
+objects.
+
+Classifiers
+-----------
+Which attribute(s) turn an event into an *activity label* is a choice, called
+the *event classifier* in XES.  The default is ``concept:name``.  A log that
+records both *start* and *complete* events (like the plane-boarding logs in
+the course) would, with the default classifier, show every activity twice in a
+row.  Two standard remedies are offered as ready-made classifiers:
+
+* keep only *complete* events and label them by name, or
+* label every event by ``name + lifecycle`` (so ``Move in+start`` and
+  ``Move in+complete`` become different activities).
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Iterable, Iterator
+
+#: The control-flow abstraction of a log: a multiset of activity sequences.
+SimpleLog = Counter  # Counter[tuple[str, ...]]
+
+# Standard XES attribute keys, named once so a typo is a NameError rather
+# than a silently empty column.
+KEY_NAME = "concept:name"
+KEY_TIME = "time:timestamp"
+KEY_LIFECYCLE = "lifecycle:transition"
+KEY_RESOURCE = "org:resource"
+
+
+# ---------------------------------------------------------------------------
+# Events and traces
+# ---------------------------------------------------------------------------
+@dataclass(slots=True)
+class Event:
+    """One event: a bag of typed attributes.
+
+    Attribute values are already converted to Python types by the reader:
+    ``str``, ``int``, ``float``, ``bool``, :class:`datetime`, or ``list`` for
+    XES list attributes.
+    """
+
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+    # Convenience accessors for the standard extensions --------------------
+    @property
+    def activity(self) -> str | None:
+        return self.attributes.get(KEY_NAME)
+
+    @property
+    def timestamp(self) -> datetime | None:
+        value = self.attributes.get(KEY_TIME)
+        return value if isinstance(value, datetime) else None
+
+    @property
+    def lifecycle(self) -> str | None:
+        return self.attributes.get(KEY_LIFECYCLE)
+
+    @property
+    def resource(self) -> str | None:
+        return self.attributes.get(KEY_RESOURCE)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.attributes.get(key, default)
+
+
+@dataclass(slots=True)
+class Trace:
+    """One case: trace-level attributes plus the ordered list of events."""
+
+    attributes: dict[str, Any] = field(default_factory=dict)
+    events: list[Event] = field(default_factory=list)
+
+    @property
+    def case_id(self) -> str:
+        value = self.attributes.get(KEY_NAME)
+        return "" if value is None else str(value)
+
+    def __len__(self) -> int:
+        return len(self.events)
+
+    def __iter__(self) -> Iterator[Event]:
+        return iter(self.events)
+
+    def __getitem__(self, index: int) -> Event:
+        return self.events[index]
+
+
+# ---------------------------------------------------------------------------
+# Classifiers
+# ---------------------------------------------------------------------------
+@dataclass(frozen=True)
+class Classifier:
+    """Maps an event to an activity label, optionally dropping some events.
+
+    Parameters
+    ----------
+    name:
+        Shown in the user interface.
+    keys:
+        Attribute keys whose values are joined with ``+`` to form the label.
+    lifecycles:
+        If given, only events whose ``lifecycle:transition`` is in this set
+        are kept (case-insensitive).  Events *without* a lifecycle attribute
+        are always kept: a log that never recorded lifecycles should not come
+        out empty.
+    """
+
+    name: str
+    keys: tuple[str, ...] = (KEY_NAME,)
+    lifecycles: frozenset[str] | None = None
+
+    def accepts(self, event: Event) -> bool:
+        if self.lifecycles is None:
+            return True
+        lifecycle = event.attributes.get(KEY_LIFECYCLE)
+        return lifecycle is None or str(lifecycle).lower() in self.lifecycles
+
+    def label(self, event: Event) -> str:
+        parts = [event.attributes.get(key) for key in self.keys]
+        return "+".join("" if part is None else str(part) for part in parts)
+
+
+#: Label by activity name, keep every event.
+BY_NAME = Classifier("Activity")
+#: Label by activity name, keep only *complete* events.
+BY_NAME_COMPLETE = Classifier("Activity (complete events)",
+                              lifecycles=frozenset({"complete"}))
+#: Label by activity name and lifecycle transition.
+BY_NAME_LIFECYCLE = Classifier("Activity + lifecycle", keys=(KEY_NAME, KEY_LIFECYCLE))
+
+
+# ---------------------------------------------------------------------------
+# The log
+# ---------------------------------------------------------------------------
+@dataclass
+class EventLog:
+    """A list of traces plus log-level metadata.
+
+    ``classifiers`` holds the classifiers declared in the XES file (if any) in
+    addition to the built-in ones; the GUI offers all of them.
+    """
+
+    traces: list[Trace] = field(default_factory=list)
+    attributes: dict[str, Any] = field(default_factory=dict)
+    extensions: list[dict[str, str]] = field(default_factory=list)
+    global_trace_attributes: dict[str, Any] = field(default_factory=dict)
+    global_event_attributes: dict[str, Any] = field(default_factory=dict)
+    declared_classifiers: list[Classifier] = field(default_factory=list)
+    source_path: str | None = None
+
+    # -- container protocol --------------------------------------------------
+    def __len__(self) -> int:
+        return len(self.traces)
+
+    def __iter__(self) -> Iterator[Trace]:
+        return iter(self.traces)
+
+    def __getitem__(self, index: int) -> Trace:
+        return self.traces[index]
+
+    @property
+    def name(self) -> str:
+        value = self.attributes.get(KEY_NAME)
+        if value:
+            return str(value)
+        if self.source_path:
+            from pathlib import Path
+            return Path(self.source_path).stem
+        return "Untitled log"
+
+    @property
+    def event_count(self) -> int:
+        lazy = getattr(self.traces, "event_count", None)
+        return lazy if lazy is not None else sum(len(trace) for trace in self.traces)
+
+    @property
+    def columnar(self) -> bool:
+        """Are the events kept in columns (a large log, read lazily)?"""
+        return hasattr(self.traces, "store") and not getattr(self.traces, "modified", True)
+
+    @classmethod
+    def from_columns(cls, store, **fields) -> "EventLog":
+        from .columns import LazyTraces
+        return cls(traces=LazyTraces(store), **fields)
+
+    # -- classifiers ------------------------------------------------------
+    def has_lifecycle_pairs(self) -> bool:
+        """Does the log record both *start* and *complete* events?"""
+        if self.columnar:
+            return self.traces.store.has_lifecycle_pairs()
+        seen: set[str] = set()
+        for trace in self.traces:
+            for event in trace:
+                lifecycle = event.attributes.get(KEY_LIFECYCLE)
+                if lifecycle is not None:
+                    seen.add(str(lifecycle).lower())
+                    if {"start", "complete"} <= seen:
+                        return True
+        return False
+
+    def default_classifier(self) -> Classifier:
+        """The most sensible classifier for control-flow discovery.
+
+        With start/complete pairs, the plain name classifier would produce a
+        self-loop on every activity, which is an artefact of logging, not of
+        the process.  Keeping complete events avoids that.
+        """
+        return BY_NAME_COMPLETE if self.has_lifecycle_pairs() else BY_NAME
+
+    def available_classifiers(self) -> list[Classifier]:
+        built_in = [BY_NAME, BY_NAME_COMPLETE, BY_NAME_LIFECYCLE]
+        names = {c.name for c in built_in}
+        extra = [c for c in self.declared_classifiers if c.name not in names]
+        return built_in + extra
+
+    # -- control-flow projections ----------------------------------------
+    def sequence(self, trace: Trace, classifier: Classifier | None = None) -> tuple[str, ...]:
+        """The activity sequence of one trace under ``classifier``."""
+        classifier = classifier or self.default_classifier()
+        return tuple(classifier.label(e) for e in trace.events if classifier.accepts(e))
+
+    def sequences(self, classifier: Classifier | None = None) -> list[tuple[str, ...]]:
+        """Activity sequences for every trace, in log order."""
+        classifier = classifier or self.default_classifier()
+        if self.columnar:
+            fast = self.traces.sequences(classifier.keys, classifier.lifecycles)
+            if fast is not None:
+                return fast
+        return [self.sequence(trace, classifier) for trace in self.traces]
+
+    def simple_log(self, classifier: Classifier | None = None) -> SimpleLog:
+        """The multiset of activity sequences: the input to discovery."""
+        return Counter(self.sequences(classifier))
+
+    def filtered(self, keep: Iterable[int]) -> "EventLog":
+        """A new log containing only the traces at the given indices."""
+        indices = list(keep)
+        return EventLog(
+            traces=[self.traces[i] for i in indices],
+            attributes=dict(self.attributes),
+            extensions=list(self.extensions),
+            global_trace_attributes=dict(self.global_trace_attributes),
+            global_event_attributes=dict(self.global_event_attributes),
+            declared_classifiers=list(self.declared_classifiers),
+            source_path=self.source_path,
+        )
+
+    # -- construction from a simple log ----------------------------------
+    @classmethod
+    def from_simple_log(cls, simple: SimpleLog, name: str = "Log") -> "EventLog":
+        """Expand a multiset of sequences into a full log (no timestamps).
+
+        Handy for textbook exercises: the course writes logs as multisets, and
+        this turns one into something every view in the app can display.
+        """
+        log = cls(attributes={KEY_NAME: name})
+        case = 0
+        for sequence, count in simple.items():
+            for _ in range(count):
+                case += 1
+                log.traces.append(Trace(
+                    attributes={KEY_NAME: f"case {case}"},
+                    events=[Event({KEY_NAME: activity}) for activity in sequence],
+                ))
+        return log
+
+
+# ---------------------------------------------------------------------------
+# Textbook notation
+# ---------------------------------------------------------------------------
+_TRACE_PATTERN = re.compile(r"<([^<>]*)>\s*(?:\^\s*(\d+))?")
+
+# The textbook and the slides typeset traces as ⟨a,b,c⟩³: angle brackets and
+# superscript counts.  Text copied from a PDF therefore arrives in that form.
+_TYPESET = str.maketrans({"⟨": "<", "⟩": ">", "〈": "<", "〉": ">", "‹": "<", "›": ">"})
+_SUPERSCRIPTS = re.compile("[⁰¹²³⁴⁵⁶⁷⁸⁹]+")
+_SUPERSCRIPT_DIGITS = str.maketrans("⁰¹²³⁴⁵⁶⁷⁸⁹", "0123456789")
+
+
+def parse_simple_log(text: str) -> SimpleLog:
+    """Parse the notation used in the course and the textbook.
+
+    Accepted forms (whitespace is free, the outer brackets are optional)::
+
+        [<a,b,c,d>^3, <a,c,b,d>^2, <a,e,d>]
+        [⟨a,b,c,d⟩³, ⟨a,c,b,d⟩², ⟨a,e,d⟩]    # as typeset in the book
+        [<>^2, <a>]                         # the empty trace is allowed
+
+    Activity names may contain spaces (``<register request, pay>``).  A
+    multiplicity defaults to 1.  Repeated sequences are added together, so
+    ``<a>, <a>`` is the same as ``<a>^2``; a multiplicity of 0 leaves the
+    trace out.
+
+    Raises ``ValueError`` if nothing trace-like is found, because silently
+    returning an empty log would make a typo look like a finding.
+    """
+    text = text.translate(_TYPESET)
+    text = _SUPERSCRIPTS.sub(lambda m: "^" + m.group().translate(_SUPERSCRIPT_DIGITS), text)
+    log: SimpleLog = Counter()
+    for match in _TRACE_PATTERN.finditer(text):
+        body, count = match.group(1), match.group(2)
+        activities = tuple(part.strip() for part in body.split(",") if part.strip())
+        log[activities] += int(count) if count else 1
+    log = Counter({trace: count for trace, count in log.items() if count > 0})
+    if not log:
+        raise ValueError("No traces found. Write traces as <a,b,c>^n, e.g. [<a,b,c>^3, <a,c>]")
+    return log
+
+
+def format_simple_log(log: SimpleLog, max_traces: int | None = None) -> str:
+    """The inverse of :func:`parse_simple_log`, most frequent first."""
+    items = sorted(log.items(), key=lambda item: (-item[1], item[0]))
+    if max_traces is not None:
+        items = items[:max_traces]
+    parts = []
+    for sequence, count in items:
+        body = ",".join(sequence)
+        parts.append(f"<{body}>" + (f"^{count}" if count != 1 else ""))
+    return "[" + ", ".join(parts) + "]"