feat: Add per-column metrics to summary (#34)

Co-authored-by: Marius Merkle <122545105+MariusMerkleQC@users.noreply.github.com>

Author: EgeKaraismailogluQC

diffly/cli.py

@@ -11,6 +11,7 @@
 
 from ._compat import typer
 from ._utils import ABS_TOL_DEFAULT, ABS_TOL_TEMPORAL_DEFAULT, REL_TOL_DEFAULT
+from .metrics import DEFAULT_METRICS
 
 app = typer.Typer()
 
@@ -129,8 +130,24 @@ def main(
             )
         ),
     ] = [],
+    metric: Annotated[
+        list[str],
+        typer.Option(
+            help=(
+                "Metric presets to display per numerical column. Repeatable. "
+                f"Available: {', '.join(DEFAULT_METRICS)}."
+            )
+        ),
+    ] = [],
 ) -> None:
     """Compare two `parquet` files and print the comparison result."""
+    for name in metric:
+        if name not in DEFAULT_METRICS:
+            raise typer.BadParameter(
+                f"Unknown metric: {name!r}. Available: {', '.join(DEFAULT_METRICS)}."
+            )
+    metrics = {name: DEFAULT_METRICS[name] for name in metric}
+
     comparison = compare_frames(
         pl.scan_parquet(left),
         pl.scan_parquet(right),
@@ -148,6 +165,7 @@ def main(
         right_name=right_name,
         slim=slim,
         hidden_columns=hidden_columns,
+        metrics=metrics,
     )
     if output_json:
         typer.echo(summary.to_json())

diffly/comparison.py

@@ -25,6 +25,7 @@
     lazy_len,
     make_and_validate_mapping,
 )
+from .metrics import MetricFn, _make_numeric_metric
 
 if TYPE_CHECKING:  # pragma: no cover
     # NOTE: We cannot import at runtime as we're otherwise running into circular
@@ -919,6 +920,7 @@ def summary(
         right_name: str = Side.RIGHT,
         slim: bool = False,
         hidden_columns: list[str] | None = None,
+        metrics: Mapping[str, MetricFn] | None = None,
     ) -> Summary:
         """Generate a summary of all aspects of the comparison.
 
@@ -948,6 +950,16 @@ def summary(
                 advanced users who are familiar with the summary format.
             hidden_columns: Columns for which no values are printed, e.g. because they
                 contain sensitive information.
+            metrics: Optional mapping from display label to a metric callable
+                ``(left_expr, right_expr) -> pl.Expr``. Each callable receives two
+                :class:`polars.Expr` referring to the left and right values of a single
+                numerical column across all joined rows, and must return a scalar
+                aggregation expression. See :doc:`/api/metrics` for the full list of
+                presets and the :data:`~diffly.metrics.MetricFn` type. When ``None``
+                (default), no metrics are computed; presets are not applied
+                automatically. Metrics are only computed for numerical columns. Prefer
+                short labels — the summary has a fixed width and many or long labels
+                degrade rendering.
 
         Returns:
             A summary which can be printed or written to a file.
@@ -963,6 +975,12 @@ def summary(
         # NOTE: We're importing here to prevent circular imports
         from .summary import Summary
 
+        resolved_metrics = (
+            {label: _make_numeric_metric(fn) for label, fn in metrics.items()}
+            if metrics is not None
+            else None
+        )
+
         return Summary(
             self,
             show_perfect_column_matches=show_perfect_column_matches,
@@ -973,6 +991,7 @@ def summary(
             right_name=right_name,
             slim=slim,
             hidden_columns=hidden_columns,
+            metrics=resolved_metrics,
         )
 
     # ----------------------------------- UTILITIES ----------------------------------- #

diffly/metrics.py

@@ -0,0 +1,93 @@
+# Copyright (c) QuantCo 2025-2026
+# SPDX-License-Identifier: BSD-3-Clause
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import polars as pl
+import polars.selectors as cs
+
+
+@dataclass(frozen=True)
+class Metric:
+    """A metric function paired with a column-applicability selector.
+
+    Internal only.
+    """
+
+    fn: MetricFn
+    selector: cs.Selector
+
+
+MetricFn = Callable[[pl.Expr, pl.Expr], pl.Expr]
+"""A metric function maps ``(left_expr, right_expr)`` to a scalar aggregation
+expression.
+
+The expressions refer to the left-side and right-side values of a single column across
+all joined rows.
+"""
+
+
+def _make_numeric_metric(fn: MetricFn) -> Metric:
+    return Metric(fn=fn, selector=cs.numeric())
+
+
+def mean(left: pl.Expr, right: pl.Expr) -> pl.Expr:
+    """Mean of ``right - left``."""
+    return (right - left).mean()
+
+
+def median(left: pl.Expr, right: pl.Expr) -> pl.Expr:
+    """Median of ``right - left``."""
+    return (right - left).median()
+
+
+def min(left: pl.Expr, right: pl.Expr) -> pl.Expr:
+    """Minimum of ``right - left``."""
+    return (right - left).min()
+
+
+def max(left: pl.Expr, right: pl.Expr) -> pl.Expr:
+    """Maximum of ``right - left``."""
+    return (right - left).max()
+
+
+def std(left: pl.Expr, right: pl.Expr) -> pl.Expr:
+    """Standard deviation of ``right - left``."""
+    return (right - left).std()
+
+
+def mean_absolute_deviation(left: pl.Expr, right: pl.Expr) -> pl.Expr:
+    """Mean of ``|right - left|``."""
+    return (right - left).abs().mean()
+
+
+def mean_relative_deviation(left: pl.Expr, right: pl.Expr) -> pl.Expr:
+    """Mean of ``|(right - left) / left|``. Yields ``inf`` or ``null`` where
+    ``left`` is zero."""
+    return ((right - left) / left).abs().mean()
+
+
+def quantile(q: float) -> MetricFn:
+    """Factory returning a metric that computes the ``q``-quantile of
+    ``right - left``."""
+    if not 0 <= q <= 1:
+        raise ValueError(f"q must be in [0, 1], got {q}")
+
+    def _quantile(left: pl.Expr, right: pl.Expr) -> pl.Expr:
+        return (right - left).quantile(q)
+
+    return _quantile
+
+
+DEFAULT_METRICS: dict[str, MetricFn] = {
+    "Mean": mean,
+    "Median": median,
+    "Min": min,
+    "Max": max,
+    "Std": std,
+    "Mean absolute deviation": mean_absolute_deviation,
+    "Mean relative deviation": mean_relative_deviation,
+}