reactra 0.1.0.dev1__tar.gz

reactra-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: reactra
+Version: 0.1.0.dev1
+Summary: Inspect, summarize, and plot exported molecular-simulation trajectories
+Author: MechanismAtlas
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.12
+Provides-Extra: plot
+Requires-Dist: matplotlib<4,>=3.8; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# Reactra
+
+**Reaction Engine for Atomistic Catalytic Trajectory Reconstruction and Automation**
+
+Reactra is the simulation platform being developed for the MechanismAtlas
+enzyme-reaction ecosystem. This **0.1.0.dev1** public preview provides useful,
+standalone tools for **exported simulation results**. The simulation engine is
+currently private and is **not included in this distribution**.
+
+The public tools work with ordinary PLUMED/COLVAR numeric tables, including
+exported OPES traces. They require no model weights, accelerator, private
+credentials, molecular structures, or mechanism definitions.
+
+## Install
+
+Python 3.12 or later:
+
+```sh
+python -m pip install reactra==0.1.0.dev1
+# Optional plotting support:
+python -m pip install 'reactra[plot]==0.1.0.dev1'
+```
+
+## Inspect a trajectory
+
+Given a text file named `COLVAR` with PLUMED's standard header:
+
+```text
+#! FIELDS time cv opes.bias
+0.0 0.20 0.0
+0.1 0.23 -0.4
+0.2 0.27 -0.8
+```
+
+```sh
+reactra summary COLVAR
+reactra summary COLVAR --columns cv opes.bias
+reactra export-csv COLVAR --columns time cv --output selected.csv
+reactra plot COLVAR --x time --y cv opes.bias --output traces.png
+reactra fingerprint COLVAR
+# Verify an independently recorded SHA-256 digest:
+reactra fingerprint COLVAR --sha256 YOUR_64_CHARACTER_HEXADECIMAL_DIGEST
+```
+
+Summary reports the number of rows, per-column first/last/minimum/maximum/mean
+and population standard deviation, and repeated or backward time steps. Summary
+and CSV export stream the input instead of loading the trajectory into memory.
+Identical repeated headers are accepted; changing headers, duplicate column names,
+ragged rows, nonnumeric values, and NaN/infinity are refused with line diagnostics.
+
+Plots use one panel per requested column and preserve row order. For a large file,
+choose an explicit stride, for example `--stride 100`; plotting retains the
+selected points in memory. Output supports PNG, SVG, and PDF. CSV and plot exports
+refuse existing destinations and publish only after processing succeeds.
+
+Units are preserved as recorded, not inferred. Statistics are linear, including
+for angular columns: this release does not perform circular statistics or
+periodic unwrapping. Time differences are not interpreted as completed continuous
+sampling when a trace repeats or moves backward.
+
+**A recorded bias or potential-energy trace is not a free-energy barrier.** These
+tools do not infer reaction crossings, reconstruct free energies, estimate rates,
+or qualify convergence. Artifact hashing checks byte identity against a supplied
+digest; it does not establish scientific validity or authenticity.
+
+## Python API
+
+```python
+from reactra.artifacts import fingerprint
+from reactra.colvar import iter_colvar, summarize
+
+report = summarize("COLVAR", columns=["cv"])
+for row in iter_colvar("COLVAR"):
+    print(row["time"], row["cv"])
+identity = fingerprint("COLVAR")
+```
+
+CLI output is JSON. Exit codes are `0` for successful processing or a matching
+digest, `1` for a digest mismatch, and `2` for invalid input or an I/O error.
+The tools inspect explicitly named files and do not open or modify engine stores.
+
+## Development status
+
+This is an early, intentionally limited public component of a larger research
+project. Its API may change before a stable release. It does not provide the
+private engine's run, restart, YAML-authoring, or chemistry interfaces. Install
+this public preview in its own environment if you also use a private Reactra
+deployment; both distributions use the `reactra` package and command name.
+
+The release source includes focused software tests. Run them with:
+
+```sh
+python -m pip install -e . pytest
+python -m pytest
+```

reactra-0.1.0.dev1/README.md

@@ -0,0 +1,95 @@
+# Reactra
+
+**Reaction Engine for Atomistic Catalytic Trajectory Reconstruction and Automation**
+
+Reactra is the simulation platform being developed for the MechanismAtlas
+enzyme-reaction ecosystem. This **0.1.0.dev1** public preview provides useful,
+standalone tools for **exported simulation results**. The simulation engine is
+currently private and is **not included in this distribution**.
+
+The public tools work with ordinary PLUMED/COLVAR numeric tables, including
+exported OPES traces. They require no model weights, accelerator, private
+credentials, molecular structures, or mechanism definitions.
+
+## Install
+
+Python 3.12 or later:
+
+```sh
+python -m pip install reactra==0.1.0.dev1
+# Optional plotting support:
+python -m pip install 'reactra[plot]==0.1.0.dev1'
+```
+
+## Inspect a trajectory
+
+Given a text file named `COLVAR` with PLUMED's standard header:
+
+```text
+#! FIELDS time cv opes.bias
+0.0 0.20 0.0
+0.1 0.23 -0.4
+0.2 0.27 -0.8
+```
+
+```sh
+reactra summary COLVAR
+reactra summary COLVAR --columns cv opes.bias
+reactra export-csv COLVAR --columns time cv --output selected.csv
+reactra plot COLVAR --x time --y cv opes.bias --output traces.png
+reactra fingerprint COLVAR
+# Verify an independently recorded SHA-256 digest:
+reactra fingerprint COLVAR --sha256 YOUR_64_CHARACTER_HEXADECIMAL_DIGEST
+```
+
+Summary reports the number of rows, per-column first/last/minimum/maximum/mean
+and population standard deviation, and repeated or backward time steps. Summary
+and CSV export stream the input instead of loading the trajectory into memory.
+Identical repeated headers are accepted; changing headers, duplicate column names,
+ragged rows, nonnumeric values, and NaN/infinity are refused with line diagnostics.
+
+Plots use one panel per requested column and preserve row order. For a large file,
+choose an explicit stride, for example `--stride 100`; plotting retains the
+selected points in memory. Output supports PNG, SVG, and PDF. CSV and plot exports
+refuse existing destinations and publish only after processing succeeds.
+
+Units are preserved as recorded, not inferred. Statistics are linear, including
+for angular columns: this release does not perform circular statistics or
+periodic unwrapping. Time differences are not interpreted as completed continuous
+sampling when a trace repeats or moves backward.
+
+**A recorded bias or potential-energy trace is not a free-energy barrier.** These
+tools do not infer reaction crossings, reconstruct free energies, estimate rates,
+or qualify convergence. Artifact hashing checks byte identity against a supplied
+digest; it does not establish scientific validity or authenticity.
+
+## Python API
+
+```python
+from reactra.artifacts import fingerprint
+from reactra.colvar import iter_colvar, summarize
+
+report = summarize("COLVAR", columns=["cv"])
+for row in iter_colvar("COLVAR"):
+    print(row["time"], row["cv"])
+identity = fingerprint("COLVAR")
+```
+
+CLI output is JSON. Exit codes are `0` for successful processing or a matching
+digest, `1` for a digest mismatch, and `2` for invalid input or an I/O error.
+The tools inspect explicitly named files and do not open or modify engine stores.
+
+## Development status
+
+This is an early, intentionally limited public component of a larger research
+project. Its API may change before a stable release. It does not provide the
+private engine's run, restart, YAML-authoring, or chemistry interfaces. Install
+this public preview in its own environment if you also use a private Reactra
+deployment; both distributions use the `reactra` package and command name.
+
+The release source includes focused software tests. Run them with:
+
+```sh
+python -m pip install -e . pytest
+python -m pytest
+```

reactra-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reactra"
+version = "0.1.0.dev1"
+description = "Inspect, summarize, and plot exported molecular-simulation trajectories"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{name = "MechanismAtlas"}]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Programming Language :: Python :: 3",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.8,<4"]
+
+[project.scripts]
+reactra = "reactra.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reactra"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/reactra", "tests", "pyproject.toml", "README.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

reactra-0.1.0.dev1/src/reactra/__init__.py

@@ -0,0 +1,3 @@
+"""Public Reactra tools for exported simulation results."""
+
+__version__ = "0.1.0.dev1"

reactra-0.1.0.dev1/src/reactra/artifacts.py

@@ -0,0 +1,41 @@
+"""Exact artifact identity and publication to new local paths."""
+
+import hashlib
+import os
+import re
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+
+def fingerprint(path: str | Path, *, expected_sha256=None) -> dict:
+    if expected_sha256 is not None and not re.fullmatch(r"[0-9a-fA-F]{64}", expected_sha256):
+        raise ValueError("Expected SHA-256 must contain exactly 64 hexadecimal characters")
+    digest = hashlib.sha256()
+    size = 0
+    with Path(path).open("rb") as stream:
+        while chunk := stream.read(1024 * 1024):
+            size += len(chunk)
+            digest.update(chunk)
+    actual = digest.hexdigest()
+    result = {"path": str(Path(path)), "byte_count": size, "sha256": actual}
+    if expected_sha256 is not None:
+        result["matches"] = actual == expected_sha256.lower()
+    return result
+
+
+@contextmanager
+def new_output(path: str | Path):
+    """Publish a completed temporary file without overwriting an existing path."""
+    destination = Path(path)
+    if destination.exists() or destination.is_symlink():
+        raise FileExistsError(f"Output already exists: {destination}")
+    descriptor, temporary = tempfile.mkstemp(
+        prefix=".reactra-", suffix=destination.suffix, dir=destination.parent
+    )
+    os.close(descriptor)
+    try:
+        yield Path(temporary)
+        os.link(temporary, destination)
+    finally:
+        Path(temporary).unlink(missing_ok=True)

reactra-0.1.0.dev1/src/reactra/cli.py

@@ -0,0 +1,108 @@
+"""Command-line tools for exported results, independent of the private engine."""
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+
+from reactra import __version__
+from reactra.artifacts import fingerprint, new_output
+from reactra.colvar import iter_colvar, select_columns, summarize
+
+
+def export_csv(source, output, columns=None):
+    with new_output(output) as temporary:
+        with temporary.open("w", newline="", encoding="utf-8") as stream:
+            writer = csv.writer(stream)
+            selected = None
+            for row in iter_colvar(source):
+                if selected is None:
+                    selected = select_columns(row, columns)
+                    writer.writerow(selected)
+                writer.writerow(row[name] for name in selected)
+    return {"output": str(output), "columns": list(selected)}
+
+
+def plot_trace(source, output, x, ys, stride=1):
+    if stride < 1:
+        raise ValueError("Plot stride must be positive")
+    if Path(output).suffix.lower() not in (".png", ".svg", ".pdf"):
+        raise ValueError("Plot output must end in .png, .svg, or .pdf")
+    try:
+        import matplotlib
+
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+    except ImportError as error:
+        raise ValueError("Plotting requires: python -m pip install 'reactra[plot]'") from error
+    selected = None
+    values = []
+    rows = 0
+    for index, row in enumerate(iter_colvar(source)):
+        if selected is None:
+            selected = select_columns(row, [x, *ys])
+        rows += 1
+        if index % stride == 0:
+            values.append(tuple(row[name] for name in selected))
+    figure, axes = plt.subplots(
+        len(ys), 1, sharex=True, squeeze=False, figsize=(8, 2.8 * len(ys)), layout="constrained"
+    )
+    try:
+        for column, axis in enumerate(axes[:, 0], 1):
+            axis.plot([row[0] for row in values], [row[column] for row in values], linewidth=1)
+            axis.set_ylabel(ys[column - 1])
+            axis.grid(alpha=0.2)
+        axes[-1, 0].set_xlabel(x + " (recorded units)")
+        figure.suptitle("Recorded simulation traces")
+        with new_output(output) as temporary:
+            figure.savefig(temporary)
+    finally:
+        plt.close(figure)
+    return {"output": str(output), "rows": rows, "plotted_rows": len(values), "stride": stride}
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(description="Reactra public simulation-result tools")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    summary = commands.add_parser("summary", help="Summarize a PLUMED/COLVAR numeric table")
+    summary.add_argument("source", type=Path)
+    summary.add_argument("--columns", nargs="+")
+    summary.add_argument("--time-column", default="time")
+    export = commands.add_parser("export-csv", help="Export selected COLVAR columns to a new CSV")
+    export.add_argument("source", type=Path)
+    export.add_argument("--columns", nargs="+")
+    export.add_argument("--output", type=Path, required=True)
+    plot = commands.add_parser("plot", help="Plot recorded columns; no free-energy reconstruction")
+    plot.add_argument("source", type=Path)
+    plot.add_argument("--x", default="time")
+    plot.add_argument("--y", nargs="+", required=True)
+    plot.add_argument("--stride", type=int, default=1)
+    plot.add_argument("--output", type=Path, required=True)
+    digest = commands.add_parser("fingerprint", help="Hash exact artifact bytes, optionally verify")
+    digest.add_argument("source", type=Path)
+    digest.add_argument("--sha256")
+    return parser
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "summary":
+            result = summarize(args.source, columns=args.columns, time_column=args.time_column)
+        elif args.command == "export-csv":
+            result = export_csv(args.source, args.output, args.columns)
+        elif args.command == "plot":
+            result = plot_trace(args.source, args.output, args.x, args.y, args.stride)
+        else:
+            result = fingerprint(args.source, expected_sha256=args.sha256)
+        print(json.dumps(result, indent=2, allow_nan=False))
+        return 0 if result.get("matches", True) else 1
+    except (OSError, ValueError) as error:
+        print(json.dumps({"error": str(error)}), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reactra-0.1.0.dev1/src/reactra/colvar.py

@@ -0,0 +1,124 @@
+"""Strict, streaming access to PLUMED text tables; no simulation dependencies."""
+
+import math
+from pathlib import Path
+
+
+def iter_colvar(path: str | Path):
+    """Yield numeric rows by field name, refusing missing or changing schemas.
+
+    Identical repeated FIELDS headers are accepted (for concatenated chunks).
+    No sorting, deduplication, unit conversion, or periodic unwrapping occurs.
+    """
+    fields = None
+    count = 0
+    with Path(path).open(encoding="utf-8") as stream:
+        for line_number, line in enumerate(stream, 1):
+            tokens = line.split()
+            if not tokens:
+                continue
+            if tokens[:2] == ["#!", "FIELDS"]:
+                declared = tuple(tokens[2:])
+                if not declared or len(set(declared)) != len(declared):
+                    raise ValueError(f"Line {line_number}: FIELDS must be nonempty and unique")
+                if fields is not None and fields != declared:
+                    raise ValueError(f"Line {line_number}: FIELDS changed within the file")
+                fields = declared
+                continue
+            if tokens[0].startswith("#"):
+                continue
+            if fields is None:
+                raise ValueError(f"Line {line_number}: data precedes the FIELDS header")
+            if len(tokens) != len(fields):
+                raise ValueError(f"Line {line_number}: expected {len(fields)} numeric values")
+            try:
+                values = tuple(float(token) for token in tokens)
+            except ValueError as error:
+                raise ValueError(f"Line {line_number}: invalid numeric value") from error
+            if not all(math.isfinite(value) for value in values):
+                raise ValueError(f"Line {line_number}: nonfinite numeric value")
+            count += 1
+            yield dict(zip(fields, values, strict=True))
+    if not count:
+        raise ValueError("COLVAR contains no data rows")
+
+
+def select_columns(row, columns):
+    selected = tuple(columns) if columns is not None else tuple(row)
+    if not selected or len(set(selected)) != len(selected):
+        raise ValueError("Selected columns must be nonempty and unique")
+    missing = set(selected) - row.keys()
+    if missing:
+        raise ValueError(f"Unknown columns: {', '.join(sorted(missing))}")
+    return selected
+
+
+def summarize(path: str | Path, *, columns=None, time_column="time") -> dict:
+    """Compute linear population statistics in one pass and report time anomalies.
+
+    Circular CVs need circular analysis; these statistics intentionally do not
+    infer periodicity, units, reaction basins, convergence, or free energies.
+    """
+    statistics = {}
+    count = 0
+    previous_time = None
+    time = None
+    for row in iter_colvar(path):
+        if not count:
+            selected = select_columns(row, columns)
+            statistics = {
+                name: {
+                    "first": row[name],
+                    "min": row[name],
+                    "max": row[name],
+                    "mean": 0.0,
+                    "m2": 0.0,
+                }
+                for name in selected
+            }
+            if time_column in row:
+                time = {
+                    "column": time_column,
+                    "first": row[time_column],
+                    "last": row[time_column],
+                    "repeated_steps": 0,
+                    "backward_steps": 0,
+                }
+            elif time_column != "time":
+                raise ValueError(f"Unknown time column: {time_column}")
+        count += 1
+        for name, stats in statistics.items():
+            value = row[name]
+            delta = value - stats["mean"]
+            stats["mean"] += delta / count
+            stats["m2"] += delta * (value - stats["mean"])
+            stats["min"] = min(stats["min"], value)
+            stats["max"] = max(stats["max"], value)
+            stats["last"] = value
+        if time is not None:
+            current = row[time_column]
+            if previous_time is not None:
+                time["repeated_steps"] += current == previous_time
+                time["backward_steps"] += current < previous_time
+            time["last"] = current
+            previous_time = current
+    for stats in statistics.values():
+        if not all(math.isfinite(value) for value in stats.values()):
+            raise ValueError("Numeric range exceeds supported summary precision")
+        stats["std_population"] = math.sqrt(max(0.0, stats.pop("m2") / count))
+        if not all(math.isfinite(value) for value in stats.values()):
+            raise ValueError("Numeric range exceeds supported summary precision")
+    if time is not None:
+        span = time["last"] - time["first"]
+        if not math.isfinite(span):
+            raise ValueError("Time range exceeds supported summary precision")
+        time["last_minus_first"] = span
+        time["strictly_increasing"] = not (time["repeated_steps"] or time["backward_steps"])
+    return {
+        "source": str(Path(path)),
+        "rows": count,
+        "columns": statistics,
+        "time": time,
+        "units": "as recorded; not inferred",
+        "statistics": "linear; no periodic unwrapping or free-energy estimation",
+    }

reactra-0.1.0.dev1/tests/test_results.py

@@ -0,0 +1,137 @@
+import csv
+import hashlib
+import json
+
+import pytest
+
+from reactra.artifacts import fingerprint
+from reactra.cli import export_csv, main, plot_trace
+from reactra.colvar import iter_colvar, summarize
+
+
+@pytest.fixture
+def source(tmp_path):
+    path = tmp_path / "COLVAR"
+    path.write_text(
+        "#! FIELDS time cv bias\n#! SET label ignored\n"
+        "0 1 -1\n1 2 -2\n#! FIELDS time cv bias\n2 3 -3\n"
+    )
+    return path
+
+
+def test_summary_matches_known_population_statistics(source):
+    result = summarize(source, columns=["cv"])
+    assert result["rows"] == 3
+    assert result["columns"]["cv"] == {
+        "first": 1,
+        "last": 3,
+        "min": 1,
+        "max": 3,
+        "mean": 2,
+        "std_population": pytest.approx((2 / 3) ** 0.5),
+    }
+    assert result["time"]["last_minus_first"] == 2
+    assert result["time"]["strictly_increasing"]
+
+
+def test_time_resets_and_duplicates_are_reported_not_deduplicated(source):
+    source.write_text("#! FIELDS time cv\n0 1\n1 2\n1 3\n0 4\n")
+    result = summarize(source)
+    assert result["rows"] == 4
+    assert result["time"]["repeated_steps"] == 1
+    assert result["time"]["backward_steps"] == 1
+    assert not result["time"]["strictly_increasing"]
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        "",
+        "# comment only\n",
+        "#! FIELDS time cv\n",
+        "0 1\n",
+        "#! FIELDS\n0\n",
+        "#! FIELDS cv cv\n1 2\n",
+        "#! FIELDS time cv\n0\n",
+        "#! FIELDS time cv\n0 nope\n",
+        "#! FIELDS time cv\n0 nan\n",
+        "#! FIELDS time cv\n0 inf\n",
+        "#! FIELDS time cv\n0 1\n#! FIELDS time other\n1 2\n",
+    ],
+)
+def test_malformed_inputs_refuse(source, text):
+    source.write_text(text)
+    with pytest.raises(ValueError):
+        list(iter_colvar(source))
+
+
+def test_summary_refuses_numerical_overflow(source):
+    source.write_text("#! FIELDS cv\n1e308\n-1e308\n")
+    with pytest.raises(ValueError, match="precision"):
+        summarize(source)
+
+
+@pytest.mark.parametrize("columns", [["absent"], ["cv", "cv"], []])
+def test_invalid_selection_refuses(source, columns):
+    with pytest.raises(ValueError):
+        summarize(source, columns=columns)
+
+
+def test_no_time_is_distinct_from_wrong_explicit_time(source):
+    source.write_text("#! FIELDS cv\n1\n2\n")
+    assert summarize(source)["time"] is None
+    with pytest.raises(ValueError, match="Unknown time"):
+        summarize(source, time_column="clock")
+
+
+def test_csv_preserves_selection_order_and_refuses_overwrite(source, tmp_path):
+    target = tmp_path / "selected.csv"
+    export_csv(source, target, ["bias", "time"])
+    with target.open(newline="") as stream:
+        rows = list(csv.reader(stream))
+    assert rows == [["bias", "time"], ["-1.0", "0.0"], ["-2.0", "1.0"], ["-3.0", "2.0"]]
+    before = target.read_bytes()
+    with pytest.raises(FileExistsError):
+        export_csv(source, target)
+    assert target.read_bytes() == before
+
+
+def test_late_parse_failure_publishes_no_partial_export(source, tmp_path):
+    source.write_text("#! FIELDS time cv\n0 1\n1 broken\n")
+    target = tmp_path / "incomplete.csv"
+    with pytest.raises(ValueError, match="Line 3"):
+        export_csv(source, target)
+    assert not target.exists()
+    assert not list(tmp_path.glob(".reactra-*"))
+
+
+def test_fingerprint_is_exact_and_detects_corruption(source):
+    expected = hashlib.sha256(source.read_bytes()).hexdigest()
+    assert fingerprint(source, expected_sha256=expected)["matches"]
+    source.write_text(source.read_text() + "3 4 -4\n")
+    assert not fingerprint(source, expected_sha256=expected)["matches"]
+    with pytest.raises(ValueError, match="64"):
+        fingerprint(source, expected_sha256="invalid")
+
+
+def test_cli_json_and_exit_status(source, capsys):
+    assert main(["summary", str(source)]) == 0
+    assert json.loads(capsys.readouterr().out)["rows"] == 3
+    assert main(["fingerprint", str(source), "--sha256", "0" * 64]) == 1
+    assert json.loads(capsys.readouterr().out)["matches"] is False
+    assert main(["summary", str(source.parent / "absent")]) == 2
+    assert "error" in json.loads(capsys.readouterr().err)
+
+
+def test_plot_generates_readable_output_and_validates_all_rows(source, tmp_path):
+    pytest.importorskip("matplotlib")
+    target = tmp_path / "trace.png"
+    report = plot_trace(source, target, "time", ["cv", "bias"], stride=2)
+    assert target.read_bytes().startswith(b"\x89PNG\r\n\x1a\n")
+    assert report["plotted_rows"] == 2
+    with pytest.raises(FileExistsError):
+        plot_trace(source, target, "time", ["cv"])
+    source.write_text("#! FIELDS time cv\n0 1\n1 nan\n2 3\n")
+    with pytest.raises(ValueError, match="nonfinite"):
+        plot_trace(source, tmp_path / "bad.png", "time", ["cv"], stride=2)
+    assert not (tmp_path / "bad.png").exists()