phpbench · dantleech · Jun 7, 2026 · May 31, 2026
diff --git a/docs/report-generators/expression.rst b/docs/report-generators/expression.rst
@@ -129,6 +129,36 @@ Which yields:
   :language: bash
   :section: 2
 
+
+.. _generator_expression_derivations:
+
+Derivations
+-----------
+
+:ref:`Expressions<generator_expression_expressions>` effectively enable you to
+populate a *table* based on the benchmarking :ref:`data <generator_expression_data>`.
+**Derivations** allow you to derive new columns from that table in one or more
+passes.
+
+Derivations have access to two variables and each expression is mapped on a row:
+
+- ``table``: a data frame containing the entire table. ``table['mean']`` for example will yield a **list** containing all of the values in the `mean` column.
+- ``row``: the current row to which the derivation will be mapped. ``row['mean']`` for example will yield the value of `mean` in the current row.
+
+In the following example we derive a new column ``super mean``:
+
+.. approved:: ../../examples/Command/report-generators-derivations
+  :language: javascript
+  :section: 0
+
+Which yields:
+
+.. approved:: ../../examples/Command/report-generators-derivations
+  :language: bash
+  :section: 2
+
+.. _generator_expression_data:
+
 Data
 ----
 

diff --git a/examples/Command/report-generators-column-diff b/examples/Command/report-generators-column-diff
@@ -11,10 +11,13 @@
          "my-report": {
              "generator": "expression",
              "aggregate": ["iteration_index"],
-             "cols": {
-                 "subject": null,
-                 "mode": null,
-                 "diff": "format('%.2fx', mean(result_time_avg) / min(suite['result_time_avg']))"
+             "cols": [
+                 "subject",
+                 "mode",
+                 "diff"
+             ],
+             "derivations": {
+                "diff": "if(min(table['mode']) > 0, format('%.2fx', row['mode'] / min(table['mode'])), 'N/A')"
              }
          }
     }

diff --git a/examples/Command/report-generators-derivations b/examples/Command/report-generators-derivations
@@ -0,0 +1,22 @@
+{
+    "report.generators": {
+         "my-report": {
+             "generator": "expression",
+             "cols": [ "benchmark", "subject", "mode", "super mode" ],
+             "derivations": {
+                 "super mode": "row['mode'] ~ ' of ' ~ sum(table['mode'])"
+             }
+         }
+    }
+}
+---
+phpbench run --report=my-report --executor=debug MultipleSubjects.php --progress=none
+---
++----------------------+---------------+----------+------------+
+| benchmark            | subject       | mode     | super mode |
++----------------------+---------------+----------+------------+
+| MultipleSubjectBench | benchSubject1 | 10.000μs | 10 of 30   |
+| MultipleSubjectBench | benchSubject2 | 10.000μs | 10 of 30   |
+| MultipleSubjectBench | benchSubject3 | 10.000μs | 10 of 30   |
++----------------------+---------------+----------+------------+
+
diff --git a/examples/Command/report-generators-expressions b/examples/Command/report-generators-expressions
@@ -3,17 +3,17 @@
          "my-report": {
              "generator": "expression",
              "expressions": {
-                "mode": "\"This is the mode: \" ~ mode(result_time_avg)"
+                "new_mode": "\"This is the mode: \" ~ mode(result_time_avg)"
              },
-             "cols": [ "benchmark", "subject", "mode" ]
+             "cols": [ "benchmark", "subject", "new_mode" ]
          }
     }
 }
 ---
 phpbench run --report=my-report --executor=debug NothingBench.php --progress=none
 ---
 +--------------+--------------+----------------------+
-| benchmark    | subject      | mode                 |
+| benchmark    | subject      | new_mode             |
 +--------------+--------------+----------------------+
 | NothingBench | benchNothing | This is the mode: 10 |
 +--------------+--------------+----------------------+

diff --git a/lib/Extension/config/report/generators.php b/lib/Extension/config/report/generators.php
@@ -1,5 +1,23 @@
 <?php
 
+$formatTime = function (string $expr) {
+    return sprintf(
+        <<<'EOT'
+        display_as_time(
+            %s, 
+            coalesce(
+                row["time_unit"],
+                "time"
+            ), 
+            row["time_precision"], 
+            row["time_mode"]
+        )
+        EOT
+        ,
+        $expr
+    );
+};
+
 return [
     'bare' => [
         'generator' => 'bare',
@@ -21,6 +39,54 @@
             'rstdev',
         ]
     ],
+    'aggregate-preview' => [
+        'title' => 'Aggregate by Subject',
+        'description' => "Aggregate results by subject and group by benchmark class.\nThis is a preview report and may change in minor version updates.",
+        'extends' => 'aggregate',
+        'break' => [
+            'benchmark',
+        ],
+        'expressions' => [
+            'name' => sprintf(
+                'if(first(variant_name) != "", %s, %s)',
+                'first(subject_name) ~ " (" ~ first(variant_name) ~ ")"',
+                'first(subject_name)'
+            ),
+            '_mode' => 'mode(result_time_avg)',
+        ],
+        'cols' => [
+            'name',
+            'revs',
+            'its',
+            'mem_peak',
+            'mode',
+            'rstdev',
+            'diff',
+        ],
+        'baseline_expressions' => [],
+        'derivations' => [
+            'diff' => sprintf(
+                'if(min(table["_mode"]) > 0, %s, %s)',
+                'format("%.2fx", row["_mode"] / min(table["_mode"]))',
+                '"N/A"'
+            ),
+            'mode' => sprintf(
+                'if(row["baseline_exists"], %s, %s)',
+                $formatTime('row["_mode"]') . ' ~ " " ~ percent_diff(row["baseline_mode"], row["_mode"])',
+                $formatTime('row["_mode"]'),
+            ),
+            'mem_peak' => sprintf(
+                'if(row["baseline_exists"], %s, %s)',
+                '(row["mem_peak"] as memory) ~ " " ~ percent_diff(row["baseline_mem_peak"], row["mem_peak"])',
+                'row["mem_peak"] as memory',
+            ),
+            'rstdev' => sprintf(
+                'if(row["baseline_exists"], %s, %s)',
+                '(row["rstdev"] as "rstdev") ~ " " ~ percent_diff(row["baseline_rstdev"], row["rstdev"])',
+                'row["rstdev"] as "rstdev"',
+            ),
+        ]
+    ],
     'bar_chart_time' => [
         'generator' => 'component',
         'components' => [