openprocess 0.11.3__tar.gz → 0.12.1__tar.gz

{openprocess-0.11.3/openprocess.egg-info → openprocess-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openprocess
-Version: 0.11.3
+Version: 0.12.1
 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
@@ -766,9 +766,11 @@ report = check_soundness(net)
 print(report.sound, report.findings)
 ```
 
-[**docs/how-it-works.md**](docs/how-it-works.md) covers the architecture, the
-CPN ML subset, binding search, timed nets, the state space, the file format
-and the project layout. [**docs/design.md**](docs/design.md) is the *why*:
+[**docs/architecture.md**](docs/architecture.md) maps the code: its four
+layers, which package imports which (drawn from the code, and checked), how a
+workflow runs, and every module. [**docs/how-it-works.md**](docs/how-it-works.md)
+covers the CPN ML subset, binding search, timed nets, the state space and
+the file format. [**docs/design.md**](docs/design.md) is the *why*:
 the problem, the claim, the three ideas and the decisions that follow from
 them. `tests/cross_check_inductive_miner.py` compares the built-in Inductive
 Miner with PM4Py's on hundreds of logs and reports where they differ.
@@ -791,8 +793,8 @@ extra) and *Predict the next activity*. Or start empty.
   and Save. The sidebar beside it lists the folder's analyses and, folded
   under them, its logs.
 - **+ Add box** (or a double-click on the canvas) opens every box, one
-  section per group (Input, Filter, Discover, Check, Compare, Output, then
-  Science, Predict, Coloured nets, Sweep and your own boxes), in a list that
+  section per group (Input, Filter, Discover, Check, Measure, Compare, Output,
+  then Science, Predict, Coloured nets, Sweep and your own boxes), in a list that
   scrolls. Under *Input*, **the folder's own files**: one click adds the box
   that reads the file, already set. Type to search them all: "alpha" finds
   the α-algorithm, "boarding" the log; Enter adds the first match.
@@ -853,8 +855,29 @@ extra) and *Predict the next activity*. Or start empty.
   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.
+- **The side panel** resizes by dragging the gap beside it, never narrower
+  than what it shows; double-click the gap, or *View ▸ Reset Workflow Layout*,
+  for its default size. Its dock button (or *View ▸ Workflow Panel Under the
+  Canvas*) moves it under the canvas, where a wide table or the code has the
+  window's width; the app remembers where you put it.
+- **Alignments** are drawn as ProM draws them: the log on the model (per
+  transition, ✓ synchronous moves and » model moves, its colour from green,
+  always matched, to purple, often skipped; *n* » log moves at the activity),
+  and every variant's alignment as a row of chevrons: green synchronous,
+  yellow log move, purple model move, black τ. On a large log, the box's
+  *variants* setting aligns the most frequent ones and says what share of the
+  cases they cover.
+- **Measure** boxes answer the questions an audit asks, for every case: *Time
+  between* two activities (throughput), *Order rule* (does the payment block
+  go before the goods receipt?), *Segregation of duties* (who both recorded
+  and cleared an invoice?) and *Compliance by attribute* (per vendor: cases,
+  share that fits, value), with *Case attribute* to keep one category and
+  *Bubble chart* to draw it. [examples/bpi2019](examples/bpi2019/README.md)
+  uses them on the BPI Challenge 2019. *Dotted chart* saves a dotted chart
+  as a figure (the same dots as the log page's tab), and *Who does what*
+  counts each activity per resource;
+  [examples/energy_contracts](examples/energy_contracts/README.md) uses them
+  with the course's miners and checks on the 2AMI10 exam log.
 - **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
@@ -896,7 +919,7 @@ save(wf, "orders.cpnflow", run)
 ```bash
 openprocess run orders.cpnflow --check     # re-run; fails if any result differs from the record
 openprocess run orders.cpnflow --sweep noise=0..0.5 step 0.1
-openprocess boxes                          # the 47 boxes, with a folder's boxes/
+openprocess boxes                          # every box (listed in docs/boxes.md), with a folder's boxes/
 openprocess datasets list                  # the BPI Challenge, Sepsis, ... logs by name
 ```
 
@@ -912,11 +935,22 @@ def last_two(log: EventLog, representation: str = "multiset") -> TransitionSyste
 ```
 
 `pip install -e ".[science]"` adds the pandas, NumPy, SciPy and matplotlib
-boxes (describe, bootstrap intervals, tests, plots). Large logs are read
-into columns rather than objects, so a million events fit in memory.
-[**docs/workflows.md**](docs/workflows.md) has the whole framework: writing
-a box, the types, the *How* tab, sweeps, the prediction pipeline, the
-record and running in CI.
+boxes (describe, bootstrap intervals, tests, plots).
+
+**Large logs.** A log above 20 MB is read into columns rather than objects,
+and everything that looks at every event reads the columns: the BPI
+Challenge 2019 log (251,734 cases, 1.6 million events, 728 MB) opens in
+about 12 seconds and 250 MB, every tab of its log page in a few seconds, and
+the whole [BPI 2019 analysis](examples/bpi2019/README.md), from reading the
+file to the last chart, runs in about two minutes.
+
+[**docs/workflows.md**](docs/workflows.md) is the tutorial: writing a box,
+the types, the *How* tab, sweeps, the prediction pipeline, the record and
+running in CI. [**docs/framework.md**](docs/framework.md) is the
+specification: what a box, a workflow and a run are, what a fingerprint
+covers and what a reproduced result promises. [**docs/architecture.md**](docs/architecture.md)
+maps the code, drawn from its imports, and [**docs/boxes.md**](docs/boxes.md)
+lists every box.
 
 **Building the apps.** `packaging/` turns OpenProcess into a standalone app with
 PyInstaller. In the environment:
@@ -939,11 +973,20 @@ workflow* on the Actions tab.
    [CHANGELOG.md](CHANGELOG.md) (`## 0.4.0`, then a few bullet points). Write
    it for the people using the app: it becomes the text of the release on
    GitHub, and the app shows it when it offers the update.
-2. Set `__version__` in `openprocess/__init__.py` to the same version and merge
-   both into `main`. It is the only place the version is written:
-   `pyproject.toml`, the download names and the app's update check all read
-   it from there.
-3. Tag that commit with the same version and push the tag:
+2. Bring the documentation up to date with the code:
+   - run `python docs/make_docs.py`, which rewrites the code map in
+     [docs/architecture.md](docs/architecture.md) and the box catalogue in
+     [docs/boxes.md](docs/boxes.md) (the test suite, and so the release
+     build, fails while they are out of date, and when a package imports
+     across its layer);
+   - read [docs/framework.md](docs/framework.md) against what changed in
+     `openprocess/flow` (a test fails when a public name is not described
+     there, but only you can tell whether a description is still right).
+3. Set `__version__` in `openprocess/__init__.py` and `version` and
+   `date-released` in `CITATION.cff` to the same version, and merge them into
+   `main`. `pyproject.toml`, the download names and the app's update check
+   all read the version from `__version__`.
+4. Tag that commit with the same version and push the tag:
 
    ```bash
    git pull
@@ -954,8 +997,8 @@ workflow* on the Actions tab.
 About five minutes later the
 [Releases page](https://github.com/s4mstruthers/openprocess/releases) has the
 macOS (Apple silicon and Intel), Windows and Linux apps. The build refuses a
-tag that does not match `__version__`, or a version with no section in
-`CHANGELOG.md`.
+tag that does not match `__version__`, a version with no section in
+`CHANGELOG.md`, and code whose tests fail, stale documentation included.
 
 **Updates.** Each time it opens, the app checks the latest release on GitHub
 (*Settings* turns that off). If there is a newer version, a slim bar at the

{openprocess-0.11.3 → openprocess-0.12.1}/README.md

@@ -727,9 +727,11 @@ report = check_soundness(net)
 print(report.sound, report.findings)
 ```
 
-[**docs/how-it-works.md**](docs/how-it-works.md) covers the architecture, the
-CPN ML subset, binding search, timed nets, the state space, the file format
-and the project layout. [**docs/design.md**](docs/design.md) is the *why*:
+[**docs/architecture.md**](docs/architecture.md) maps the code: its four
+layers, which package imports which (drawn from the code, and checked), how a
+workflow runs, and every module. [**docs/how-it-works.md**](docs/how-it-works.md)
+covers the CPN ML subset, binding search, timed nets, the state space and
+the file format. [**docs/design.md**](docs/design.md) is the *why*:
 the problem, the claim, the three ideas and the decisions that follow from
 them. `tests/cross_check_inductive_miner.py` compares the built-in Inductive
 Miner with PM4Py's on hundreds of logs and reports where they differ.
@@ -752,8 +754,8 @@ extra) and *Predict the next activity*. Or start empty.
   and Save. The sidebar beside it lists the folder's analyses and, folded
   under them, its logs.
 - **+ Add box** (or a double-click on the canvas) opens every box, one
-  section per group (Input, Filter, Discover, Check, Compare, Output, then
-  Science, Predict, Coloured nets, Sweep and your own boxes), in a list that
+  section per group (Input, Filter, Discover, Check, Measure, Compare, Output,
+  then Science, Predict, Coloured nets, Sweep and your own boxes), in a list that
   scrolls. Under *Input*, **the folder's own files**: one click adds the box
   that reads the file, already set. Type to search them all: "alpha" finds
   the α-algorithm, "boarding" the log; Enter adds the first match.
@@ -814,8 +816,29 @@ extra) and *Predict the next activity*. Or start empty.
   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.
+- **The side panel** resizes by dragging the gap beside it, never narrower
+  than what it shows; double-click the gap, or *View ▸ Reset Workflow Layout*,
+  for its default size. Its dock button (or *View ▸ Workflow Panel Under the
+  Canvas*) moves it under the canvas, where a wide table or the code has the
+  window's width; the app remembers where you put it.
+- **Alignments** are drawn as ProM draws them: the log on the model (per
+  transition, ✓ synchronous moves and » model moves, its colour from green,
+  always matched, to purple, often skipped; *n* » log moves at the activity),
+  and every variant's alignment as a row of chevrons: green synchronous,
+  yellow log move, purple model move, black τ. On a large log, the box's
+  *variants* setting aligns the most frequent ones and says what share of the
+  cases they cover.
+- **Measure** boxes answer the questions an audit asks, for every case: *Time
+  between* two activities (throughput), *Order rule* (does the payment block
+  go before the goods receipt?), *Segregation of duties* (who both recorded
+  and cleared an invoice?) and *Compliance by attribute* (per vendor: cases,
+  share that fits, value), with *Case attribute* to keep one category and
+  *Bubble chart* to draw it. [examples/bpi2019](examples/bpi2019/README.md)
+  uses them on the BPI Challenge 2019. *Dotted chart* saves a dotted chart
+  as a figure (the same dots as the log page's tab), and *Who does what*
+  counts each activity per resource;
+  [examples/energy_contracts](examples/energy_contracts/README.md) uses them
+  with the course's miners and checks on the 2AMI10 exam log.
 - **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
@@ -857,7 +880,7 @@ save(wf, "orders.cpnflow", run)
 ```bash
 openprocess run orders.cpnflow --check     # re-run; fails if any result differs from the record
 openprocess run orders.cpnflow --sweep noise=0..0.5 step 0.1
-openprocess boxes                          # the 47 boxes, with a folder's boxes/
+openprocess boxes                          # every box (listed in docs/boxes.md), with a folder's boxes/
 openprocess datasets list                  # the BPI Challenge, Sepsis, ... logs by name
 ```
 
@@ -873,11 +896,22 @@ def last_two(log: EventLog, representation: str = "multiset") -> TransitionSyste
 ```
 
 `pip install -e ".[science]"` adds the pandas, NumPy, SciPy and matplotlib
-boxes (describe, bootstrap intervals, tests, plots). Large logs are read
-into columns rather than objects, so a million events fit in memory.
-[**docs/workflows.md**](docs/workflows.md) has the whole framework: writing
-a box, the types, the *How* tab, sweeps, the prediction pipeline, the
-record and running in CI.
+boxes (describe, bootstrap intervals, tests, plots).
+
+**Large logs.** A log above 20 MB is read into columns rather than objects,
+and everything that looks at every event reads the columns: the BPI
+Challenge 2019 log (251,734 cases, 1.6 million events, 728 MB) opens in
+about 12 seconds and 250 MB, every tab of its log page in a few seconds, and
+the whole [BPI 2019 analysis](examples/bpi2019/README.md), from reading the
+file to the last chart, runs in about two minutes.
+
+[**docs/workflows.md**](docs/workflows.md) is the tutorial: writing a box,
+the types, the *How* tab, sweeps, the prediction pipeline, the record and
+running in CI. [**docs/framework.md**](docs/framework.md) is the
+specification: what a box, a workflow and a run are, what a fingerprint
+covers and what a reproduced result promises. [**docs/architecture.md**](docs/architecture.md)
+maps the code, drawn from its imports, and [**docs/boxes.md**](docs/boxes.md)
+lists every box.
 
 **Building the apps.** `packaging/` turns OpenProcess into a standalone app with
 PyInstaller. In the environment:
@@ -900,11 +934,20 @@ workflow* on the Actions tab.
    [CHANGELOG.md](CHANGELOG.md) (`## 0.4.0`, then a few bullet points). Write
    it for the people using the app: it becomes the text of the release on
    GitHub, and the app shows it when it offers the update.
-2. Set `__version__` in `openprocess/__init__.py` to the same version and merge
-   both into `main`. It is the only place the version is written:
-   `pyproject.toml`, the download names and the app's update check all read
-   it from there.
-3. Tag that commit with the same version and push the tag:
+2. Bring the documentation up to date with the code:
+   - run `python docs/make_docs.py`, which rewrites the code map in
+     [docs/architecture.md](docs/architecture.md) and the box catalogue in
+     [docs/boxes.md](docs/boxes.md) (the test suite, and so the release
+     build, fails while they are out of date, and when a package imports
+     across its layer);
+   - read [docs/framework.md](docs/framework.md) against what changed in
+     `openprocess/flow` (a test fails when a public name is not described
+     there, but only you can tell whether a description is still right).
+3. Set `__version__` in `openprocess/__init__.py` and `version` and
+   `date-released` in `CITATION.cff` to the same version, and merge them into
+   `main`. `pyproject.toml`, the download names and the app's update check
+   all read the version from `__version__`.
+4. Tag that commit with the same version and push the tag:
 
    ```bash
    git pull
@@ -915,8 +958,8 @@ workflow* on the Actions tab.
 About five minutes later the
 [Releases page](https://github.com/s4mstruthers/openprocess/releases) has the
 macOS (Apple silicon and Intel), Windows and Linux apps. The build refuses a
-tag that does not match `__version__`, or a version with no section in
-`CHANGELOG.md`.
+tag that does not match `__version__`, a version with no section in
+`CHANGELOG.md`, and code whose tests fail, stale documentation included.
 
 **Updates.** Each time it opens, the app checks the latest release on GitHub
 (*Settings* turns that off). If there is a newer version, a slim bar at the

{openprocess-0.11.3 → openprocess-0.12.1}/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.11.3"
+__version__ = "0.12.1"
 
 __all__ = [
     "Arc", "BindingElement", "CPNet", "Marking", "Multiset", "Page", "Place",

{openprocess-0.11.3 → openprocess-0.12.1}/openprocess/cli.py

@@ -20,7 +20,8 @@ Commands
 ``exercises``   ``check``, ``marks``, ``import``, ``computes``: exercise packs (OpenProcess Learn)
 ``run``         run a ``.cpnflow`` workflow headless; ``--check`` re-runs and
                 compares with the record, ``--sweep`` varies a setting,
-                ``--lock`` writes the requirements the record names
+                ``--lock`` writes the requirements the record names,
+                ``--export`` and ``--report`` write a zip and an HTML page
 ``boxes``       list the boxes (OpenProcess's own, a folder's ``boxes/``, packages)
 ``datasets``    the public logs known by name: ``list``, ``fetch``, ``where``
 """
@@ -468,7 +469,7 @@ def command_run(arguments: argparse.Namespace) -> int:
         print(f"openprocess: {line}", file=sys.stderr)
     if problems:
         return 2
-    run = Runner(library, folder=folder).run(workflow)      # file settings are relative to the folder
+    run = Runner(library, folder=folder, strict=arguments.strict).run(workflow)   # file settings: relative to the folder
     for node in workflow.order():
         result = run.result(node)
         value = run.value(node)
@@ -490,13 +491,21 @@ def command_run(arguments: argparse.Namespace) -> int:
     if arguments.export:
         from .flow.record import export_experiment
         print(f"Wrote {export_experiment(workflow, run, arguments.export, folder, library)}")
+    if arguments.report:
+        from .flow.report import write_report
+        print(f"Wrote {write_report(arguments.report, workflow=workflow, run=run, folder=folder)}")
     if arguments.check:
-        report = check(workflow, record, run)
+        if not record.results:
+            # Nothing to compare is not a pass: a CI job would claim a reproduction that never happened.
+            print(f"openprocess: {path.name} has no recorded results to check against; "
+                  f"record them first with: openprocess run {path.name} --save", file=sys.stderr)
+            return 1
+        report = check(workflow, record, run, complete=True)
         if report:
             for line in report:
                 print(f"DIFFERS: {line}")
             return 1
-        print("Every recorded result was reproduced.")
+        print(f"Every recorded result was reproduced ({len(record.results)} boxes).")
     elif arguments.save:
         save(workflow, path, run, folder)
         print(f"Recorded the results in {path.name}")
@@ -504,7 +513,11 @@ def command_run(arguments: argparse.Namespace) -> int:
 
 
 def _brief(value) -> str:
+    import dataclasses
+    from .flow.figures import tile_parts
     from .flow.types import Figure, Scores, Table
+    if dataclasses.is_dataclass(value) and not isinstance(value, type) and tile_parts(value):
+        return " · ".join(tile_parts(value))
     if isinstance(value, Scores):
         return ", ".join(f"{k} {v:.3f}" if isinstance(v, float) else f"{k} {v}" for k, v in value.metrics.items())
     if isinstance(value, Table):
@@ -650,6 +663,10 @@ def build_parser() -> argparse.ArgumentParser:
     run.add_argument("-o", "--output", metavar="FOLDER", help="write every result as a file")
     run.add_argument("--export", metavar="FILE.zip",
                      help="zip the workflow, its inputs, boxes and results, with a README")
+    run.add_argument("--strict", action="store_true",
+                     help="also fail a box that changes its inputs in place (slower; for tests and CI)")
+    run.add_argument("--report", metavar="FILE.html",
+                     help="write the analysis as one HTML page: results, how, code, inputs, citations")
     run.add_argument("-v", "--verbose", action="store_true", help="also print the boxes' notes")
     run.set_defaults(handler=command_run)
 

{openprocess-0.11.3 → openprocess-0.12.1}/openprocess/flow/box.py

@@ -11,18 +11,18 @@ Writing a box is writing a function with type hints, nothing more::
 
 What the decorator reads, and nothing else:
 
-================================================  ===============================================
-parameters whose type is a OpenProcess type             input connection points, named after the parameter
-``list[Type]``                                    an input that takes any number of connections
-``Type | None`` (or a default of ``None``)        an optional input
-the return type                                   the output; a dataclass of typed fields gives several
+====================================================  ========================================================
+parameters whose type is an OpenProcess type          input connection points, named after the parameter
+``list[Type]``                                        an input that takes any number of connections
+``Type | None`` (or a default of ``None``)            an optional input
+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
-================================================  ===============================================
+``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; a ``name: text`` line is a setting's help
+``inspect.getsource``                                 the Code tab
+====================================================  ========================================================
 
 A box has no base class and no registration call: the decorator returns a
 :class:`Box`, which is still the function (call it from a script or a
@@ -39,6 +39,7 @@ import hashlib
 import inspect
 import os
 import importlib.util
+import re
 import types
 import typing
 from dataclasses import dataclass, field
@@ -81,10 +82,11 @@ class Port:
         return "Anything" if self.type is None else getattr(self.type, "__name__", str(self.type))
 
     def accepts(self, other: "Port") -> bool:
-        """Can an output ``other`` be connected to this input?"""
+        """Can an output ``other`` be connected to this input?  The same type
+        or a subclass of it; a ``typing.Any`` point only to another one."""
         if self.type is None or other.type is None:
-            return self.type is other.type and other.type is None or self.type is other.type
-        return issubclass(other.type, self.type) or self.type is other.type
+            return self.type is other.type
+        return issubclass(other.type, self.type)
 
 
 def clean_path(value: Any) -> str:
@@ -113,8 +115,22 @@ class Setting:
     help: str = ""
 
     def coerce(self, value: Any) -> Any:
-        """A value as the GUI or a file gives it, in the setting's type."""
+        """A value as the GUI or a file gives it, in the setting's type.
+        Raises ``ValueError`` for a value that is not one, rather than
+        rounding it: ``2.5`` is not an int setting's value, ``"2"`` and
+        ``2.0`` are."""
+        if value is None and self.default is None and self.kind != "bool":
+            return None                                  # "no value" stays no value (str | None = None)
         if self.kind == "int":
+            if isinstance(value, (bool, int)):
+                return int(value)
+            if isinstance(value, str):
+                try:
+                    return int(value.strip())
+                except ValueError:
+                    value = float(value)
+            if isinstance(value, float) and not value.is_integer():
+                raise ValueError(f"{self.name!r} must be a whole number, not {value!r}")
             return int(value)
         if self.kind == "float":
             return float(value)
@@ -168,6 +184,20 @@ class BoxSpec:
     def defaults(self) -> dict[str, Any]:
         return {s.name: s.default for s in self.settings}
 
+    @property
+    def description(self) -> str:
+        """The docstring's prose: :attr:`help` without the ``name: text``
+        lines of its settings (they are shown next to each setting) and
+        without an ``Args:`` heading left with nothing under it."""
+        names = {s.name for s in self.settings} | {p.name for p in self.inputs}
+        lines = (self.help or "").splitlines()
+        dropped = {number for key, _text, first, last in _hint_blocks(self.help) if key in names
+                   for number in range(first, last + 1)}
+        text = "\n".join(line for number, line in enumerate(lines) if number not in dropped)
+        for heading in ("Args:", "Arguments:", "Parameters:"):
+            text = re.sub(rf"(?m)^\s*{heading}\s*$\n?(?=\s*(\n|$))", "", text)
+        return text.strip()
+
     @property
     def fingerprint(self) -> str:
         """Changes when the code changes: part of every cache key."""
@@ -280,7 +310,7 @@ def _setting_from(name: str, annotation, default, has_default: bool, doc_hints:
         kind = "str"
     else:
         raise BoxError(
-            f"parameter {name!r} has type {_type_text(annotation)}, which is neither a OpenProcess "
+            f"parameter {name!r} has type {_type_text(annotation)}, which is neither an OpenProcess "
             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} = ...)")
@@ -298,39 +328,65 @@ def _outputs_from(annotation) -> tuple[list[Port], type | None]:
         raise BoxError("the function needs a return type hint (-> PetriNet), or -> None")
     if annotation is None or annotation is type(None):
         return [], None
-    annotation, _ = _unwrap_optional(annotation)
+    annotation, optional = _unwrap_optional(annotation)
     if annotation is Any:
         return [Port("out", None)], None
     if isinstance(annotation, type) and is_known(annotation):
-        return [Port("out", annotation)], None
+        return [Port("out", annotation, optional=optional)], None
     if isinstance(annotation, type) and dataclasses.is_dataclass(annotation):
         ports = []
         hints = get_type_hints(annotation)
         for f in dataclasses.fields(annotation):
-            inner, _ = _unwrap_optional(hints.get(f.name, f.type))
+            inner, optional = _unwrap_optional(hints.get(f.name, f.type))
             if not (isinstance(inner, type) and is_known(inner)) and inner is not Any:
                 raise BoxError(f"result field {f.name!r} has type {_type_text(inner)}, "
-                               f"which is not a OpenProcess type")
-            ports.append(Port(f.name, None if inner is Any else inner, label=f.name.replace("_", " ")))
+                               f"which is not an OpenProcess type")
+            ports.append(Port(f.name, None if inner is Any else inner, optional=optional,
+                              label=f.name.replace("_", " ")))
         if not ports:
             raise BoxError(f"result class {annotation.__name__} has no fields")
         return ports, annotation
-    raise BoxError(f"the return type {_type_text(annotation)} is not a OpenProcess type "
+    raise BoxError(f"the return type {_type_text(annotation)} is not an OpenProcess type "
                    f"(nor a dataclass of them)")
 
 
 def _doc_hints(doc: str) -> dict[str, str]:
-    """``name: text`` lines of a docstring, as help for settings."""
+    """``name: text`` lines of a docstring, as help for settings.  The
+    Google style ``name (float): text`` is read the same way, so a function
+    documented for Sphinx needs no second docstring to be a box."""
     hints: dict[str, str] = {}
-    for line in (doc or "").splitlines():
-        stripped = line.strip()
-        if ":" in stripped and not stripped.startswith(":"):
-            key, _, text = stripped.partition(":")
-            if key.isidentifier() and text.strip():
-                hints[key] = text.strip()
+    for key, text, _first, _last in _hint_blocks(doc):
+        hints.setdefault(key, text)
     return hints
 
 
+def _hint_blocks(doc: str):
+    """``(name, help, first line, last line)`` for each ``name: text`` block of a
+    docstring: the line and the lines under it until a blank line or the next
+    ``name:``, so a help that goes on over several lines stays one help."""
+    lines = (doc or "").splitlines()
+    index = 0
+    while index < len(lines):
+        stripped = lines[index].strip()
+        key, _, text = stripped.partition(":")
+        key = key.split("(", 1)[0].strip()                 # "noise (float)" -> "noise"
+        if ":" in stripped and not stripped.startswith(":") and key.isidentifier() and text.strip():
+            parts, end = [text.strip()], index + 1
+            while end < len(lines) and lines[end].strip() and not _starts_hint(lines[end]):
+                parts.append(lines[end].strip())
+                end += 1
+            yield key, " ".join(parts), index, end - 1
+            index = end
+        else:
+            index += 1
+
+
+def _starts_hint(line: str) -> bool:
+    stripped = line.strip()
+    key, _, text = stripped.partition(":")
+    return ":" in stripped and key.split("(", 1)[0].strip().isidentifier() and bool(text.strip())
+
+
 def _plain_name(function_name: str) -> str:
     words = function_name.replace("_", " ").strip()
     return words[:1].upper() + words[1:]

{openprocess-0.11.3 → openprocess-0.12.1}/openprocess/flow/boxes/check.py

@@ -6,7 +6,7 @@ from typing import Literal
 
 from ... import flow
 from ...mining.analysis import check_soundness
-from ...mining.compare_nets import compare_nets
+from ...mining.compare_nets import compare_nets, trace_overlap
 from ...mining.conformance.alignments import AlignmentResult, align_log
 from ...mining.conformance.quality import generalisation, precision, simplicity
 from ...mining.conformance.token_replay import ReplayResult, token_replay as _replay
@@ -61,10 +61,23 @@ def token_replay(model: PetriNet, log: EventLog) -> ReplayResult:
 
 
 @box(name="Alignments", group="Check")
-def alignments(model: PetriNet, log: EventLog) -> AlignmentResult:
+def alignments(model: PetriNet, log: EventLog, variants: int = 0) -> AlignmentResult:
     """Optimal alignments of every variant with the model (A* over the
-    synchronous product, standard cost function)."""
-    result = align_log(model, log.simple_log())
+    synchronous product, standard cost function). Shown as ProM shows them:
+    the log on the model, and every variant's moves.
+
+    variants: align only this many of the most frequent variants (0: all); on a large log
+    the most frequent few hundred usually cover most cases, and the notes say how many
+    """
+    simple = log.simple_log()
+    if variants > 0 and len(simple) > variants:
+        from collections import Counter
+        kept = Counter(dict(sorted(simple.items(), key=lambda item: (-item[1], item[0]))[:variants]))
+        covered, total = sum(kept.values()), sum(simple.values())
+        flow.note(f"Aligned the {variants:,} most frequent of {len(simple):,} variants: "
+                  f"{covered:,} of {total:,} cases ({100 * covered / total:.1f} %); fitness is over those cases")
+        simple = kept
+    result = align_log(model, simple)
     rows = [["⟨" + ", ".join(a.trace) + "⟩", a.count, a.cost if a.complete else "?", round(a.fitness, 4)]
             for a in result.alignments]
     flow.show(Table("Alignments", ["variant", "cases", "cost", "fitness"], rows), "Alignment per variant")
@@ -94,23 +107,36 @@ def _yes(value) -> str:
 
 @box(name="Compare to true net", group="Check")
 def compare_to_true_net(model: PetriNet, true_net: PetriNet, max_length: int = 12) -> Scores:
-    """Model to model: the share of the true net's complete traces the
-    model allows (recall), the share of the model's traces the true net
-    allows (precision), simplicity, and soundness."""
+    """Model to model, on behaviour: of the true net's complete traces of up
+    to *max_length* activities, the share the model allows (recall); of the
+    model's, the share the true net allows (precision). Traces are counted
+    exactly, each distinct trace once; silent steps leave no trace. Also the
+    model's simplicity and soundness.
+
+    max_length: the longest trace counted (loops make the number of traces grow with it)
+    """
     comparison = compare_nets(model, true_net, max_length=max_length)
-    only_model, only_truth = len(comparison.only_first), len(comparison.only_second)
     for trace in comparison.only_first[:5]:
         flow.note("The model allows ⟨" + ", ".join(trace) + "⟩, the true net does not")
     for trace in comparison.only_second[:5]:
         flow.note("The true net allows ⟨" + ", ".join(trace) + "⟩, the model does not")
-    sound = check_soundness(model).sound
-    recall = 1.0 if comparison.equivalent else max(0.0, 1 - only_truth / max(1, only_truth + 3))
-    prec = 1.0 if comparison.equivalent else max(0.0, 1 - only_model / max(1, only_model + 3))
+    overlap = trace_overlap(model, true_net, max_length=max_length)
+    flow.note(f"Complete traces of up to {max_length} activities: the true net has {overlap.second:,}, "
+              f"the model {overlap.first:,}, both {overlap.both:,}")
+    if not overlap.complete:
+        flow.note("The nets have too many states to count every trace: the counts are a lower bound")
+    for net, count in (("true net", overlap.second), ("model", overlap.first)):
+        if not count:
+            flow.note(f"The {net} has no complete trace of up to {max_length} activities, so "
+                      f"{'recall' if net == 'true net' else 'precision'} is not defined (n/a)")
     flow.note(comparison.summary("the model", "the true net"))
-    return Scores(model.name, {"recall": recall, "precision": prec, "simplicity": simplicity(model),
+    sound = check_soundness(model).sound
+    return Scores(model.name, {"recall": overlap.recall if overlap.second else "n/a",
+                               "precision": overlap.precision if overlap.first else "n/a",
+                               "simplicity": simplicity(model),
                                "soundness": {True: "Sound", False: "Not sound", None: "Undecided"}[sound]},
-                  note="Recall and precision here count the shortest differing traces; "
-                       "equivalent nets score 1.")
+                  note=f"Recall and precision over the distinct complete traces of up to {max_length} "
+                       "activities.")
 
 
 @box(name="Footprint conformance", group="Check")