openodd-py 0.2.2__tar.gz → 0.4.0__tar.gz

{openodd_py-0.2.2 → openodd_py-0.4.0}/Cargo.lock

@@ -263,7 +263,7 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "openodd"
-version = "0.2.2"
+version = "0.4.0"
 dependencies = [
  "flate2",
  "fs2",

{openodd_py-0.2.2 → openodd_py-0.4.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "openodd"
-version = "0.2.2"
+version = "0.4.0"
 edition = "2021"
 rust-version = "1.82"
 description = "ASAM OpenODD 1.0: read, evaluate, version and sample Operational Design Domains"

{openodd_py-0.2.2 → openodd_py-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openodd-py
-Version: 0.2.2
+Version: 0.4.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering
@@ -25,8 +25,19 @@ Project-URL: Repository, https://github.com/hakuturu583/openodd_py
   (see [docs/versioning.md](docs/versioning.md)), and the transmission packs into a
   deterministic archive the ODD reads back from exactly.
 
+- **Cover** what runs drive: `CoverageCollector` samples cover items and the ODD's
+  attributes step by step (hits, seconds, metres, entries, `min_stay`, situations,
+  steps outside the ODD) and writes a coverage file; `merge_coverage` /
+  `openodd-coverage` merge any number into a report, and `--export-cod` writes each
+  run's ODD samples as an OpenODD COD table (section 8.3) with its manifest and
+  taxonomy.
+- **Sample** the next runs from the ODD (`OddSampler`), aimed at what coverage
+  left uncovered.
+
 What measures the attributes -- a simulator, a recorded log -- is the application's
-*backend*; the core only judges values.
+*backend*: a subclass of `openodd.Backend` naming its probes, how a run sets an
+attribute (`knob`), and where the ego is (`position`, `geolocation`). Everything
+else is this library's.
 
 A `default` ODD ships with the package (`openodd.bundled_odd()`,
 [python/openodd/odds/default](python/openodd/odds/default)): every attribute a road-vehicle
@@ -42,8 +53,34 @@ odd = openodd.load_odd_binding("urban.yaml", backend=backend)
 verdict = odd.evaluate(odd.sample(context))
 odd.revision   # sha256 of the files it was read from
 odd.archive()  # those files as a deterministic .tar.gz
+
+collector = openodd.CoverageCollector(items, odd=odd, backend=backend)
+collector.start(context, 0.0)
+collector.tick(context, 0.05)  # after every step
+collector.end(context, 0.05)
+collector.write(Path("run_coverage.json"), "my_scenario")
+```
+
+### Coverage
+
+A coverage document records, besides each item's buckets, how a run spent its
+time across the ODD's buckets: `OddCells` adds up steps, seconds and metres per
+*cell* -- one bucket of each attribute, as its cover item buckets it -- so a
+consumer can slice runs by any attributes without the per-step values:
+
+```python
+cells = openodd.OddCells(odd)
+cells.add(values, seconds=dt, meters=ds)   # every step: each attribute's value
+cells.to_dict()
+# {"attributes": ["speed", "rain"], "rows": [[["[30, 60]", "heavy"], 812, 40.6, 588.2], ...]}
 ```
 
+A missing value is `<missing>`, a number outside the buckets `<below>` / `<above>`.
+Each item's definition (`describe()`) names the measure its coverage is read from
+(`amount`: `hits`, `counted.seconds`, ...) and, for an ODD attribute's item, the
+attribute (`attribute`). `openodd.__version__` is the installed version, for
+coverage files to say what wrote them.
+
 ## Development
 
 ```bash

{openodd_py-0.2.2 → openodd_py-0.4.0}/README.md

@@ -10,8 +10,19 @@
   (see [docs/versioning.md](docs/versioning.md)), and the transmission packs into a
   deterministic archive the ODD reads back from exactly.
 
+- **Cover** what runs drive: `CoverageCollector` samples cover items and the ODD's
+  attributes step by step (hits, seconds, metres, entries, `min_stay`, situations,
+  steps outside the ODD) and writes a coverage file; `merge_coverage` /
+  `openodd-coverage` merge any number into a report, and `--export-cod` writes each
+  run's ODD samples as an OpenODD COD table (section 8.3) with its manifest and
+  taxonomy.
+- **Sample** the next runs from the ODD (`OddSampler`), aimed at what coverage
+  left uncovered.
+
 What measures the attributes -- a simulator, a recorded log -- is the application's
-*backend*; the core only judges values.
+*backend*: a subclass of `openodd.Backend` naming its probes, how a run sets an
+attribute (`knob`), and where the ego is (`position`, `geolocation`). Everything
+else is this library's.
 
 A `default` ODD ships with the package (`openodd.bundled_odd()`,
 [python/openodd/odds/default](python/openodd/odds/default)): every attribute a road-vehicle
@@ -27,8 +38,34 @@ odd = openodd.load_odd_binding("urban.yaml", backend=backend)
 verdict = odd.evaluate(odd.sample(context))
 odd.revision   # sha256 of the files it was read from
 odd.archive()  # those files as a deterministic .tar.gz
+
+collector = openodd.CoverageCollector(items, odd=odd, backend=backend)
+collector.start(context, 0.0)
+collector.tick(context, 0.05)  # after every step
+collector.end(context, 0.05)
+collector.write(Path("run_coverage.json"), "my_scenario")
+```
+
+### Coverage
+
+A coverage document records, besides each item's buckets, how a run spent its
+time across the ODD's buckets: `OddCells` adds up steps, seconds and metres per
+*cell* -- one bucket of each attribute, as its cover item buckets it -- so a
+consumer can slice runs by any attributes without the per-step values:
+
+```python
+cells = openodd.OddCells(odd)
+cells.add(values, seconds=dt, meters=ds)   # every step: each attribute's value
+cells.to_dict()
+# {"attributes": ["speed", "rain"], "rows": [[["[30, 60]", "heavy"], 812, 40.6, 588.2], ...]}
 ```
 
+A missing value is `<missing>`, a number outside the buckets `<below>` / `<above>`.
+Each item's definition (`describe()`) names the measure its coverage is read from
+(`amount`: `hits`, `counted.seconds`, ...) and, for an ODD attribute's item, the
+attribute (`attribute`). `openodd.__version__` is the installed version, for
+coverage files to say what wrote them.
+
 ## Development
 
 ```bash

{openodd_py-0.2.2 → openodd_py-0.4.0}/pyproject.toml

@@ -16,6 +16,9 @@ classifiers = [
   "Topic :: Scientific/Engineering",
 ]
 
+[project.scripts]
+openodd-coverage = "openodd.report:main"
+
 [project.urls]
 Repository = "https://github.com/hakuturu583/openodd_py"
 

{openodd_py-0.2.2 → openodd_py-0.4.0}/python/openodd/__init__.py

@@ -16,7 +16,10 @@ What measures the attributes -- a simulator, a recorded log -- is the
 application's :class:`Backend`.
 """
 
+from importlib import metadata as _metadata
+
 from ._core import GitSourceError, OpenOddError, UnitError, Units, convert, normalize_unit
+from .cells import MISSING, OddCells
 from .backend import Backend, Probe, default_backend, import_callable, set_default_backend
 from .items import (
     ABOVE_RANGE,
@@ -41,6 +44,8 @@ from .loader import (
     load_openodd,
     read_archive_manifest,
 )
+from .cod import CodExport, export_cod, export_cods
+from .collector import CROSS_SEPARATOR, CoverageCollector
 from .report import (
     COVERAGE_SCHEMA,
     CoverageReport,
@@ -65,7 +70,20 @@ from .model import (
     read_probe,
 )
 
+try:
+    __version__: str = _metadata.version("openodd-py")
+except _metadata.PackageNotFoundError:  # a source tree, not installed
+    __version__ = "0+unknown"
+
 __all__ = [
+    "CROSS_SEPARATOR",
+    "CodExport",
+    "CoverageCollector",
+    "MISSING",
+    "OddCells",
+    "__version__",
+    "export_cod",
+    "export_cods",
     "COVERAGE_SCHEMA",
     "CoverageReport",
     "MergedEntry",

{openodd_py-0.2.2 → openodd_py-0.4.0}/python/openodd/_core.pyi

@@ -47,8 +47,19 @@ class Units:
     def convert(self, value: float, from_unit: str, to_unit: str) -> float: ...
     def check_type(self, unit: str, unit_type: str) -> None: ...
 
+class Cells:
+    def __init__(self, odd: Any) -> None: ...
+    @property
+    def attributes(self) -> list[str]: ...
+    @property
+    def ticks(self) -> int: ...
+    def cell_of(self, values: list[Any]) -> list[str]: ...
+    def add(self, values: list[Any], seconds: float = 0.0, meters: float = 0.0) -> None: ...
+    def to_json(self) -> str: ...
+
 UNDECIDED: Any
 CACHE_ENV: str
+MISSING: str
 
 def convert(value: float, from_unit: str, to_unit: str) -> float: ...
 def normalize_unit(unit: str) -> str: ...

{openodd_py-0.2.2 → openodd_py-0.4.0}/python/openodd/backend.py

@@ -18,6 +18,11 @@ is missing. A probe that raises is read as missing too.
 The sampler (:mod:`.sampler`) asks the backend the other way round as well:
 how a run *sets* an attribute (:meth:`Backend.knob`), so an application that
 can stage conditions -- a simulator's weather -- can be sampled from an ODD.
+The coverage collector (:mod:`.collector`) asks it where the ego is
+(:meth:`Backend.position`, :meth:`Backend.geolocation`).
+
+An application subclasses :class:`Backend` for what is its own and leaves the
+rest -- the model, the reader, coverage, the sampler -- to this library.
 """
 
 from __future__ import annotations
@@ -112,6 +117,24 @@ class Backend:
             raise ValueError(f"the {self.name} backend has no {key!r} readers")
         return self.readers[key](value)
 
+    # -- what the collector asks on every step ---------------------------------
+
+    def position(self, context: Any) -> Optional[tuple[float, float, float]]:
+        """Where the ego is in *context*, in metres (``None``: unknown).
+
+        The collector measures the distance a step stands for with it (an
+        item's ``cover_by="meters"``). A backend that can tell overrides it.
+        """
+        return None
+
+    def geolocation(self, context: Any) -> Optional[tuple[float, float]]:
+        """The ego's latitude and longitude in *context* (``None``: unknown).
+
+        Kept with every step's ODD samples, it is the spatial extent of an
+        exported COD (:mod:`.cod`). A backend that can tell overrides it.
+        """
+        return None
+
     # -- what the Rust reader asks while it reads a binding --------------------
 
     def reader_keys(self) -> list[str]:

openodd_py-0.4.0/python/openodd/cells.py

@@ -0,0 +1,76 @@
+"""Cells: how long a run spent in each combination of the ODD's buckets.
+
+Every step, each attribute with buckets puts its value in one (its cover
+item's ``bucket_of``); the labels together are the step's *cell*.
+:class:`OddCells` adds up steps, seconds and metres per cell, so a consumer can
+slice a run by any attributes afterwards -- a matrix of two of them inside a
+third's bucket -- without keeping every step's values, and without bucketing
+them again by rules of its own::
+
+    cells = OddCells(odd)
+    for step in run:                       # every attribute's value, in order
+        cells.add(step.values, seconds=step.dt, meters=step.ds)
+    cells.to_dict()
+    # {"attributes": ["scenery.speed_limit", "environment.rain"],
+    #  "rows": [[["[50, 60)", "none"], 812, 40.6, 588.2], ...]}
+
+A missing value is :data:`MISSING`; a number outside the buckets
+``<below>``/``<above>``; a category none of the values names keeps its own
+label. Attributes without buckets are left out of the cell.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Union
+
+from . import _core
+from .model import to_core
+
+if TYPE_CHECKING:
+    from .model import OddDefinition
+
+__all__ = ["MISSING", "OddCells"]
+
+#: The label of a step whose value was missing.
+MISSING: str = _core.MISSING
+
+
+class OddCells:
+    """Steps, seconds and metres per cell of *odd*'s attributes."""
+
+    def __init__(self, odd: "OddDefinition") -> None:
+        self._names = [a.name for a in odd.attributes]
+        self._core = _core.Cells(odd._core)
+
+    @property
+    def attributes(self) -> list[str]:
+        """The attributes with buckets: what a cell's labels are of, in order."""
+        return list(self._core.attributes)
+
+    @property
+    def ticks(self) -> int:
+        """Steps counted so far."""
+        return int(self._core.ticks)
+
+    def _values(self, values: Union[Sequence[Any], Mapping[str, Any]]) -> list[Any]:
+        if isinstance(values, Mapping):
+            return [to_core(values.get(name)) for name in self._names]
+        return [to_core(v) for v in values]
+
+    def cell_of(self, values: Union[Sequence[Any], Mapping[str, Any]]) -> list[str]:
+        """The cell of one step: *values* by attribute name, or one per
+        attribute of the ODD in its order."""
+        return list(self._core.cell_of(self._values(values)))
+
+    def add(self, values: Union[Sequence[Any], Mapping[str, Any]], seconds: float = 0.0,
+            meters: float = 0.0) -> None:
+        """Count one step that took *seconds* and covered *meters*."""
+        self._core.add(self._values(values), float(seconds), float(meters))
+
+    def to_dict(self) -> dict[str, Any]:
+        """``{"attributes": [...], "rows": [[[label, ...], ticks, seconds, meters], ...]}``,
+        most steps first (ties by labels); seconds and metres to 3 decimals."""
+        out: dict[str, Any] = json.loads(self._core.to_json())
+        return out

openodd_py-0.4.0/python/openodd/cod.py

@@ -0,0 +1,261 @@
+"""Export a run's ODD samples as an ASAM OpenODD 1.0 current operational domain.
+
+The coverage file keeps, per tick, the time, the ego's position and every ODD
+attribute's value (``odd.samples``).  This turns them into OpenODD's exchange
+format for what was observed: a COD table (section 8.3), a manifest linking
+its columns to the taxonomy (8.3.4), and the taxonomy itself, which has to
+travel with a COD (6.1.4.5).
+
+* ``TEMPORAL_EXTENT`` is the run's start time (UTC) plus the elapsed time.
+* ``SPATIAL_EXTENT`` is ``"latitude longitude"``, as the backend's
+  :meth:`~.backend.Backend.geolocation` gave it.  A tick without an ego
+  position is left out: the column must not be empty.
+* A number's column is ``name;unit``; a categorical holds its literal; a
+  boolean ``true`` or ``false``; a missing value is empty, which OpenODD reads
+  as unknown (8.3.2).
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import logging
+import re
+from collections.abc import Sequence
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Optional
+
+from ._core import Units
+
+__all__ = ["CodExport", "export_cod", "export_cods"]
+
+logger = logging.getLogger(__name__)
+
+
+class CodExport:
+    """The files written for one run."""
+
+    def __init__(self, cod: Path, manifest: Path, taxonomy: Path, rows: int) -> None:
+        self.cod = cod
+        self.manifest = manifest
+        self.taxonomy = taxonomy
+        #: Rows written; ticks without an ego position are not.
+        self.rows = rows
+
+
+def _kind(meta: dict[str, Any], column: list[Any]) -> str:
+    """``boolean``, ``integer``, ``categorical`` or ``number``."""
+    values = meta.get("values")
+    seen = [v for v in column if v is not None]
+    if values is not None and set(values) <= {"false", "true"}:
+        return "boolean"
+    if all(isinstance(v, bool) for v in seen) and seen and values is None:
+        return "boolean"
+    if values is not None:
+        if all(re.fullmatch(r"-?\d+", str(v)) for v in values):
+            return "integer"
+        return "categorical"
+    if seen and all(isinstance(v, str) for v in seen):
+        return "categorical"
+    return "number"
+
+
+def _place(name: str, names: set[str]) -> tuple[list[str], str]:
+    """Where an attribute goes in the taxonomy: its records, and its key.
+
+    A dotted name nests one record per part, except past a part that is an
+    attribute itself: ``env.rain.duration`` beside ``env.rain`` is the key
+    ``rain.duration`` under ``env``, as OpenODD writes a measure of an element.
+    """
+    parts = name.split(".")
+    for i in range(1, len(parts)):
+        if ".".join(parts[:i]) in names:
+            return parts[: i - 1], ".".join(parts[i - 1 :])
+    return parts[:-1], parts[-1]
+
+
+def _unit_type(unit: str) -> Optional[str]:
+    return Units().unit_type(unit) if unit else None
+
+
+_PLAIN = re.compile(r"[A-Za-z_][A-Za-z0-9_.]*( [A-Za-z_][A-Za-z0-9_.]*)*")
+
+
+def _scalar(text: str) -> str:
+    """*text* as a YAML scalar: plain when it is a name, else quoted (JSON is YAML)."""
+    if _PLAIN.fullmatch(text) and text.lower() not in (
+        "true", "false", "yes", "no", "on", "off", "null", "none", "y", "n", "~",
+    ):
+        return text
+    return json.dumps(text)
+
+
+def _yaml(node: dict[str, Any], indent: int = 0) -> list[str]:
+    """A taxonomy (nested mappings of strings and lists of strings) as block YAML."""
+    lines: list[str] = []
+    pad = "  " * indent
+    for key, value in node.items():
+        if isinstance(value, dict):
+            lines.append(f"{pad}{_scalar(str(key))}:")
+            lines += _yaml(value, indent + 1)
+        elif isinstance(value, list):
+            literals = ", ".join(json.dumps(str(v)) for v in value)
+            lines.append(f"{pad}{_scalar(str(key))}: [{literals}]")
+        else:
+            lines.append(f"{pad}{_scalar(str(key))}: {_scalar(str(value))}")
+    return lines
+
+
+def _taxonomy(
+    attributes: list[dict[str, Any]], kinds: list[str], columns: list[list[Any]]
+) -> dict[str, Any]:
+    """An OpenODD YAML taxonomy of the attributes, nested by their dotted names."""
+    root: dict[str, Any] = {}
+    names = {str(meta["name"]) for meta in attributes}
+    for meta, kind, column in zip(attributes, kinds, columns):
+        parents, leaf = _place(str(meta["name"]), names)
+        node = root
+        for part in parents:
+            node = node.setdefault(part, {})
+        if kind == "boolean":
+            node[leaf] = "boolean"
+        elif kind == "integer":
+            node[leaf] = "integer count"
+        elif kind == "categorical":
+            # Every literal a cell can hold: the declared ones, else those seen.
+            declared = meta.get("values")
+            literals = (
+                [str(v) for v in declared]
+                if declared is not None
+                else sorted({str(v) for v in column if v is not None})
+            )
+            node[leaf] = literals
+        else:
+            unit_type = _unit_type(str(meta.get("unit", ""))) or "count"
+            node[leaf] = f"float {unit_type}"
+    return {"TAXONOMY": root}
+
+
+def _cell(value: Any, kind: str) -> str:
+    if value is None:
+        return ""
+    if kind == "boolean":
+        return "true" if value in (True, "true") else "false"
+    return str(value)
+
+
+def export_cod(doc: dict[str, Any], out_dir: Path, stem: str) -> Optional[CodExport]:
+    """Write *doc*'s ODD samples (a coverage document) as a COD under *out_dir*.
+
+    Returns ``None`` when the document has no samples (no ODD, or a coverage
+    file from before samples were recorded).
+    """
+    odd = doc.get("odd") or {}
+    samples = odd.get("samples")
+    if not samples or not samples.get("rows"):
+        return None
+    attributes: list[dict[str, Any]] = list(samples.get("attributes", ()))
+    rows: list[list[Any]] = list(samples["rows"])
+    columns = [[row[3 + i] for row in rows] for i in range(len(attributes))]
+    kinds = [_kind(meta, column) for meta, column in zip(attributes, columns)]
+    started = _start(odd.get("started_at"))
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    cod = out_dir / f"{stem}_cod.csv"
+    manifest = out_dir / f"{stem}_cod_manifest.csv"
+    taxonomy = out_dir / f"{stem}_taxonomy.yml"
+
+    headers = [
+        f"{meta['name']};{meta['unit']}"
+        if kind == "number" and meta.get("unit")
+        else str(meta["name"])
+        for meta, kind in zip(attributes, kinds)
+    ]
+    written = 0
+    with cod.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(["TEMPORAL_EXTENT", "SPATIAL_EXTENT", *headers])
+        for row in rows:
+            elapsed, lat, lon = row[0], row[1], row[2]
+            if lat is None or lon is None:
+                continue
+            when = started + timedelta(seconds=float(elapsed))
+            writer.writerow(
+                [
+                    when.strftime("%Y-%m-%d %H:%M:%S.%f")[:-3],
+                    f"{lat:.7f} {lon:.7f}",
+                    *(_cell(v, k) for v, k in zip(row[3:], kinds)),
+                ]
+            )
+            written += 1
+
+    names = {str(meta["name"]) for meta in attributes}
+    leaves = [_place(str(meta["name"]), names)[1] for meta in attributes]
+    with manifest.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(
+            [
+                "FIELD_ID",
+                "FILE_NAME",
+                "TYPE",
+                "COLUMN",
+                "TAXONOMY_ID",
+                "UNIT",
+                "COMMENT",
+            ]
+        )
+        writer.writerow(
+            ["001", taxonomy.name, "taxonomy", "", "", "", "Taxonomy of the ODD"]
+        )
+        for n, (meta, header, leaf, kind) in enumerate(
+            zip(attributes, headers, leaves, kinds), start=2
+        ):
+            unique = leaves.count(leaf) == 1
+            writer.writerow(
+                [
+                    f"{n:03d}",
+                    cod.name,
+                    "cod",
+                    header,
+                    leaf if unique else meta["name"],
+                    meta.get("unit", "") if kind == "number" else "",
+                    meta["name"],
+                ]
+            )
+
+    taxonomy.write_text(
+        "\n".join(_yaml(_taxonomy(attributes, kinds, columns))) + "\n",
+        encoding="utf-8",
+    )
+    return CodExport(cod, manifest, taxonomy, written)
+
+
+def _start(started_at: Any) -> datetime:
+    """The run's start time; the epoch when it was not recorded."""
+    if isinstance(started_at, str):
+        try:
+            # Python 3.10 reads "+00:00", not "Z".
+            return datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+        except ValueError:
+            pass
+    return datetime(1970, 1, 1)
+
+
+def export_cods(documents: Sequence[tuple[Path, dict[str, Any]]], out_dir: Path) -> list[CodExport]:
+    """Export every run's ODD samples (``(path, coverage document)`` each) as a COD."""
+    exported = []
+    used: set[str] = set()
+    for path, doc in documents:
+        stem = path.name.removesuffix(".json").removesuffix("_coverage")
+        unique, n = stem, 1
+        while unique in used:  # runs of one scenario in different directories
+            n += 1
+            unique = f"{stem}-{n}"
+        used.add(unique)
+        result = export_cod(doc, out_dir, unique)
+        if result is None:
+            logger.warning("coverage: %s has no ODD samples to export", path)
+        else:
+            exported.append(result)
+    return exported