enh: series and expr round method (#306)

* enh: series and expr round

* Update narwhals/_pandas_like/expr.py

Francesco always forgets this

Co-authored-by: Marco Edward Gorelli <[email protected]>

* Update narwhals/_pandas_like/series.py

Co-authored-by: Marco Edward Gorelli <[email protected]>

* move test to expr folder

* note on different rounding

* Update narwhals/expression.py

* Update narwhals/series.py

---------

Co-authored-by: Marco Edward Gorelli <[email protected]>

docs/api-reference/expressions.md

@@ -28,6 +28,7 @@
         - n_unique
         - over
         - quantile
+        - round
         - sample
         - shift
         - sort

docs/api-reference/series.md

@@ -32,6 +32,7 @@
         - null_count
         - n_unique
         - quantile
+        - round
         - sample
         - shape
         - shift

narwhals/_pandas_like/expr.py

@@ -294,6 +294,9 @@ def head(self, n: int) -> Self:
     def tail(self, n: int) -> Self:
         return reuse_series_implementation(self, "tail", n)
 
+    def round(self: Self, decimals: int) -> Self:
+        return reuse_series_implementation(self, "round", decimals)
+
     @property
     def str(self) -> PandasExprStringNamespace:
         return PandasExprStringNamespace(self)

narwhals/_pandas_like/series.py

@@ -500,6 +500,9 @@ def head(self: Self, n: int) -> Self:
     def tail(self: Self, n: int) -> Self:
         return self._from_series(self._series.tail(n))
 
+    def round(self: Self, decimals: int) -> Self:
+        return self._from_series(self._series.round(decimals=decimals))
+
     @property
     def str(self) -> PandasSeriesStringNamespace:
         return PandasSeriesStringNamespace(self)

narwhals/expression.py

@@ -1519,6 +1519,58 @@ def tail(self, n: int = 10) -> Expr:
 
         return self.__class__(lambda plx: self._call(plx).tail(n))
 
+    def round(self, decimals: int = 0) -> Expr:
+        r"""
+        Round underlying floating point data by `decimals` digits.
+
+        Arguments:
+            decimals: Number of decimals to round by.
+
+        Notes:
+            For values exactly halfway between rounded decimal values pandas and Polars behave differently.
+
+            pandas rounds to the nearest even value (e.g. -0.5 and 0.5 round to 0.0, 1.5 and 2.5 round to 2.0, 3.5 and
+            4.5 to 4.0, etc..).
+
+            Polars rounds away from 0 (e.g. -0.5 to -1.0, 0.5 to 1.0, 1.5 to 2.0, 2.5 to 3.0, etc..).
+
+
+        Examples:
+            >>> import narwhals as nw
+            >>> import pandas as pd
+            >>> import polars as pl
+            >>> data = {"a": [1.12345, 2.56789, 3.901234]}
+            >>> df_pd = pd.DataFrame(data)
+            >>> df_pl = pl.DataFrame(data)
+
+            Let's define a dataframe-agnostic function that rounds to the first decimal:
+
+            >>> @nw.narwhalify
+            ... def func(df):
+            ...     return df.select(nw.col("a").round(1))
+
+            We can then pass either pandas or Polars to `func`:
+
+            >>> func(df_pd)  # doctest: +NORMALIZE_WHITESPACE
+                 a
+            0  1.1
+            1  2.6
+            2  3.9
+            >>> func(df_pl)  # doctest: +NORMALIZE_WHITESPACE
+            shape: (3, 1)
+            ┌─────┐
+            │ a   │
+            │ --- │
+            │ f64 │
+            ╞═════╡
+            │ 1.1 │
+            │ 2.6 │
+            │ 3.9 │
+            └─────┘
+        """
+
+        return self.__class__(lambda plx: self._call(plx).round(decimals))
+
     @property
     def str(self) -> ExprStringNamespace:
         return ExprStringNamespace(self)

narwhals/series.py

@@ -1707,6 +1707,54 @@ def tail(self: Self, n: int = 10) -> Self:
 
         return self._from_series(self._series.tail(n))
 
+    def round(self: Self, decimals: int = 0) -> Self:
+        r"""
+        Round underlying floating point data by `decimals` digits.
+
+        Arguments
+            decimals: Number of decimals to round by.
+
+        Notes:
+            For values exactly halfway between rounded decimal values pandas and Polars behave differently.
+
+            pandas rounds to the nearest even value (e.g. -0.5 and 0.5 round to 0.0, 1.5 and 2.5 round to 2.0, 3.5 and
+            4.5 to 4.0, etc..).
+
+            Polars rounds away from 0 (e.g. -0.5 to -1.0, 0.5 to 1.0, 1.5 to 2.0, 2.5 to 3.0, etc..).
+
+        Examples:
+            >>> import narwhals as nw
+            >>> import pandas as pd
+            >>> import polars as pl
+            >>> data = [1.12345, 2.56789, 3.901234]
+            >>> s_pd = pd.Series(data)
+            >>> s_pl = pl.Series(data)
+
+            Let's define a dataframe-agnostic function that rounds to the first decimal:
+
+            >>> @nw.narwhalify(allow_series=True)
+            ... def func(s):
+            ...     return s.round(1)
+
+            We can then pass either pandas or Polars to `func`:
+
+            >>> func(s_pd)  # doctest: +NORMALIZE_WHITESPACE
+            0    1.1
+            1    2.6
+            2    3.9
+            dtype: float64
+
+            >>> func(s_pl)  # doctest: +NORMALIZE_WHITESPACE
+            shape: (3,)
+            Series: '' [f64]
+            [
+               1.1
+               2.6
+               3.9
+            ]
+        """
+        return self._from_series(self._series.round(decimals))
+
     @property
     def str(self) -> SeriesStringNamespace:
         return SeriesStringNamespace(self)

tests/expr/round_test.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+import polars as pl
+import pytest
+
+import narwhals as nw
+from tests.utils import compare_dicts
+
+
+@pytest.mark.parametrize("constructor", [pd.DataFrame, pl.DataFrame])
+@pytest.mark.parametrize("decimals", [0, 1, 2])
+def test_round(constructor: Any, decimals: int) -> None:
+    data = {"a": [1.12345, 2.56789, 3.901234]}
+    df_raw = constructor(data)
+    df = nw.from_native(df_raw, eager_only=True)
+
+    expected_data = {k: [round(e, decimals) for e in v] for k, v in data.items()}
+    result_frame = df.select(nw.col("a").round(decimals))
+    compare_dicts(result_frame, expected_data)
+
+    result_series = df["a"].round(decimals)
+
+    assert result_series.to_numpy().tolist() == expected_data["a"]