feat: add support for median

docs/api-reference/expr.md

@@ -29,6 +29,7 @@
         - len
         - max
         - mean
+        - median
         - min
         - mode
         - null_count

docs/api-reference/narwhals.md

@@ -29,6 +29,7 @@ Here are the top-level functions available in Narwhals.
         - maybe_set_index
         - mean
         - mean_horizontal
+        - median
         - min
         - min_horizontal
         - narwhalify

docs/api-reference/series.md

@@ -36,6 +36,7 @@
         - len
         - max
         - mean
+        - median
         - min
         - mode
         - name

narwhals/__init__.py

@@ -40,6 +40,7 @@
 from narwhals.expr import max_horizontal
 from narwhals.expr import mean
 from narwhals.expr import mean_horizontal
+from narwhals.expr import median
 from narwhals.expr import min
 from narwhals.expr import min_horizontal
 from narwhals.expr import nth
@@ -97,6 +98,7 @@
     "max_horizontal",
     "mean",
     "mean_horizontal",
+    "median",
     "min",
     "min_horizontal",
     "nth",

narwhals/_arrow/expr.py

@@ -204,6 +204,9 @@ def filter(self, *predicates: IntoArrowExpr) -> Self:
     def mean(self) -> Self:
         return reuse_series_implementation(self, "mean", returns_scalar=True)
 
+    def median(self) -> Self:
+        return reuse_series_implementation(self, "median", returns_scalar=True)
+
     def count(self) -> Self:
         return reuse_series_implementation(self, "count", returns_scalar=True)
 

narwhals/_arrow/namespace.py

@@ -325,6 +325,11 @@ def mean(self, *column_names: str) -> ArrowExpr:
             *column_names, backend_version=self._backend_version, dtypes=self._dtypes
         ).mean()
 
+    def median(self, *column_names: str) -> ArrowExpr:
+        return ArrowExpr.from_column_names(
+            *column_names, backend_version=self._backend_version, dtypes=self._dtypes
+        ).median()
+
     def max(self, *column_names: str) -> ArrowExpr:
         return ArrowExpr.from_column_names(
             *column_names, backend_version=self._backend_version, dtypes=self._dtypes

narwhals/_arrow/series.py

@@ -260,6 +260,11 @@ def mean(self) -> int:
 
         return pc.mean(self._native_series)  # type: ignore[no-any-return]
 
+    def median(self) -> int:
+        import pyarrow.compute as pc  # ignore-banned-import()
+
+        return pc.approximate_median(self._native_series)  # type: ignore[no-any-return]
+
     def min(self) -> int:
         import pyarrow.compute as pc  # ignore-banned-import()
 

narwhals/_dask/expr.py

@@ -381,6 +381,13 @@ def mean(self) -> Self:
             returns_scalar=True,
         )
 
+    def median(self) -> Self:
+        return self._from_call(
+            lambda _input: _input.median_approximate(),
+            "median",
+            returns_scalar=True,
+        )
+
     def min(self) -> Self:
         return self._from_call(
             lambda _input: _input.min(),

narwhals/_dask/namespace.py

@@ -104,6 +104,11 @@ def mean(self, *column_names: str) -> DaskExpr:
             *column_names, backend_version=self._backend_version, dtypes=self._dtypes
         ).mean()
 
+    def median(self, *column_names: str) -> DaskExpr:
+        return DaskExpr.from_column_names(
+            *column_names, backend_version=self._backend_version, dtypes=self._dtypes
+        ).median()
+
     def sum(self, *column_names: str) -> DaskExpr:
         return DaskExpr.from_column_names(
             *column_names, backend_version=self._backend_version, dtypes=self._dtypes

narwhals/_pandas_like/expr.py

@@ -218,6 +218,9 @@ def count(self) -> Self:
     def mean(self) -> Self:
         return reuse_series_implementation(self, "mean", returns_scalar=True)
 
+    def median(self) -> Self:
+        return reuse_series_implementation(self, "median", returns_scalar=True)
+
     def std(self, *, ddof: int = 1) -> Self:
         return reuse_series_implementation(self, "std", ddof=ddof, returns_scalar=True)
 

narwhals/_pandas_like/namespace.py

@@ -177,6 +177,14 @@ def mean(self, *column_names: str) -> PandasLikeExpr:
             dtypes=self._dtypes,
         ).mean()
 
+    def median(self, *column_names: str) -> PandasLikeExpr:
+        return PandasLikeExpr.from_column_names(
+            *column_names,
+            implementation=self._implementation,
+            backend_version=self._backend_version,
+            dtypes=self._dtypes,
+        ).median()
+
     def max(self, *column_names: str) -> PandasLikeExpr:
         return PandasLikeExpr.from_column_names(
             *column_names,

narwhals/_pandas_like/series.py

@@ -421,6 +421,10 @@ def mean(self) -> Any:
         ser = self._native_series
         return ser.mean()
 
+    def median(self) -> Any:
+        ser = self._native_series
+        return ser.median()
+
     def std(
         self,
         *,

narwhals/_polars/namespace.py

@@ -117,6 +117,13 @@ def mean_horizontal(self, *exprs: IntoPolarsExpr) -> PolarsExpr:
             dtypes=self._dtypes,
         )
 
+    def median(self, *column_names: str) -> PolarsExpr:
+        import polars as pl  # ignore-banned-import()
+
+        from narwhals._polars.expr import PolarsExpr
+
+        return PolarsExpr(pl.median([*column_names]), dtypes=self._dtypes)  # type: ignore[arg-type]
+
     def concat_str(
         self,
         exprs: Iterable[IntoPolarsExpr],

narwhals/expr.py

@@ -447,6 +447,52 @@ def mean(self) -> Self:
         """
         return self.__class__(lambda plx: self._call(plx).mean())
 
+    def median(self) -> Self:
+        """
+        Get median value.
+
+        Notes:
+            Results might slightly differ across backends due to differences in the underlying algorithms used to compute the median.
+
+        Examples:
+            >>> import pandas as pd
+            >>> import polars as pl
+            >>> import pyarrow as pa
+            >>> import narwhals as nw
+            >>> df_pd = pd.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]})
+            >>> df_pl = pl.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]})
+            >>> df_pa = pa.table({"a": [1, 8, 3], "b": [4, 5, 2]})
+
+            Let's define a dataframe-agnostic function:
+
+            >>> @nw.narwhalify
+            ... def func(df):
+            ...     return df.select(nw.col("a", "b").median())
+
+            We can then pass any supported library such as pandas, Polars, or PyArrow to `func`:
+
+            >>> func(df_pd)
+                 a    b
+            0  3.0  4.0
+            >>> func(df_pl)
+            shape: (1, 2)
+            ┌─────┬─────┐
+            │ a   ┆ b   │
+            │ --- ┆ --- │
+            │ f64 ┆ f64 │
+            ╞═════╪═════╡
+            │ 3.0 ┆ 4.0 │
+            └─────┴─────┘
+            >>> func(df_pa)
+            pyarrow.Table
+            a: double
+            b: double
+            ----
+            a: [[3]]
+            b: [[4]]
+        """
+        return self.__class__(lambda plx: self._call(plx).median())
+
     def std(self, *, ddof: int = 1) -> Self:
         """
         Get standard deviation.
@@ -4548,6 +4594,56 @@ def mean(*columns: str) -> Expr:
     return Expr(lambda plx: plx.mean(*columns))
 
 
+def median(*columns: str) -> Expr:
+    """
+    Get the median value.
+
+    Notes:
+        - Syntactic sugar for ``nw.col(columns).median()``
+        - Results might slightly differ across backends due to differences in the underlying algorithms used to compute the median.
+
+    Arguments:
+        columns: Name(s) of the columns to use in the aggregation function
+
+    Examples:
+        >>> import pandas as pd
+        >>> import polars as pl
+        >>> import pyarrow as pa
+        >>> import narwhals as nw
+        >>> df_pd = pd.DataFrame({"a": [4, 5, 2]})
+        >>> df_pl = pl.DataFrame({"a": [4, 5, 2]})
+        >>> df_pa = pa.table({"a": [4, 5, 2]})
+
+        Let's define a dataframe agnostic function:
+
+        >>> @nw.narwhalify
+        ... def func(df):
+        ...     return df.select(nw.median("a"))
+
+        We can then pass any supported library such as pandas, Polars, or PyArrow to `func`:
+
+        >>> func(df_pd)
+             a
+        0  4.0
+        >>> func(df_pl)
+        shape: (1, 1)
+        ┌─────┐
+        │ a   │
+        │ --- │
+        │ f64 │
+        ╞═════╡
+        │ 4.0 │
+        └─────┘
+        >>> func(df_pa)
+        pyarrow.Table
+        a: double
+        ----
+        a: [[4]]
+    """
+
+    return Expr(lambda plx: plx.median(*columns))
+
+
 def min(*columns: str) -> Expr:
     """
     Return the minimum value.

narwhals/series.py

@@ -521,6 +521,40 @@ def mean(self) -> Any:
         """
         return self._compliant_series.mean()
 
+    def median(self) -> Any:
+        """
+        Reduce this Series to the median value.
+
+        Notes:
+            Results might slightly differ across backends due to differences in the underlying algorithms used to compute the median.
+
+        Examples:
+            >>> import pandas as pd
+            >>> import polars as pl
+            >>> import pyarrow as pa
+            >>> import narwhals as nw
+            >>> s = [5, 3, 8]
+            >>> s_pd = pd.Series(s)
+            >>> s_pl = pl.Series(s)
+            >>> s_pa = pa.chunked_array([s])
+
+            Let's define a library agnostic function:
+
+            >>> @nw.narwhalify
+            ... def func(s):
+            ...     return s.median()
+
+            We can then pass any supported library such as pandas, Polars, or PyArrow to `func`:
+
+            >>> func(s_pd)
+            np.float64(5.0)
+            >>> func(s_pl)
+            5.0
+            >>> func(s_pa)
+            <pyarrow.DoubleScalar: 5.0>
+        """
+        return self._compliant_series.median()
+
     def count(self) -> Any:
         """
         Returns the number of non-null elements in the Series.

narwhals/stable/v1/__init__.py

@@ -1357,6 +1357,55 @@ def mean(*columns: str) -> Expr:
     return _stableify(nw.mean(*columns))
 
 
+def median(*columns: str) -> Expr:
+    """
+    Get the median value.
+
+    Notes:
+        - Syntactic sugar for ``nw.col(columns).median()``
+        - Results might slightly differ across backends due to differences in the underlying algorithms used to compute the median.
+
+    Arguments:
+        columns: Name(s) of the columns to use in the aggregation function
+
+    Examples:
+        >>> import pandas as pd
+        >>> import polars as pl
+        >>> import pyarrow as pa
+        >>> import narwhals.stable.v1 as nw
+        >>> df_pd = pd.DataFrame({"a": [4, 5, 2]})
+        >>> df_pl = pl.DataFrame({"a": [4, 5, 2]})
+        >>> df_pa = pa.table({"a": [4, 5, 2]})
+
+        Let's define a dataframe agnostic function:
+
+        >>> @nw.narwhalify
+        ... def func(df):
+        ...     return df.select(nw.median("a"))
+
+        We can then pass any supported library such as pandas, Polars, or PyArrow to `func`:
+
+        >>> func(df_pd)
+             a
+        0  4.0
+        >>> func(df_pl)
+        shape: (1, 1)
+        ┌─────┐
+        │ a   │
+        │ --- │
+        │ f64 │
+        ╞═════╡
+        │ 4.0 │
+        └─────┘
+        >>> func(df_pa)
+        pyarrow.Table
+        a: double
+        ----
+        a: [[4]]
+    """
+    return _stableify(nw.median(*columns))
+
+
 def sum(*columns: str) -> Expr:
     """
     Sum all values.
@@ -2461,6 +2510,7 @@ def from_dict(
     "max_horizontal",
     "mean",
     "mean_horizontal",
+    "median",
     "min",
     "min_horizontal",
     "sum",