pytest-benchmem 0.4.2__tar.gz → 0.4.4__tar.gz

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/.github/dependabot.yml

@@ -1,10 +1,10 @@
 version: 2
 
 updates:
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "monthly"
     labels:
       - "dependencies"
     commit-message:
@@ -27,7 +27,7 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "monthly"
     labels:
       - "dependencies"
     commit-message:

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/.github/workflows/ci.yaml

@@ -16,11 +16,11 @@ jobs:
     runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
-      - run: uv sync --group dev
+      - run: uv sync --group dev --frozen
       - run: uv run ruff check --output-format=github
       - run: uv run ruff format --diff
 
@@ -29,11 +29,11 @@ jobs:
     runs-on: ubuntu-24.04
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
-      - run: uv sync --group dev
+      - run: uv sync --group dev --frozen
       - run: uv run mypy src/pytest_benchmem tests
 
   test:
@@ -49,14 +49,14 @@ jobs:
           - os: macos-latest
             python-version: "3.13"
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
-      - run: uv sync --group dev
+      - run: uv sync --group dev --frozen
       - run: uv run pytest -q
 
   smoke-install:
@@ -64,7 +64,7 @@ jobs:
     runs-on: ubuntu-24.04
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/.github/workflows/docs.yaml

@@ -18,11 +18,11 @@ jobs:
     runs-on: ubuntu-24.04
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
       # Build the notebooks from their jupytext sources, then build+execute the site.
-      - run: uv sync --group docs
+      - run: uv sync --group docs --frozen
       - run: uv run jupytext --to ipynb docs/compare-plot.md
       - run: uv run mkdocs gh-deploy --force

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/.github/workflows/nightly.yaml

@@ -31,7 +31,7 @@ jobs:
             python: "3.13"
             resolution: "--upgrade"
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
       - uses: actions/setup-python@v6
         with:

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/.github/workflows/release.yaml

@@ -49,7 +49,7 @@ jobs:
       name: pypi
       url: https://pypi.org/project/pytest-benchmem
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}
           fetch-depth: 0

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/.gitignore

@@ -10,9 +10,6 @@ build/
 .pytest_cache/
 *.bin
 
-# lockfile not tracked for a library — resolve fresh against current deps
-uv.lock
-
 # jupytext-built notebooks (source is the .md) + mkdocs build
 docs/*.ipynb
 site/

pytest_benchmem-0.4.4/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.4"
+}

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.4.4](https://github.com/fluxopt/pytest-benchmem/compare/v0.4.3...v0.4.4) (2026-06-29)
+
+
+### Features
+
+* `--pivot` comparison axis for compare/plot (fold one run along a config dim) ([#137](https://github.com/fluxopt/pytest-benchmem/issues/137)) ([d0672f7](https://github.com/fluxopt/pytest-benchmem/commit/d0672f74d7040b4f777df342c346052fc9f77678))
+
+## [0.4.3](https://github.com/fluxopt/pytest-benchmem/compare/v0.4.2...v0.4.3) (2026-06-29)
+
+
+### Features
+
+* benchmem compare accepts a single run (plain table) ([#123](https://github.com/fluxopt/pytest-benchmem/issues/123)) ([96275d9](https://github.com/fluxopt/pytest-benchmem/commit/96275d93628323ffd4f3cc74decdebdcb132004e))
+
 ## [0.4.2](https://github.com/fluxopt/pytest-benchmem/compare/v0.4.1...v0.4.2) (2026-06-18)
 
 

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-benchmem
-Version: 0.4.2
+Version: 0.4.4
 Summary: The memory companion to pytest-benchmark: a memray peak-memory pass on the same test, plus dims-aware plots and cross-version sweeps.
 Project-URL: Homepage, https://github.com/fluxopt/pytest-benchmem
 Project-URL: Documentation, https://fluxopt.github.io/pytest-benchmem/

pytest_benchmem-0.4.4/docs/changelog.md

@@ -0,0 +1,9 @@
+---
+hide:
+  - navigation
+---
+
+<!-- Rendered from the repo-root CHANGELOG.md (release-please source of truth) so the
+     published release notes can't drift from the tagged releases. -->
+
+--8<-- "CHANGELOG.md"

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/docs/compare-plot.md

@@ -99,6 +99,72 @@ Pick the metrics with `--columns` (a comma list of `time` / `peak` / `allocated`
 `module` | `class` | `param:NAME`, comma-composable); pass it to cluster param-variants
 (`--group-by func`) or collapse everything into one table.
 
+## One run, two configs — `--pivot`
+
+Everything above compares **run-files**: `compare a.json b.json` lays one file against
+another. But the file is just the *series axis* — the thing whose values sit side by side and
+get the `(N.NN)` multiplier. **The series axis is a [dim](dims.md)**, and the run-file is only
+the default one.
+
+`--pivot DIM` re-points it at a data dim, so a **single combined run** is A/B'd along that dim —
+the role a file-pair plays today, without splitting into N runs. Say `semantics` is a param
+(so it's in the node id, `test_build[legacy-100]`, *and* a dim):
+
+```python
+@pytest.mark.parametrize("semantics", ["legacy", "v1"])
+@pytest.mark.parametrize("n", [100, 200])
+def test_build(benchmark, semantics, n):
+    benchmark(build, semantics=semantics, n=n)
+```
+
+One `pytest` invocation produces one `build.json`; `--pivot param:semantics` folds it so rows
+that differ *only* in `semantics` pair up (`legacy` ↔ `v1`) per `n`:
+
+```bash
+pytest benchmarks/ --benchmark-only --benchmark-memory --benchmark-json=build.json
+benchmem compare build.json --pivot param:semantics --columns time,peak   # the A/B table
+benchmem plot    build.json --pivot param:semantics --columns peak --view compare   # the A/B bars
+benchmem plot    build.json --x n --facet semantics --columns peak     # --pivot optional here
+```
+
+Don't confuse it with `--group-by`, which touches the *other* axis: `--group-by` **partitions
+rows** into sub-tables along a dim while the compared series stays the run-files (`legacy` and
+`v1` would sit in separate sections, never set against each other); `--pivot` makes the dim
+*itself* the compared series, folding rows that differ only in it into one ranked A/B row. They
+compose on orthogonal axes — `--pivot param:semantics --group-by node.func` folds `legacy` ↔ `v1`
+*and* clusters the folded rows into per-function sub-tables. In short: `--group-by` says which
+rows belong together; `--pivot` says what you're comparing.
+
+`--pivot` accepts the same dims as `--group-by`/`--facet` — `param:NAME` or a bare `extra_info`
+name — and composes with `--columns`, `--stat`, `--facet`, `--where`, and `--sort` unchanged.
+It's mutually exclusive with multiple runs (an A/B view has *one* series axis: comparing files
+*and* folding a dim would be a 2-D matrix), and only the paired views consume it — on `plot`
+it applies to `--view compare`/`scatter`; for `scaling`/`sweep` the dim is a normal `--x` /
+`--facet` axis instead. One combined run then drives the A/B table, the A/B plot, the scaling
+plot, *and* an external per-id gate (e.g. CodSpeed, which wants the config value in the node id
+of one run) — no file-splitting, no per-config reruns.
+
+`--fail-on` follows the same axis: it normally gates the first run vs the last, but with
+`--pivot` it gates the **first dim value vs the last** (e.g. `legacy` → `v1`) out of the one
+run — so the combined run also gates itself in CI, no second file required:
+
+```bash
+# fail if v1's peak grew >10% over legacy, for any benchmark, from one run:
+pytest benchmarks/ --benchmark-only --benchmark-memory --benchmark-json=build.json
+benchmem compare build.json --pivot param:semantics --fail-on peak:10%
+```
+
+The **base** (the `--fail-on` reference, and the first row) is the dim's *first* value in
+parametrize / collection order — the `--pivot` analogue of file argument order. So
+`parametrize("semantics", ["legacy", "v1"])` gates `v1` against `legacy`; reorder the list to
+flip it. (The table's `(1.0)` annotation is separate — it marks each column's *best* value,
+green, exactly as the run-file table does, not the base.)
+
+> A `--pivot` param is lifted out of the id when rows fold (`test_build[legacy-100]` → `test_build[100]`),
+> matched by value. A param given a custom `pytest.param(id=…)` whose label differs from its
+> value won't fold — use a plain parametrize value, or an `extra_info` dim (which isn't in the
+> id at all), for the comparison axis.
+
 ## Gate CI on a regression
 
 `--fail-on` exits non-zero past a threshold — drop it into CI after the run. Thresholds are
@@ -289,6 +355,8 @@ A minimal GitHub Actions job using the two-file approach, caching the baseline a
 | 2 | `compare` (`--view compare`) | ranked — what moved *most*, in native units? |
 | 3+ | `sweep` | fold-change across versions, one cell per (id, run) |
 
+`--pivot` re-points the series axis of the paired views (`compare`/`scatter`) from the run-file
+onto a dim, folding a single run along it (see [One run, two configs](#one-run-two-configs-pivot)).
 `--facet` splits any view into small multiples by a [dim](dims.md) (including `node.*`),
 `--where` keeps only rows matching a `dim=value` filter (repeatable, AND-combined),
 `--free-axes` unmatches a faceted axis from the shared default, and `--label`/`-l` names

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/mkdocs.yml

@@ -39,6 +39,7 @@ nav:
       - Grouping by dims: dims.md
       - Cross-version sweeps: sweeps.md
   - Reference: reference.md
+  - Release notes: changelog.md
 
 plugins:
   - search
@@ -93,6 +94,10 @@ markdown_extensions:
       anchor_linenums: true
       use_pygments: true
   - pymdownx.inlinehilite
+  - pymdownx.snippets:
+      # Pull docs/changelog.md's `--8<-- "CHANGELOG.md"` from the repo root.
+      base_path: ["."]
+      check_paths: true
   - pymdownx.superfences
   - pymdownx.details
   - pymdownx.tabbed:

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/pyproject.toml

@@ -48,7 +48,8 @@ build-backend = "hatchling.build"
 source = "vcs"
 
 [dependency-groups]
-dev = ["ruff", "mypy", "pre-commit", "pytest-benchmem[plot]", { include-group = "docs" }]
+# mypy <2.1: 2.1.0 errors on numpy's PEP 695 stub under python_version=3.11. Lift once fixed upstream.
+dev = ["ruff", "mypy<2.2", "pre-commit", "pytest-benchmem[plot]", { include-group = "docs" }]
 docs = [
     "jupytext",
     "ipykernel",

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/src/pytest_benchmem/cli.py

@@ -100,6 +100,16 @@ def plot(
         typer.Option(help="compare | scatter | sweep | scaling (default: by count)."),
     ] = None,
     facet: Annotated[str | None, typer.Option(help="Dim to facet by.")] = None,
+    pivot: Annotated[
+        str | None,
+        typer.Option(
+            "--pivot",
+            help="Comparison axis for --view compare/scatter: fold a single run along this dim "
+            "instead of across run-files (param:NAME or a bare extra_info name); its values "
+            "become the compared series. Like --group-by but it sets what's *compared*, not how "
+            "rows cluster. Mutually exclusive with multiple runs.",
+        ),
+    ] = None,
     x: Annotated[str | None, typer.Option(help="scaling: dim for the x-axis.")] = None,
     clip: Annotated[float | None, typer.Option(help="Clamp the colour scale.")] = None,
     where: Annotated[
@@ -129,7 +139,21 @@ def plot(
     """Render an interactive plotly view from one or more pytest-benchmark runs."""
     _require_runs_exist(runs, suggest=True)
 
-    chosen = view or ("scaling" if len(runs) == 1 else "scatter" if len(runs) == 2 else "sweep")
+    # --pivot's natural home is the A/B compare view, so when --view is unset it defaults there
+    # (otherwise one run would default to scaling, which has no series axis to pivot). An explicit
+    # --view still wins in both cases; the guard below rejects a non-paired view under --pivot.
+    if pivot is not None:
+        chosen = view or "compare"
+    else:
+        chosen = view or ("scaling" if len(runs) == 1 else "scatter" if len(runs) == 2 else "sweep")
+    # --pivot re-points the series axis at a dim; only the paired views (compare/scatter) have a
+    # series axis to re-point. For scaling/sweep the dim is a normal x/colour/facet axis.
+    if pivot is not None and chosen not in ("compare", "scatter"):
+        raise _fail(
+            f"--pivot re-points the comparison series and applies to --view compare or scatter, "
+            f"not {chosen!r}; for scaling/sweep use --x / --facet to place the dim.",
+            2,
+        )
     _need_plotly()
     from pytest_benchmem import plotting
 
@@ -145,6 +169,7 @@ def plot(
                 where=filters,
                 free_axes=free_axes,
                 labels=labels,
+                pivot=pivot,
             )
         elif chosen == "scatter":
             fig, n = plotting.plot_scatter(
@@ -155,6 +180,7 @@ def plot(
                 where=filters,
                 free_axes=free_axes,
                 labels=labels,
+                pivot=pivot,
             )
         elif chosen == "sweep":
             fig, n = plotting.plot_sweep(
@@ -188,7 +214,10 @@ def plot(
 def compare(
     runs: Annotated[
         list[Path],
-        typer.Argument(help="Two or more pytest-benchmark runs, oldest → newest (a sweep is N)."),
+        typer.Argument(
+            help="One or more pytest-benchmark runs, oldest → newest. One prints a plain "
+            "table; two or more compare (a sweep is N)."
+        ),
     ],
     columns: Annotated[
         str | None,
@@ -219,6 +248,16 @@ def compare(
         str,
         typer.Option(help="Row order: name (id) | value (largest in the last run) | change."),
     ] = "name",
+    pivot: Annotated[
+        str | None,
+        typer.Option(
+            "--pivot",
+            help="Comparison axis: fold a single run along this dim instead of across run-files "
+            "— param:NAME or a bare extra_info name. Rows differing only in it pair up and its "
+            "values become the compared series. Like --group-by but it sets what's *compared*, "
+            "not how rows cluster. Mutually exclusive with multiple runs.",
+        ),
+    ] = None,
     csv: Annotated[
         Path | None,
         typer.Option(help="Also write the raw (unscaled) comparison to this CSV file."),
@@ -227,29 +266,50 @@ def compare(
         list[str] | None,
         typer.Option(
             "--fail-on",
-            help="Exit non-zero on a regression of the first run vs the last. "
-            "FIELD:THRESHOLD, repeatable — e.g. --fail-on peak:10% --fail-on peak:5MiB "
-            "--fail-on rss:10% (rss gates only isolated runs).",
+            help="Exit non-zero on a regression of the first run vs the last (or, with --pivot, "
+            "the first dim value vs the last). FIELD:THRESHOLD, repeatable — e.g. --fail-on "
+            "peak:10% --fail-on peak:5MiB --fail-on rss:10% (rss gates only isolated runs).",
         ),
     ] = None,
 ) -> None:
-    """Print a per-id comparison table across two or more runs (and optionally gate CI)."""
-    if len(runs) < 2:  # noqa: PLR2004 — a comparison needs two sides
-        raise _fail("compare needs at least two runs", 2)
+    """Print a per-id table for one run, or compare two or more (and optionally gate CI)."""
+    if not runs:
+        raise _fail("compare needs at least one run", 2)
+    # A growth gate needs a base and a head: two runs, or one run folded along --pivot (which
+    # supplies the two sides from one file). Without either, refuse rather than silently pass.
+    if fail_on and len(runs) < 2 and pivot is None:  # noqa: PLR2004
+        raise _fail(
+            "compare --fail-on needs at least two runs — it gates growth of the first run vs "
+            "the last. To gate one combined run, add --pivot DIM (first dim value vs last); for "
+            "an absolute ceiling, use the @pytest.mark.benchmem(max_peak=...) marker instead.",
+            2,
+        )
     _require_runs_exist(runs, suggest=False)
-    from pytest_benchmem.compare import compare_runs, find_regressions, parse_threshold
+    from pytest_benchmem.compare import (
+        compare_runs,
+        find_pivot_regressions,
+        find_regressions,
+        parse_threshold,
+    )
 
     with _exit_on_value_error():
-        compare_runs(runs, columns=columns, group_by=group_by, stat=stat, sort=sort, csv=csv)
+        compare_runs(
+            runs, columns=columns, group_by=group_by, stat=stat, sort=sort, pivot=pivot, csv=csv
+        )
 
     if not fail_on:
         return
     with _exit_on_value_error(code=2):
         thresholds = [parse_threshold(expr) for expr in fail_on]
 
-    # Gate the first run (base) against the last (head) — oldest vs newest in a sweep.
+    # Gate base vs head: the first run vs the last (oldest vs newest in a sweep), or — with
+    # --pivot — the first value of the dim vs the last, folded out of the one run.
     with _exit_on_value_error(code=2):  # e.g. an rss gate against non-isolated runs
-        regressions = find_regressions(runs[0], runs[-1], thresholds)
+        regressions = (
+            find_pivot_regressions(runs[0], pivot, thresholds)
+            if pivot is not None
+            else find_regressions(runs[0], runs[-1], thresholds)
+        )
     if regressions:
         typer.secho(f"{len(regressions)} regression(s) over threshold:", fg=typer.colors.RED)
         for reg in regressions:

{pytest_benchmem-0.4.2 → pytest_benchmem-0.4.4}/src/pytest_benchmem/compare.py

@@ -1,11 +1,12 @@
-"""Text comparison of two or more pytest-benchmark runs — keyed on the benchmark id.
+"""Text table for one or more pytest-benchmark runs — keyed on the benchmark id.
 
-:func:`compare_runs` prints the comparison table, modelled on pytest-benchmark's own:
+:func:`compare_runs` prints the table, modelled on pytest-benchmark's own:
 rows are one per ``(benchmark × run)``, columns are ``metric × stat`` (``--columns``
 picks the metrics, default ``time,peak``; ``--stat`` picks the stat, default ``all`` for
-the full min/max/mean/median/stddev spread), every cell carries a relative ``(N.NN)``
-multiplier vs its column's best (best green, worst red), and ``group_by`` splits the rows
-into sub-tables.
+the full min/max/mean/median/stddev spread), and ``group_by`` splits the rows into
+sub-tables. With **two or more** runs every cell carries a relative ``(N.NN)`` multiplier
+vs its column's best (best green, worst red); a **single** run is a plain readout — there's
+no other run to rank against, so the multiplier and colour are dropped.
 
 The rest is the regression gate behind ``benchmem compare --fail-on``: parse a threshold
 like ``peak:10%`` / ``peak:5MiB`` / ``allocations:5%`` / ``time:5%``, find the ids whose
@@ -141,14 +142,18 @@ def _short(test_id: str) -> str:
 
 
 def _load_columns(
-    runs: Sequence[str | Path], metrics: Sequence[Metric], stats: Sequence[str]
+    runs: Sequence[str | Path],
+    metrics: Sequence[Metric],
+    stats: Sequence[str],
+    pivot: str | None = None,
 ) -> tuple[list[str], dict[tuple[str, str, str], float], dict[str, str], dict[str, dict[str, Any]]]:
     """Load each ``metric × stat`` column into ``(labels, values, units, dims)``.
 
-    Columns are keyed by a ``"metric:stat"`` id; ``values`` maps ``(col_id, id, run) →
-    value``, ``units`` maps ``metric → unit``. Runs keep file order (oldest → newest).
-    Each stat reads pytest-benchmark's own ``stats`` for ``time`` and reduces the
-    per-repeat series for the memory metrics.
+    Columns are keyed by a ``"metric:stat"`` id; ``values`` maps ``(col_id, id, series) →
+    value``, ``units`` maps ``metric → unit``. The series labels keep their natural order —
+    file order (oldest → newest) for run-files, or dim-value order when ``pivot`` folds a single
+    run along a dim. Each stat reads pytest-benchmark's own ``stats`` for ``time`` and reduces
+    the per-repeat series for the memory metrics.
     """
     paths = [Path(r) for r in runs]
     labels: list[str] = []
@@ -157,7 +162,7 @@ def _load_columns(
     dims: dict[str, dict[str, Any]] = {}
     for metric in metrics:
         for stat in stats:
-            df, unit = load_long_df(paths, metric=metric, stat=stat)
+            df, unit = load_long_df(paths, metric=metric, stat=stat, pivot=pivot)
             units[metric] = unit
             if df.empty:  # metric absent from every run (e.g. memory on timing-only files)
                 continue
@@ -224,25 +229,36 @@ def compare_runs(
     stat: str | None = None,
     group_by: str | None = "fullname",
     sort: str = "name",
+    pivot: str | None = None,
     csv: Path | None = None,
     out: TextIO | None = None,
 ) -> None:
-    """Print a per-(benchmark, run) comparison table across two or more runs.
-
-    Mirrors pytest-benchmark's table model: rows are one per ``(benchmark × run)``,
-    ``columns`` selects which metric columns appear (``time`` / ``peak`` / ``allocated``
-    / ``allocations``), each cell carries the value plus a relative ``(N.NN)`` multiplier
-    vs the group's best (best green, worst red), and ``group_by`` splits the rows into
-    sub-tables (``fullname`` / ``name`` / ``func`` / ``group`` / ``module`` / ``class`` /
-    ``param:NAME``, comma-composable). With no ``group_by`` the whole comparison is one
-    table.
+    """Print a per-(benchmark, series) table for one or more runs.
+
+    Mirrors pytest-benchmark's table model: rows are one per ``(benchmark × series)``, where
+    the **series axis** is the run-file by default (one column-group per run). With two or more
+    series each cell carries a relative ``(N.NN)`` multiplier vs the group's best (best green,
+    worst red); a single series is a plain readout with neither. ``columns`` selects which metric
+    columns appear (``time`` / ``peak`` / ``allocated`` / ``allocations``). ``group_by`` splits
+    the rows into sub-tables (``fullname`` / ``name`` / ``func`` / ``group`` / ``module`` /
+    ``class`` / ``param:NAME``, comma-composable); with no ``group_by`` the whole comparison is
+    one table.
+
+    ``pivot`` re-points the series axis from the run-file onto a data dim (``param:NAME`` or a
+    bare ``extra_info`` name), folding a *single* combined run along that dim: rows that differ
+    only in it pair up and its values become the compared series — the A/B a run-file pair gives
+    you today, without splitting the data into N files. Distinct from ``group_by`` (which only
+    clusters rows into sub-tables, leaving the run-files as the compared series): ``pivot`` sets
+    *what* is compared, ``group_by`` sets how rows cluster. It composes with ``columns`` /
+    ``stat`` / ``sort`` / ``group_by`` unchanged and is mutually exclusive with multiple runs
+    (one series axis per table).
 
     Every column is a ``metric × stat`` pair. ``columns`` is a comma list of metric names
     (default ``time,peak``); ``stat`` is one of ``min`` / ``max`` / ``mean`` / ``median`` /
     ``stddev`` or ``all`` (the default), which expands each metric into its full stat
     spread — so no single statistic is privileged. A metric absent from every run is
     dropped rather than shown all dashes (so timing-only runs collapse to just ``time``).
-    ``sort`` orders rows within a group: ``name``, ``value`` (largest in the last run), or
+    ``sort`` orders rows within a group: ``name``, ``value`` (largest in the last series), or
     ``change`` (biggest growth first). ``csv`` also writes the raw (unscaled) comparison.
     """
     from rich import box
@@ -253,12 +269,17 @@ def compare_runs(
     if sort not in _SORTS:
         raise ValueError(f"unknown --sort {sort!r}; use one of {', '.join(_SORTS)}")
     metrics, stats = _resolve_columns(columns), _resolve_stats(stat)
-    labels, values, units, dims = _load_columns(runs, metrics, stats)
-    if len(labels) < 2:  # noqa: PLR2004 — a comparison needs two sides
+    labels, values, units, dims = _load_columns(runs, metrics, stats, pivot)
+    if not labels:
+        raise ValueError("no benchmarks found in the given run(s)")
+    if len(labels) < 2 and len(runs) > 1:  # noqa: PLR2004 — distinct paths collapsed to one series
         raise ValueError(
             f"compare needs at least two distinct runs; got {labels!r} "
             f"(the same file more than once?). Pass distinct files."
         )
+    # One run is a plain readout: with no other run to rank against, the (N.NN) multiplier and
+    # the best/worst colour are meaningless (best == worst == the value), so they're dropped.
+    single = len(labels) == 1
     with_data = {col_id for col_id, _i, _lab in values}
     all_cols = [(m, s) for m in metrics for s in stats]
     cols = [(m, s) for m, s in all_cols if f"{m}:{s}" in with_data] or all_cols  # drop empties
@@ -338,7 +359,9 @@ def compare_runs(
                     if unit == ""
                     else f"{v:.4g}"
                 )
-                cells.append(Text(body + _mult(v, best), style=rank_style(v, best, worst) or ""))
+                mult = "" if single else _mult(v, best)
+                style = "" if single else (rank_style(v, best, worst) or "")
+                cells.append(Text(body + mult, style=style))
             table.add_row(*cells)
         console.print(table)
         console.print()  # one blank line between sub-tables
@@ -465,6 +488,39 @@ def find_regressions(a: str | Path, b: str | Path, thresholds: list[Threshold])
     return regressions
 
 
+def find_pivot_regressions(
+    run: str | Path, pivot: str, thresholds: list[Threshold]
+) -> list[Regression]:
+    """Regressions along a ``--pivot`` axis within *one* run — the gate generalized the same way
+    the table is: with run-files the base is ``runs[0]`` and the head ``runs[-1]``; here the base
+    is the first value of the ``pivot`` dim and the head the last (mirroring oldest→newest). Each
+    fold-collapsed id is paired across them and flagged only on growth, reusing
+    :func:`_regressions_for`.
+    """
+    regressions: list[Regression] = []
+    for th in thresholds:
+        # ``pivot`` folds the run so ``snapshot`` carries the dim's values and ``id`` is the
+        # collapsed pairing key; the fail-on field doubles as the metric to read (headline scalar).
+        df, _unit = load_long_df(run, metric=cast("Metric", th.field), pivot=pivot)
+        labels = list(dict.fromkeys(df["snapshot"]))
+        if len(labels) < 2:  # noqa: PLR2004 — a growth gate needs a base value and a head value
+            raise ValueError(
+                f"--fail-on with --pivot {pivot!r} needs two distinct values to gate; got "
+                f"{labels}. Does the run vary {pivot!r}?"
+            )
+        base_label, head_label = labels[0], labels[-1]
+        rows = zip(df["id"], df["value"], df["snapshot"], strict=True)
+        side: dict[str, dict[str, float]] = {base_label: {}, head_label: {}}
+        for test_id, value, label in rows:
+            if label in side:
+                side[label][test_id] = float(value)
+        base, head = side[base_label], side[head_label]
+        if th.field == "rss" and not (base.keys() & head.keys()):
+            raise ValueError(_RSS_GATE_EMPTY)
+        regressions.extend(_regressions_for(base, head, th))
+    return regressions
+
+
 #: Memory-blob key per fail-on field — the fields ``--benchmark-memory-compare-fail`` gates on.
 _BLOB_FIELD = {
     "peak": "peak_bytes",