openprocess 0.10.5__tar.gz → 0.11.0__tar.gz

{openprocess-0.10.5/openprocess.egg-info → openprocess-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openprocess
-Version: 0.10.5
+Version: 0.11.0
 Summary: Process mining, Petri nets and workflows in one open app: every algorithm visible, every result reproducible, every step teachable
 Author: Sam Struthers
 License: MIT
@@ -528,17 +528,19 @@ links to the definitions it builds on; **Help ▸ Definitions** lists them all.
   for bounded nets; for unbounded ones, up to a trace length (and it says
   so).
 
-| Process map | Discovering a model |
+| Process map | Discover in Mine →: the miner is a box, its result beside the canvas |
 |---|---|
 | ![Process map](docs/screenshots/studio-process-map.png) | ![Discover](docs/screenshots/studio-discover.png) |
 
-| α-algorithm result | Conformance (alignments on the model) |
+| α-algorithm result | *How*: the eight steps, from the footprint to α(L) |
 |---|---|
-| ![Alpha](docs/screenshots/studio-alpha.png) | ![Conformance](docs/screenshots/studio-conformance.png) |
+| ![Alpha](docs/screenshots/studio-alpha.png) | ![The eight steps of the α-algorithm](docs/screenshots/studio-alpha-how.png) |
 
-| Comparing two logs | Linked dotted charts of three boarding strategies |
+| Check fit: every score, and how it was computed | Comparing two logs |
 |---|---|
-| ![Comparing two logs](docs/screenshots/compare.png) | ![Linked dotted charts](docs/screenshots/compare-dotted.png) |
+| ![Conformance](docs/screenshots/studio-conformance.png) | ![Comparing two logs](docs/screenshots/compare.png) |
+
+![Linked dotted charts of two logs, one scale and one colour per activity](docs/screenshots/compare-dotted.png)
 
 The app follows the system's light or dark appearance:
 
@@ -555,6 +557,8 @@ sidebar, **Learn ▸ Open Exercise Pack…**, or **Learn ▸ Open Demo Exercises
 exercises): the window switches to a view made for working through a pack
 without distractions, and *Exit* brings your folder back exactly as it was.
 
+![An exercise in Learn: the worksheet with its answer boxes on the left, the exercise's log, given net and workflow on the right](docs/screenshots/learn-exercise.png)
+
 - **The worksheet** on the left is the question top to bottom, with an
   answer box wherever one is needed: yes/no, multiple choice, a set
   (`{a, b}`, sets of sets, or pairs like `({a}, {b,d})`), a number, a short
@@ -742,7 +746,10 @@ generated from `openprocess/mining/definitions.py`; after editing a definition,
 Likewise [`docs/references.md`](docs/references.md) — every source OpenProcess's
 notation and algorithms follow, also in the app under **Help ▸ References** —
 is generated from `openprocess/references.py` with
-`python -m openprocess.references > docs/references.md`.
+`python -m openprocess.references > docs/references.md`. The screenshots in
+this README come from the app itself: `python docs/make_screenshots.py`
+renders every page offscreen into `docs/screenshots/`, so run it after a
+change to the app's looks.
 
 The engines (`openprocess.mining`, `openprocess.ml`, `openprocess.sim`, `openprocess.analysis`)
 have **no dependencies**, so they work in a notebook or a script:
@@ -769,6 +776,10 @@ Miner, a fitness check), *Compare discovery* (three miners side by side),
 confidence* (bootstrap intervals, a test and a plot; needs the `science`
 extra) and *Predict the next activity*. Or start empty.
 
+| The canvas: *Compare discovery*, three miners side by side | Summary: every box's key figure, and the process map |
+|---|---|
+| ![The canvas of a Compare discovery analysis, the Compare box's table beside it](docs/screenshots/workflow-canvas.png) | ![The Summary view: a tile per box, the process map under them](docs/screenshots/workflow-summary.png) |
+
 - **The page is the canvas.** Its header has **Canvas | Summary**, then
   **+ Add box**, **Run ▶**, and **⋯** for Re-run, Record, Export experiment
   and Save. The sidebar beside it lists the folder's analyses and, folded
@@ -825,15 +836,29 @@ extra) and *Predict the next activity*. Or start empty.
   `boxes/`, so it is listed under *Yours* and can be used in any workflow.
 - **Export experiment** (under ⋯) writes a zip with the workflow file and its record,
   the inputs, your boxes, every result as a file (CSV, PNML, SVG, XES), a
-  `requirements.lock` and a README that says what was run: supplementary
-  material for a paper, which `openprocess run --check` can verify.
+  `requirements.lock`, a `run.py` that runs the same analysis as a plain
+  script, and a README that says what was run: supplementary material for a
+  paper, which `openprocess run --check` can verify. Drop such a zip on
+  OpenProcess and it is unpacked into a folder of its own and run again.
+- **Export as Python script** (under ⋯) writes the analysis as a `.py` file:
+  the same boxes, settings and connections, run with `python analysis.py`,
+  the results written beside it.
+- **Every result knows where it came from**: a figure saved as SVG carries
+  the analysis, the box, its settings and the result's fingerprint in its
+  metadata; a CSV gets a `.provenance.json` beside it.
+- **⌘Z and ⇧⌘Z** undo and redo on the canvas: boxes, connections, moves,
+  settings, groups.
 - **The side panel** resizes by dragging the gap beside it; double-click the
   gap, or *View ▸ Reset Workflow Layout*, for its default width.
 - **Connections** (at the bottom of the sidebar, or *View ▸ Connections*)
   draws what flows in, OpenProcess and its boxes, what flows out, and the
   optional tools (pandas, numpy, scipy, matplotlib, …) with whether each is
   installed, how to install it and the boxes it brings. All of it is read
-  from the box library.
+  from the box library. *Install…* works in the downloaded app too: it carries
+  pip and installs into a folder of your own (on a Mac,
+  `~/Library/Application Support/OpenProcess/packages`), and the boxes that
+  need the package come alive without a restart. PM4Py needs a Python
+  install (`pip install pm4py`), as parts of it are built from source.
 - **Motion** is kept short: a space switch, the side panel and Canvas ↔
   Summary settle in a fifth of a second, and a box pulses once when it
   finishes. `OPENPROCESS_NO_MOTION=1` turns it off.
@@ -969,6 +994,16 @@ Plainly stated:
 Next up: several instances of a subpage, CPN monitors, and signed apps that
 open without a security prompt.
 
+## Cite
+
+If OpenProcess helped with a course, a thesis or a paper, cite it. *Help ▸
+Cite OpenProcess…* in the app gives BibTeX and a one-line citation, and
+each algorithm's Code tab has *Cite* for the paper it follows. GitHub's
+*Cite this repository* reads [CITATION.cff](CITATION.cff). Releases are
+archived on Zenodo, which gives each version a DOI; the all-versions DOI
+goes into `CITATION.cff` (`doi:`) once the first release is archived, and
+the app's citations pick it up from there.
+
 ## Licence
 
 MIT. See [LICENSE](LICENSE).

{openprocess-0.10.5 → openprocess-0.11.0}/README.md

@@ -489,17 +489,19 @@ links to the definitions it builds on; **Help ▸ Definitions** lists them all.
   for bounded nets; for unbounded ones, up to a trace length (and it says
   so).
 
-| Process map | Discovering a model |
+| Process map | Discover in Mine →: the miner is a box, its result beside the canvas |
 |---|---|
 | ![Process map](docs/screenshots/studio-process-map.png) | ![Discover](docs/screenshots/studio-discover.png) |
 
-| α-algorithm result | Conformance (alignments on the model) |
+| α-algorithm result | *How*: the eight steps, from the footprint to α(L) |
 |---|---|
-| ![Alpha](docs/screenshots/studio-alpha.png) | ![Conformance](docs/screenshots/studio-conformance.png) |
+| ![Alpha](docs/screenshots/studio-alpha.png) | ![The eight steps of the α-algorithm](docs/screenshots/studio-alpha-how.png) |
 
-| Comparing two logs | Linked dotted charts of three boarding strategies |
+| Check fit: every score, and how it was computed | Comparing two logs |
 |---|---|
-| ![Comparing two logs](docs/screenshots/compare.png) | ![Linked dotted charts](docs/screenshots/compare-dotted.png) |
+| ![Conformance](docs/screenshots/studio-conformance.png) | ![Comparing two logs](docs/screenshots/compare.png) |
+
+![Linked dotted charts of two logs, one scale and one colour per activity](docs/screenshots/compare-dotted.png)
 
 The app follows the system's light or dark appearance:
 
@@ -516,6 +518,8 @@ sidebar, **Learn ▸ Open Exercise Pack…**, or **Learn ▸ Open Demo Exercises
 exercises): the window switches to a view made for working through a pack
 without distractions, and *Exit* brings your folder back exactly as it was.
 
+![An exercise in Learn: the worksheet with its answer boxes on the left, the exercise's log, given net and workflow on the right](docs/screenshots/learn-exercise.png)
+
 - **The worksheet** on the left is the question top to bottom, with an
   answer box wherever one is needed: yes/no, multiple choice, a set
   (`{a, b}`, sets of sets, or pairs like `({a}, {b,d})`), a number, a short
@@ -703,7 +707,10 @@ generated from `openprocess/mining/definitions.py`; after editing a definition,
 Likewise [`docs/references.md`](docs/references.md) — every source OpenProcess's
 notation and algorithms follow, also in the app under **Help ▸ References** —
 is generated from `openprocess/references.py` with
-`python -m openprocess.references > docs/references.md`.
+`python -m openprocess.references > docs/references.md`. The screenshots in
+this README come from the app itself: `python docs/make_screenshots.py`
+renders every page offscreen into `docs/screenshots/`, so run it after a
+change to the app's looks.
 
 The engines (`openprocess.mining`, `openprocess.ml`, `openprocess.sim`, `openprocess.analysis`)
 have **no dependencies**, so they work in a notebook or a script:
@@ -730,6 +737,10 @@ Miner, a fitness check), *Compare discovery* (three miners side by side),
 confidence* (bootstrap intervals, a test and a plot; needs the `science`
 extra) and *Predict the next activity*. Or start empty.
 
+| The canvas: *Compare discovery*, three miners side by side | Summary: every box's key figure, and the process map |
+|---|---|
+| ![The canvas of a Compare discovery analysis, the Compare box's table beside it](docs/screenshots/workflow-canvas.png) | ![The Summary view: a tile per box, the process map under them](docs/screenshots/workflow-summary.png) |
+
 - **The page is the canvas.** Its header has **Canvas | Summary**, then
   **+ Add box**, **Run ▶**, and **⋯** for Re-run, Record, Export experiment
   and Save. The sidebar beside it lists the folder's analyses and, folded
@@ -786,15 +797,29 @@ extra) and *Predict the next activity*. Or start empty.
   `boxes/`, so it is listed under *Yours* and can be used in any workflow.
 - **Export experiment** (under ⋯) writes a zip with the workflow file and its record,
   the inputs, your boxes, every result as a file (CSV, PNML, SVG, XES), a
-  `requirements.lock` and a README that says what was run: supplementary
-  material for a paper, which `openprocess run --check` can verify.
+  `requirements.lock`, a `run.py` that runs the same analysis as a plain
+  script, and a README that says what was run: supplementary material for a
+  paper, which `openprocess run --check` can verify. Drop such a zip on
+  OpenProcess and it is unpacked into a folder of its own and run again.
+- **Export as Python script** (under ⋯) writes the analysis as a `.py` file:
+  the same boxes, settings and connections, run with `python analysis.py`,
+  the results written beside it.
+- **Every result knows where it came from**: a figure saved as SVG carries
+  the analysis, the box, its settings and the result's fingerprint in its
+  metadata; a CSV gets a `.provenance.json` beside it.
+- **⌘Z and ⇧⌘Z** undo and redo on the canvas: boxes, connections, moves,
+  settings, groups.
 - **The side panel** resizes by dragging the gap beside it; double-click the
   gap, or *View ▸ Reset Workflow Layout*, for its default width.
 - **Connections** (at the bottom of the sidebar, or *View ▸ Connections*)
   draws what flows in, OpenProcess and its boxes, what flows out, and the
   optional tools (pandas, numpy, scipy, matplotlib, …) with whether each is
   installed, how to install it and the boxes it brings. All of it is read
-  from the box library.
+  from the box library. *Install…* works in the downloaded app too: it carries
+  pip and installs into a folder of your own (on a Mac,
+  `~/Library/Application Support/OpenProcess/packages`), and the boxes that
+  need the package come alive without a restart. PM4Py needs a Python
+  install (`pip install pm4py`), as parts of it are built from source.
 - **Motion** is kept short: a space switch, the side panel and Canvas ↔
   Summary settle in a fifth of a second, and a box pulses once when it
   finishes. `OPENPROCESS_NO_MOTION=1` turns it off.
@@ -930,6 +955,16 @@ Plainly stated:
 Next up: several instances of a subpage, CPN monitors, and signed apps that
 open without a security prompt.
 
+## Cite
+
+If OpenProcess helped with a course, a thesis or a paper, cite it. *Help ▸
+Cite OpenProcess…* in the app gives BibTeX and a one-line citation, and
+each algorithm's Code tab has *Cite* for the paper it follows. GitHub's
+*Cite this repository* reads [CITATION.cff](CITATION.cff). Releases are
+archived on Zenodo, which gives each version a DOI; the all-versions DOI
+goes into `CITATION.cff` (`doi:`) once the first release is archived, and
+the app's citations pick it up from there.
+
 ## Licence
 
 MIT. See [LICENSE](LICENSE).

{openprocess-0.10.5 → openprocess-0.11.0}/openprocess/__init__.py

@@ -48,7 +48,7 @@ from .sim.simulator import Simulator
 #: The one place the version number is written (pyproject.toml, the update
 #: check and packaging/build.py read it from here).  A release is tagged
 #: "v" + this, e.g. v0.2.0.
-__version__ = "0.10.5"
+__version__ = "0.11.0"
 
 __all__ = [
     "Arc", "BindingElement", "CPNet", "Marking", "Multiset", "Page", "Place",

{openprocess-0.10.5 → openprocess-0.11.0}/openprocess/citation.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import datetime as _dt
 import re
 from dataclasses import dataclass, field
+from pathlib import Path
 
 from . import references as _references
 
@@ -27,6 +28,23 @@ def app_version() -> str:
     return __version__
 
 
+def concept_doi() -> str:
+    """The DOI Zenodo gives the software (all versions), from ``CITATION.cff``
+    at the top of the repository or installed beside the package; "" until
+    the first release is archived."""
+    import re
+    for candidate in (Path(__file__).resolve().parents[1] / "CITATION.cff",
+                      Path(__file__).resolve().parent / "CITATION.cff"):
+        try:
+            text = candidate.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        found = re.search(r"^doi:\s*(\S+)\s*$", text, re.M)
+        if found:
+            return found.group(1).strip("'\"")
+    return ""
+
+
 # ---------------------------------------------------------------------------
 # One entry
 # ---------------------------------------------------------------------------
@@ -137,45 +155,54 @@ def entries_for_module(module: str) -> list[Entry]:
 # ---------------------------------------------------------------------------
 # The app itself
 # ---------------------------------------------------------------------------
-def app_entry(version: str | None = None, year: int | None = None) -> Entry:
+def app_entry(version: str | None = None, year: int | None = None, doi: str | None = None) -> Entry:
     version = version or app_version()
     year = year or _dt.date.today().year
+    doi = concept_doi() if doi is None else doi
     return Entry("software", "openprocess", {
         "author": " and ".join(f"{last}, {first}" for last, first in APP_AUTHORS),
         "title": APP_TITLE,
         "version": version,
         "year": str(year),
+        "doi": doi,
         "url": APP_URL,
         "note": "Every algorithm shows its code and the paper it follows; every analysis keeps a record "
                 "that runs again",
     })
 
 
-def app_bibtex(version: str | None = None, year: int | None = None) -> str:
-    return app_entry(version, year).bibtex()
+def app_bibtex(version: str | None = None, year: int | None = None, doi: str | None = None) -> str:
+    return app_entry(version, year, doi).bibtex()
 
 
-def app_text(version: str | None = None, year: int | None = None) -> str:
+def app_text(version: str | None = None, year: int | None = None, doi: str | None = None) -> str:
     """The citation in one line, as a reference list would have it."""
     version = version or app_version()
     year = year or _dt.date.today().year
+    doi = concept_doi() if doi is None else doi
     authors = ", ".join(f"{first} {last}" for last, first in APP_AUTHORS)
-    return f"{authors}. {APP_TITLE} (version {version}) [software], {year}. {APP_URL}"
+    where = f"https://doi.org/{doi}" if doi else APP_URL
+    return f"{authors}. {APP_TITLE} (version {version}) [software], {year}. {where}"
 
 
-def cff_text(version: str | None = None, released: _dt.date | None = None) -> str:
-    """The contents of ``CITATION.cff`` (Citation File Format 1.2.0) for ``version``."""
+def cff_text(version: str | None = None, released: _dt.date | None = None, doi: str = "") -> str:
+    """The contents of ``CITATION.cff`` (Citation File Format 1.2.0) for
+    ``version``; ``doi`` is Zenodo's concept DOI once the first release is archived."""
     version = version or app_version()
     released = released or _dt.date.today()
     authors = "\n".join(f"  - family-names: {last}\n    given-names: {first}" for last, first in APP_AUTHORS)
+    def quoted(text: str) -> str:               # a YAML string: a colon in the title would otherwise break it
+        return '"' + text.replace('\\', '\\\\').replace('"', '\\"') + '"'
+
     return (
         "cff-version: 1.2.0\n"
-        "message: If you use OpenProcess in teaching or research, please cite it as below.\n"
+        f"message: {quoted('If you use OpenProcess in teaching or research, please cite it as below.')}\n"
         "type: software\n"
-        f"title: {APP_TITLE}\n"
+        f"title: {quoted(APP_TITLE)}\n"
         f"version: {version}\n"
         f"date-released: {released.isoformat()}\n"
-        f"repository-code: {APP_URL}\n"
+        + (f"doi: {doi}\n" if doi else "")
+        + f"repository-code: {APP_URL}\n"
         f"url: {APP_URL}\n"
         "license: MIT\n"
         "keywords:\n  - process mining\n  - Petri nets\n  - workflow nets\n  - conformance checking\n"

{openprocess-0.10.5 → openprocess-0.11.0}/openprocess/flow/__init__.py

@@ -35,12 +35,13 @@ from .library import Library, library_for, standard_library
 from .record import check, differences, load, save
 from .runner import Cache, Result, Run, Runner
 from .sweep import Sweep
-from .types import (AlignmentResult, Any, CPNet, DFG, Dataset, EventLog, Figure, Footprint, Marking,
+from .types import (Column, AlignmentResult, Any, CPNet, DFG, Dataset, EventLog, Figure, Footprint, Marking,
                     PetriNet, Predictions, Predictor, ProcessTree, Regions, ReplayResult, Scores,
                     SimpleLog, Table, Text, TransitionSystem, register_type)
 from .workflow import Edge, Group, Node, Workflow, WorkflowError, to_python, workflow
 
 __all__ = [
+    "Column",
     "AlignmentResult", "Any", "Box", "BoxError", "BoxSpec", "CPNet", "Cache", "DFG", "Dataset", "Edge",
     "EventLog", "Explanation", "Figure", "Footprint", "Group", "Library", "Marking", "Node", "PetriNet",
     "Port", "Predictions", "Predictor", "ProcessTree", "Regions", "ReplayResult", "Result", "Run",

{openprocess-0.10.5 → openprocess-0.11.0}/openprocess/flow/box.py

@@ -18,6 +18,7 @@ parameters whose type is a OpenProcess type             input connection points,
 the return type                                   the output; a dataclass of typed fields gives several
 ``int``, ``float``, ``bool``, ``str`` with a default  a setting, with the default as its value
 ``Literal["a", "b"]``                             a setting that is a choice
+``Column``                                        a setting that is a column of a connected table
 ``Path``                                          a setting that is a file in the folder
 the docstring                                     the help text
 ``inspect.getsource``                             the Code tab
@@ -44,7 +45,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Callable, Literal, Union, get_args, get_origin, get_type_hints
 
-from .types import TypeInfo, is_known, type_info
+from .types import Column, TypeInfo, is_known, type_info
 
 SETTING_TYPES = (int, float, bool, str)
 
@@ -106,7 +107,7 @@ class Setting:
     """A parameter that is not an input: shown as a control in the side panel."""
 
     name: str
-    kind: str                        # "int", "float", "bool", "str", "choice", "path"
+    kind: str                        # "int", "float", "bool", "str", "choice", "path", "column"
     default: Any
     choices: tuple = ()
     help: str = ""
@@ -273,12 +274,14 @@ def _setting_from(name: str, annotation, default, has_default: bool, doc_hints:
         kind = "int"
     elif annotation is float:
         kind = "float"
+    elif annotation is Column:
+        kind = "column"
     elif annotation is str:
         kind = "str"
     else:
         raise BoxError(
             f"parameter {name!r} has type {_type_text(annotation)}, which is neither a OpenProcess "
-            f"type (an input) nor int, float, bool, str, Literal[...] or Path (a setting)")
+            f"type (an input) nor int, float, bool, str, Literal[...], Column or Path (a setting)")
     if not has_default:
         raise BoxError(f"setting {name!r} needs a default value (e.g. {name}: {kind} = ...)")
     if kind == "float" and isinstance(default, int) and not isinstance(default, bool):

{openprocess-0.10.5 → openprocess-0.11.0}/openprocess/flow/boxes/science.py

@@ -17,7 +17,7 @@ from ...mining.log import EventLog
 from ...mining.petrinet import PetriNet
 from ..box import box
 from ..convert import convert
-from ..types import Figure, Scores, Table
+from ..types import Column, Figure, Scores, Table
 
 
 @box(name="Describe log", group="Science", needs="pandas")
@@ -109,12 +109,14 @@ def correlate(table: Table) -> Table:
 
 @box(name="Plot", group="Science", needs="matplotlib")
 def plot(scores: list[Scores] = (), tables: list[Table] = (),
-         x: str = "", y: str = "") -> Figure:
-    """Bars per model for scores, histograms for bootstrap tables, or a line
-    of column *y* against column *x* of a table (a sweep). The figure is a
+         x: Column = "", y: Column = "") -> Figure:
+    """Bars per model for scores, histograms for bootstrap tables, or column
+    *y* of a table against column *x*: bars when *x* holds names (a model per
+    bar), a line when it holds numbers (a sweep). Once *x* and *y* are set
+    they decide the figure, whatever else is connected. The figure is a
     matplotlib figure, converted to SVG; its code is this box's code.
 
-    x: a column of the table to put on the x axis (lines only)
+    x: a column of the table to put on the x axis
     y: the column to plot against it
     """
     import matplotlib
@@ -122,7 +124,24 @@ def plot(scores: list[Scores] = (), tables: list[Table] = (),
     import matplotlib.pyplot as plt
     fig, ax = plt.subplots(figsize=(5.5, 3.2))
     scores, tables = list(scores), list(tables)
-    if scores:
+    if tables and x and y:
+        for table in tables:
+            for name in (x, y):
+                if name not in table.columns:
+                    raise ValueError(f"{table.name} has no column {name!r}; it has {', '.join(table.columns)}")
+        numeric = all(isinstance(v, (int, float)) and not isinstance(v, bool) for t in tables for v in t.column(x))
+        for table in tables:
+            values = [float(v) for v in table.column(y)]
+            if numeric:
+                ax.plot(table.column(x), values, marker="o", label=table.name)
+            else:
+                ax.bar([str(v) for v in table.column(x)], values, label=table.name)
+        ax.set_xlabel(x)
+        ax.set_ylabel(y)
+        if len(tables) > 1:
+            ax.legend(fontsize=8)
+        caption = f"{y} against {x}."
+    elif scores:
         metrics = [m for m in dict.fromkeys(k for s in scores for k in s.metrics)
                    if all(isinstance(s.metrics.get(m, 0.0), (int, float)) for s in scores)]
         width = 0.8 / max(1, len(metrics))
@@ -134,14 +153,6 @@ def plot(scores: list[Scores] = (), tables: list[Table] = (),
         ax.set_ylim(0, 1.05)
         ax.legend(fontsize=8)
         caption = f"{len(scores)} models, {len(metrics)} scores each."
-    elif tables and x and y:
-        for table in tables:
-            ax.plot(table.column(x), table.column(y), marker="o", label=table.name)
-        ax.set_xlabel(x)
-        ax.set_ylabel(y)
-        if len(tables) > 1:
-            ax.legend(fontsize=8)
-        caption = f"{y} against {x}."
     elif tables:
         for table in tables:
             if table.samples:
@@ -150,7 +161,7 @@ def plot(scores: list[Scores] = (), tables: list[Table] = (),
         ax.legend(fontsize=8)
         caption = f"{len(tables)} bootstrap distribution{'s' if len(tables) != 1 else ''}."
     else:
-        raise ValueError("Connect scores, or tables with samples or an x and y column")
+        raise ValueError("Connect scores, or tables with samples, or a table and set both x and y")
     fig.tight_layout()
     figure = convert(fig, Figure)
     plt.close(fig)

openprocess-0.11.0/openprocess/flow/history.py

@@ -0,0 +1,113 @@
+"""Undo and redo for a workflow, by snapshots.
+
+A workflow is small (its dict form, :meth:`Workflow.to_dict`, is a few
+kilobytes), so every change keeps the whole state before it: adding,
+removing, wiring, moving or grouping boxes, a setting, a rename.  Undo puts
+a snapshot back; the page then runs the boxes again, and the cache serves
+the ones that did not change.  Snapshots are taken where the page already
+learns of a change, so no edit is instrumented by hand, and a box author
+never sees any of this.
+"""
+
+from __future__ import annotations
+
+import time
+
+#: How many steps back are kept.
+LIMIT = 100
+#: A drag arrives as several moves; those within this many seconds are one step.
+MOVE_SECONDS = 1.5
+
+
+def describe(before: dict, after: dict) -> str:
+    """What changed from ``before`` to ``after``, for "Undo adding a box"."""
+    b = {n["id"]: n for n in before.get("boxes", [])}
+    a = {n["id"]: n for n in after.get("boxes", [])}
+    added, removed = set(a) - set(b), set(b) - set(a)
+    if added:
+        return "adding a box" if len(added) == 1 else f"adding {len(added)} boxes"
+    if removed:
+        return "removing a box" if len(removed) == 1 else f"removing {len(removed)} boxes"
+    if before.get("connections") != after.get("connections"):
+        return "a connection"
+    if before.get("groups") != after.get("groups"):
+        return "grouping"
+    for node_id in a:
+        if a[node_id].get("settings") != b[node_id].get("settings"):
+            return "a setting"
+        if a[node_id].get("title", "") != b[node_id].get("title", ""):
+            return "a rename"
+    if any(a[i].get("position") != b[i].get("position") for i in a):
+        return "a move"
+    if any(a[i].get("layout") != b[i].get("layout") for i in a):
+        return "tidying a drawing"
+    if before.get("name") != after.get("name"):
+        return "a rename"
+    return "a change"
+
+
+class History:
+    """The states a workflow went through; :attr:`state` is the current one."""
+
+    def __init__(self, snapshot: dict, limit: int = LIMIT) -> None:
+        self.state = snapshot
+        self.limit = limit
+        self.undo_stack: list[dict] = []
+        self.redo_stack: list[dict] = []
+        self._last: tuple[str | None, float] = (None, 0.0)
+
+    def record(self, snapshot: dict, kind: str = "change", now: float | None = None) -> bool:
+        """The workflow is now ``snapshot``; the state before it becomes undoable.
+        Returns whether anything changed.  ``kind`` "move" folds a drag's
+        steps into one."""
+        if snapshot == self.state:
+            return False
+        now = time.monotonic() if now is None else now
+        last_kind, last_time = self._last
+        if not (kind == "move" and last_kind == "move" and now - last_time < MOVE_SECONDS and self.undo_stack):
+            self.undo_stack.append(self.state)
+            del self.undo_stack[:-self.limit]
+        self.redo_stack.clear()
+        self.state = snapshot
+        self._last = (kind, now)
+        return True
+
+    @property
+    def can_undo(self) -> bool:
+        return bool(self.undo_stack)
+
+    @property
+    def can_redo(self) -> bool:
+        return bool(self.redo_stack)
+
+    @property
+    def undo_label(self) -> str:
+        return describe(self.undo_stack[-1], self.state) if self.undo_stack else ""
+
+    @property
+    def redo_label(self) -> str:
+        return describe(self.state, self.redo_stack[-1]) if self.redo_stack else ""
+
+    def undo(self) -> tuple[str, dict] | None:
+        """Step back: (what is undone, the state to restore), or None."""
+        if not self.undo_stack:
+            return None
+        before = self.undo_stack.pop()
+        label = describe(before, self.state)
+        self.redo_stack.append(self.state)
+        self.state = before
+        self._last = (None, 0.0)
+        return label, before
+
+    def redo(self) -> tuple[str, dict] | None:
+        if not self.redo_stack:
+            return None
+        after = self.redo_stack.pop()
+        label = describe(self.state, after)
+        self.undo_stack.append(self.state)
+        self.state = after
+        self._last = (None, 0.0)
+        return label, after
+
+
+__all__ = ["History", "describe", "LIMIT", "MOVE_SECONDS"]