Ë TÇ.h8ñãól—ddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlm Z dd lm Z dd lm Z dd l m Z dd lmZdd lmZddlmZerddlmZddlmZddlmZd;d„ZGd„d«Ze de¬«ZGd„dee«ZGd„dee«ZGd„dee«ZGd„dee«ZGd„d ee«Zdd#„Z"d>d$„Z#d?d%„Z$d?d&„Z%d?d'„Z&d?d(„Z'd?d)„Z(d@d*„Z)d@d+„Z*d@d,„Z+Gd-„d.«Z,Gd/„d0e«Z-dAd1„Z.d@d2„Z/dBdCd4„Z0d@d5„Z1d@d6„Z2d7d8d9œ dDd:„Z3dgZ4y3)Eé)Ú annotations)Ú TYPE_CHECKING)ÚAny)ÚCallable)ÚGeneric)ÚIterable)ÚLiteral)ÚMapping)ÚSequence)ÚTypeVar)Úis_numpy_array)Ú_validate_dtype)Ú_validate_rolling_arguments)Úflatten)ÚSelf)ÚDType)ÚIntoExprÚExprcó„—ddlm}t|t«r|j |«St||«r |j S|S)Nr)ÚSeries)Únarwhals.seriesrÚ isinstancerÚ_to_compliant_exprÚ_compliant_series)ÚexprÚotherrs úa/var/www/html/School_Mangement_New/src/backend/venv/lib/python3.12/site-packages/narwhals/expr.pyÚextract_compliantrs;€Ý&ä%œÔØ×'Ñ'¨Ó-Ð-Ü%˜Ô Ø×&Ñ&Ð&Ø €Lócó—eZdZdcd„Zddd„Zded„Zdfd„Zdgd„Zdhd„Zdhd„Z did„Z did „Z did „Z did „Z did „Zdid „Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zdid„Zddd„Z ddd„Z!ddd „Z"d!d!d!d!d"d#d$d%œ djd&„Z#ddd'„Z$ddd(„Z%d#d)œdkd*„Z& dl dmd+„Z'dnd,„Z(dod-„Z)ddd.„Z*ddd/„Z+ddd0„Z,ddd1„Z-ddd2„Z.ddd3„Z/d$d4œdpd5„Z0ddd6„Z1d$d7œdqd8„Z2ddd9„Z3drd:„Z4 dld!d;œ dsd<„Z5d$d$d=œdtd>„Z6 du dvd?„Z7did@„Z8dwdA„Z9dddB„Z:dddC„Z; dx dydD„Zd{dH„Z?dddI„Z@dddJ„ZAdddK„ZBdddL„ZCdddM„ZD d|dN„ZEd}drdO„ZFd}drdP„ZGd~ddQ„ZHdddR„ZId~d€dS„ZJ d d‚dT„ZKdndU„ZLdndV„ZMd$d7œdqdW„ZNd$d7œdqdX„ZOd$d7œdqdY„ZPd$d7œdqdZ„ZQd!d$d[œ dƒd\„ZRd!d$d[œ dƒd]„ZSeTd„d^„«ZUeTd…d_„«ZVeTd†d`„«ZWeTd‡da„«ZXeTdˆdb„«ZYy!)‰rcó—||_y©N)r)ÚselfÚto_compliant_exprs rÚ__init__z Expr.__init__$s €à"3ˆÕrcó,‡—‰jˆfd„«S)Ncó^•—‰j|«j«j«Sr")rÚabsÚsum©Úplxr#s €rúz$Expr._taxicab_norm..+s$ø€¨$×*AÑ*AÀ#Ó*F×*JÑ*JÓ*L×*PÑ*PÓ*R€r©Ú __class__©r#s`rÚ _taxicab_normzExpr._taxicab_norm(sø€ð~‰~ÓRÓSÐSrcó0‡‡—‰jˆˆfd„«S)uµRename the expression. Arguments: name: The new name. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [4, 5]}) >>> df_pl = pl.DataFrame({"a": [1, 2], "b": [4, 5]}) >>> df_pa = pa.table({"a": [1, 2], "b": [4, 5]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select((nw.col("b") + 10).alias("c")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) c 0 14 1 15 >>> my_library_agnostic_function(df_pl) shape: (2, 1) ┌─────┠│ c │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 14 │ │ 15 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table c: int64 ---- c: [[14,15]] cóD•—‰j|«j‰«Sr")rÚalias)r+Únamer#s €€rr,zExpr.alias..^sø€¨$×*AÑ*AÀ#Ó*F×*LÑ*LÈTÓ*R€rr-)r#r4s``rr3z Expr.alias.sù€ð`~‰~ÔRÓSÐSrcó—||g|¢­i|¤ŽS)ulPipe function call. Arguments: function: Function to apply. args: Positional arguments to pass to function. kwargs: Keyword arguments to pass to function. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3, 4]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Lets define a library-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").pipe(lambda x: x + 1)).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 2 1 3 2 4 3 5 >>> my_library_agnostic_function(df_pl) shape: (4, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 3 │ │ 4 │ │ 5 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[2,3,4,5]] ©)r#ÚfunctionÚargsÚkwargss rÚpipez Expr.pipe`s€ñl˜Ð.˜tÒ. vÑ.Ð.rcóF‡‡—t‰«‰jˆˆfd„«S)ugRedefine an object's data type. Arguments: dtype: Data type that the object will be cast into. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> from datetime import date >>> df_pd = pd.DataFrame({"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0]}) >>> df_pl = pl.DataFrame({"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0]}) >>> df_pa = pa.table({"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("foo").cast(nw.Float32), nw.col("bar").cast(nw.UInt8) ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) foo bar 0 1.0 6 1 2.0 7 2 3.0 8 >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌─────┬─────┠│ foo ┆ bar │ │ --- ┆ --- │ │ f32 ┆ u8 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1.0 ┆ 6 │ │ 2.0 ┆ 7 │ │ 3.0 ┆ 8 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table foo: float bar: uint8 ---- foo: [[1,2,3]] bar: [[6,7,8]] cóD•—‰j|«j‰«Sr")rÚcast)r+Údtyper#s €€rr,zExpr.cast..Ðsø€˜×/Ñ/°Ó4×9Ñ9¸%Ó@€r)rr.)r#r>s``rr=z Expr.cast˜s"ù€ôl ˜ÔØ~‰~Ü @ó ð rcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__eq__r©r+rr#s €€rr,zExpr.__eq__..Öó&ø€˜×/Ñ/°Ó4×;Ñ;Ô.ÛrCrr-rDs``rrHz Expr.__ne__ÙrErcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__and__rrBs €€rr,zExpr.__and__..àó'ø€˜×/Ñ/°Ó4×<Ñ<Ü! # uÓ-ó€rr-rDs``rrKz Expr.__and__Þóù€Ø~‰~ô ó ð rcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__rand__rrBs €€rr,zExpr.__rand__..çó'ø€˜×/Ñ/°Ó4×=Ñ=Ü! # uÓ-ó€rr-rDs``rrPz Expr.__rand__årMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__or__rrBs €€rr,zExpr.__or__..îrCrr-rDs``rrTz Expr.__or__ìrErcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__ror__rrBs €€rr,zExpr.__ror__..órLrr-rDs``rrWz Expr.__ror__ñrMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__add__rrBs €€rr,zExpr.__add__..úrLrr-rDs``rrZz Expr.__add__ørMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__radd__rrBs €€rr,zExpr.__radd__..rQrr-rDs``rr]z Expr.__radd__ÿrMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__sub__rrBs €€rr,zExpr.__sub__..rLrr-rDs``rr`z Expr.__sub__rMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__rsub__rrBs €€rr,zExpr.__rsub__..rQrr-rDs``rrcz Expr.__rsub__ rMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ __truediv__rrBs €€rr,z"Expr.__truediv__..s'ø€˜×/Ñ/°Ó4×@Ñ@Ü! # uÓ-ó€rr-rDs``rrfzExpr.__truediv__rMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ __rtruediv__rrBs €€rr,z#Expr.__rtruediv__..ó'ø€˜×/Ñ/°Ó4×AÑAÜ! # uÓ-ó€rr-rDs``rrizExpr.__rtruediv__rMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__mul__rrBs €€rr,zExpr.__mul__..$rLrr-rDs``rrmz Expr.__mul__"rMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__rmul__rrBs €€rr,zExpr.__rmul__..+rQrr-rDs``rrpz Expr.__rmul__)rMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__le__rrBs €€rr,zExpr.__le__..2rCrr-rDs``rrsz Expr.__le__0rErcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__lt__rrBs €€rr,zExpr.__lt__..7rCrr-rDs``rrvz Expr.__lt__5rErcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__gt__rrBs €€rr,zExpr.__gt__..<rCrr-rDs``rryz Expr.__gt__:rErcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__ge__rrBs €€rr,zExpr.__ge__..ArCrr-rDs``rr|z Expr.__ge__?rErcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__pow__rrBs €€rr,zExpr.__pow__..FrLrr-rDs``rrz Expr.__pow__DrMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__rpow__rrBs €€rr,zExpr.__rpow__..MrQrr-rDs``rr‚z Expr.__rpow__KrMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ __floordiv__rrBs €€rr,z#Expr.__floordiv__..Trjrr-rDs``rr…zExpr.__floordiv__RrMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ __rfloordiv__rrBs €€rr,z$Expr.__rfloordiv__..[s'ø€˜×/Ñ/°Ó4×BÑBÜ! # uÓ-ó€rr-rDs``rrˆzExpr.__rfloordiv__YrMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__mod__rrBs €€rr,zExpr.__mod__..brLrr-rDs``rr‹z Expr.__mod__`rMrcó0‡‡—‰jˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ__rmod__rrBs €€rr,zExpr.__rmod__..irQrr-rDs``rrŽz Expr.__rmod__grMrcó,‡—‰jˆfd„«S)NcóB•—‰j|«j«Sr")rÚ __invert__r*s €rr,z!Expr.__invert__..póø€¨$×*AÑ*AÀ#Ó*F×*QÑ*QÓ*S€rr-r/s`rr‘zExpr.__invert__osø€Ø~‰~ÓSÓTÐTrcó,‡—‰jˆfd„«S)uFReturn whether any of the values in the column are `True`. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [True, False], "b": [True, True]}) >>> df_pl = pl.DataFrame({"a": [True, False], "b": [True, True]}) >>> df_pa = pa.table({"a": [True, False], "b": [True, True]}) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").any()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 True True >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌──────┬──────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ true ┆ true │ └──────┴──────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: bool b: bool ---- a: [[true]] b: [[true]] cóB•—‰j|«j«Sr")rÚanyr*s €rr,zExpr.any..žóø€¨$×*AÑ*AÀ#Ó*F×*JÑ*JÓ*L€rr-r/s`rr•zExpr.anyróø€ðX~‰~ÓLÓMÐMrcó,‡—‰jˆfd„«S)uRReturn whether all values in the column are `True`. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [True, False], "b": [True, True]}) >>> df_pl = pl.DataFrame({"a": [True, False], "b": [True, True]}) >>> df_pa = pa.table({"a": [True, False], "b": [True, True]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").all()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 False True >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌───────┬──────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ false ┆ true │ └───────┴──────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: bool b: bool ---- a: [[false]] b: [[true]] cóB•—‰j|«j«Sr")rÚallr*s €rr,zExpr.all..Ìr–rr-r/s`rršzExpr.all r—rNTéF©ÚcomÚspanÚ half_lifeÚalphaÚadjustÚ min_periodsÚ ignore_nullsc óH‡‡‡‡‡‡‡‡—‰jˆˆˆˆˆˆˆˆfd„«S)u× Compute exponentially-weighted moving average. !!! warning This functionality is considered **unstable**. It may be changed at any point without it being considered a breaking change. Arguments: com: Specify decay in terms of center of mass, $\gamma$, with
$\alpha = \frac{1}{1+\gamma}\forall\gamma\geq0$ span: Specify decay in terms of span, $\theta$, with
$\alpha = \frac{2}{\theta + 1} \forall \theta \geq 1$ half_life: Specify decay in terms of half-life, $\tau$, with
$\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \tau } \right\} \forall \tau > 0$ alpha: Specify smoothing factor alpha directly, $0 < \alpha \leq 1$. adjust: Divide by decaying adjustment factor in beginning periods to account for imbalance in relative weightings - When `adjust=True` (the default) the EW function is calculated using weights $w_i = (1 - \alpha)^i$ - When `adjust=False` the EW function is calculated recursively by $$ y_0=x_0 $$ $$ y_t = (1 - \alpha)y_{t - 1} + \alpha x_t $$ min_periods: Minimum number of observations in window required to have a value, (otherwise result is null). ignore_nulls: Ignore missing values when calculating weights. - When `ignore_nulls=False` (default), weights are based on absolute positions. For example, the weights of $x_0$ and $x_2$ used in calculating the final weighted average of $[x_0, None, x_2]$ are $(1-\alpha)^2$ and $1$ if `adjust=True`, and $(1-\alpha)^2$ and $\alpha$ if `adjust=False`. - When `ignore_nulls=True`, weights are based on relative positions. For example, the weights of $x_0$ and $x_2$ used in calculating the final weighted average of $[x_0, None, x_2]$ are $1-\alpha$ and $1$ if `adjust=True`, and $1-\alpha$ and $\alpha$ if `adjust=False`. Returns: Expr Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a").ewm_mean(com=1, ignore_nulls=False) ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a 0 1.000000 1 1.666667 2 2.428571 >>> my_library_agnostic_function(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (3, 1) ┌──────────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•¡ │ 1.0 │ │ 1.666667 │ │ 2.428571 │ └──────────┘ c óR•—‰j|«j‰‰‰‰‰‰‰¬«S)Nrœ)rÚewm_mean) r+r¡r rrŸr£r¢r#ržs €€€€€€€€rr,zExpr.ewm_mean..(s7ø€˜×/Ñ/°Ó4×=Ñ=ØØØ#ØØØ'Ø)ð>ó€rr-)r#rržrŸr r¡r¢r£s````````rr¦z Expr.ewm_meanÎs!ÿ€ðr~‰~÷ ò ó  ð rcó,‡—‰jˆfd„«S)uíGet mean value. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [-1, 0, 1], "b": [2, 4, 6]}) >>> df_pl = pl.DataFrame({"a": [-1, 0, 1], "b": [2, 4, 6]}) >>> df_pa = pa.table({"a": [-1, 0, 1], "b": [2, 4, 6]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").mean()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 0.0 4.0 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 0.0 ┆ 4.0 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: double b: double ---- a: [[0]] b: [[4]] cóB•—‰j|«j«Sr")rÚmeanr*s €rr,zExpr.mean.._óø€¨$×*AÑ*AÀ#Ó*F×*KÑ*KÓ*M€rr-r/s`rr©z Expr.mean3sø€ðX~‰~ÓMÓNÐNrcó,‡—‰jˆfd„«S)u„Get median value. Returns: A new expression. 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 >>> from narwhals.typing import IntoFrameT >>> 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: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").median()).to_native() We can then pass any supported library such as pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 3.0 4.0 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 3.0 ┆ 4.0 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: double b: double ---- a: [[3]] b: [[4]] cóB•—‰j|«j«Sr")rÚmedianr*s €rr,zExpr.median..sø€¨$×*AÑ*AÀ#Ó*F×*MÑ*MÓ*O€rr-r/s`rr­z Expr.medianasø€ð^~‰~ÓOÓPÐPr©Úddofcó0‡‡—‰jˆˆfd„«S)u‘Get standard deviation. Arguments: ddof: "Delta Degrees of Freedom": the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is 1. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [20, 25, 60], "b": [1.5, 1, -1.4]}) >>> df_pl = pl.DataFrame({"a": [20, 25, 60], "b": [1.5, 1, -1.4]}) >>> df_pa = pa.table({"a": [20, 25, 60], "b": [1.5, 1, -1.4]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").std(ddof=0)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 17.79513 1.265789 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌──────────┬──────────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ 17.79513 ┆ 1.265789 │ └──────────┴──────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: double b: double ---- a: [[17.795130420052185]] b: [[1.2657891697365016]] cóF•—‰j|«j‰¬«S)Nr®)rÚstd)r+r¯r#s €€rr,zExpr.std..Ãs!ø€¨$×*AÑ*AÀ#Ó*F×*JÑ*JÐPTÐ*JÓ*U€rr-)r#r¯s``rr²zExpr.std’sù€ðb~‰~ÔUÓVÐVrcó4‡‡‡—‰jˆˆˆfd„«S)uÖApply a custom python function to a whole Series or sequence of Series. The output of this custom function is presumed to be either a Series, or a NumPy array (in which case it will be automatically converted into a Series). Arguments: function: Function to apply to Series. return_dtype: Dtype of the output Series. If not set, the dtype will be inferred based on the first non-null value that is returned by the function. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a", "b").map_batches( ... lambda s: s.to_numpy() + 1, return_dtype=nw.Float64 ... ) ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 2.0 5.0 1 3.0 6.0 2 4.0 7.0 >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 2.0 ┆ 5.0 │ │ 3.0 ┆ 6.0 │ │ 4.0 ┆ 7.0 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: double b: double ---- a: [[2,3,4]] b: [[5,6,7]] cóH•—‰j|«j‰‰¬«S)N)r7Ú return_dtype)rÚ map_batches)r+r7rµr#s €€€rr,z"Expr.map_batches.. s(ø€˜×/Ñ/°Ó4×@Ñ@Ø!° ðAó€rr-)r#r7rµs```rr¶zExpr.map_batchesÅsú€ðF~‰~õ ó ð rcó,‡—‰jˆfd„«S)u¦Calculate the sample skewness of a column. Returns: An expression representing the sample skewness of the column. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> df_pd = pd.DataFrame({"a": [1, 2, 3, 4, 5], "b": [1, 1, 2, 10, 100]}) >>> df_pl = pl.DataFrame({"a": [1, 2, 3, 4, 5], "b": [1, 1, 2, 10, 100]}) >>> df_pa = pa.Table.from_pandas(df_pd) Let's define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").skew()) We can then pass pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 0.0 1.472427 >>> func(df_pl) shape: (1, 2) ┌─────┬──────────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ 0.0 ┆ 1.472427 │ └─────┴──────────┘ >>> func(df_pa) pyarrow.Table a: double b: double ---- a: [[0]] b: [[1.4724267269058975]] cóB•—‰j|«j«Sr")rÚskewr*s €rr,zExpr.skew..9rªrr-r/s`rr¹z Expr.skewsø€ðV~‰~ÓMÓNÐNrcó,‡—‰jˆfd„«S)uèReturn the sum value. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [5, 10], "b": [50, 100]}) >>> df_pl = pl.DataFrame({"a": [5, 10], "b": [50, 100]}) >>> df_pa = pa.table({"a": [5, 10], "b": [50, 100]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").sum()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 15 150 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 15 ┆ 150 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[15]] b: [[150]] cóB•—‰j|«j«Sr")rr)r*s €rr,zExpr.sum..gr–rr-r/s`rr)zExpr.sum;r—rcó,‡—‰jˆfd„«S)uæReturns the minimum value(s) from a column(s). Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [4, 3]}) >>> df_pl = pl.DataFrame({"a": [1, 2], "b": [4, 3]}) >>> df_pa = pa.table({"a": [1, 2], "b": [4, 3]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.min("a", "b")).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 1 3 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 3 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1]] b: [[3]] cóB•—‰j|«j«Sr")rÚminr*s €rr,zExpr.min..•r–rr-r/s`rr¾zExpr.minir—rcó,‡—‰jˆfd„«S)uþReturns the maximum value(s) from a column(s). Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [10, 20], "b": [50, 100]}) >>> df_pl = pl.DataFrame({"a": [10, 20], "b": [50, 100]}) >>> df_pa = pa.table({"a": [10, 20], "b": [50, 100]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.max("a", "b")).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 20 100 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 20 ┆ 100 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[20]] b: [[100]] cóB•—‰j|«j«Sr")rÚmaxr*s €rr,zExpr.max..Ãr–rr-r/s`rrÁzExpr.max—r—rcó,‡—‰jˆfd„«S)uãReturns the index of the minimum value. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [10, 20], "b": [150, 100]}) >>> df_pl = pl.DataFrame({"a": [10, 20], "b": [150, 100]}) >>> df_pa = pa.table({"a": [10, 20], "b": [150, 100]}) Let's define a dataframe-agnostic function: >>> def agnostic_arg_min(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a", "b").arg_min().name.suffix("_arg_min") ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow: >>> agnostic_arg_min(df_pd) a_arg_min b_arg_min 0 0 1 >>> agnostic_arg_min(df_pl) shape: (1, 2) ┌───────────┬───────────┠│ a_arg_min ┆ b_arg_min │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ 0 ┆ 1 │ └───────────┴───────────┘ >>> agnostic_arg_min(df_pa) pyarrow.Table a_arg_min: int64 b_arg_min: int64 ---- a_arg_min: [[0]] b_arg_min: [[1]] cóB•—‰j|«j«Sr")rÚarg_minr*s €rr,zExpr.arg_min..óóø€¨$×*AÑ*AÀ#Ó*F×*NÑ*NÓ*P€rr-r/s`rrÄz Expr.arg_minÅóø€ð\~‰~ÓPÓQÐQrcó,‡—‰jˆfd„«S)uãReturns the index of the maximum value. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [10, 20], "b": [150, 100]}) >>> df_pl = pl.DataFrame({"a": [10, 20], "b": [150, 100]}) >>> df_pa = pa.table({"a": [10, 20], "b": [150, 100]}) Let's define a dataframe-agnostic function: >>> def agnostic_arg_max(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a", "b").arg_max().name.suffix("_arg_max") ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow: >>> agnostic_arg_max(df_pd) a_arg_max b_arg_max 0 1 0 >>> agnostic_arg_max(df_pl) shape: (1, 2) ┌───────────┬───────────┠│ a_arg_max ┆ b_arg_max │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ 1 ┆ 0 │ └───────────┴───────────┘ >>> agnostic_arg_max(df_pa) pyarrow.Table a_arg_max: int64 b_arg_max: int64 ---- a_arg_max: [[1]] b_arg_max: [[0]] cóB•—‰j|«j«Sr")rÚarg_maxr*s €rr,zExpr.arg_max..#rÅrr-r/s`rrÉz Expr.arg_maxõrÆrcó,‡—‰jˆfd„«S)u Returns the number of non-null elements in the column. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2, 3], "b": [None, 4, 4]}) >>> df_pl = pl.DataFrame({"a": [1, 2, 3], "b": [None, 4, 4]}) >>> df_pa = pa.table({"a": [1, 2, 3], "b": [None, 4, 4]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.all().count()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 3 2 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 3 ┆ 2 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[3]] b: [[2]] cóB•—‰j|«j«Sr")rÚcountr*s €rr,zExpr.count..Qsø€¨$×*AÑ*AÀ#Ó*F×*LÑ*LÓ*N€rr-r/s`rrÌz Expr.count%sø€ðX~‰~ÓNÓOÐOrcó,‡—‰jˆfd„«S)uReturns count of unique values. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2, 3, 4, 5], "b": [1, 1, 3, 3, 5]}) >>> df_pl = pl.DataFrame({"a": [1, 2, 3, 4, 5], "b": [1, 1, 3, 3, 5]}) >>> df_pa = pa.table({"a": [1, 2, 3, 4, 5], "b": [1, 1, 3, 3, 5]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").n_unique()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 5 3 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 5 ┆ 3 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[5]] b: [[3]] cóB•—‰j|«j«Sr")rÚn_uniquer*s €rr,zExpr.n_unique..óø€¨$×*AÑ*AÀ#Ó*F×*OÑ*OÓ*Q€rr-r/s`rrÏz Expr.n_uniqueSsø€ðX~‰~ÓQÓRÐRr©Úmaintain_ordercó0‡‡—‰jˆˆfd„«S)u£Return unique values of this expression. Arguments: maintain_order: Keep the same order as the original expression. This may be more expensive to compute. Settings this to `True` blocks the possibility to run on the streaming engine for Polars. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 1, 3, 5, 5], "b": [2, 4, 4, 6, 6]}) >>> df_pl = pl.DataFrame({"a": [1, 1, 3, 5, 5], "b": [2, 4, 4, 6, 6]}) >>> df_pa = pa.table({"a": [1, 1, 3, 5, 5], "b": [2, 4, 4, 6, 6]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").unique(maintain_order=True)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 1 2 1 3 4 2 5 6 >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 2 │ │ 3 ┆ 4 │ │ 5 ┆ 6 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1,3,5]] b: [[2,4,6]] cóF•—‰j|«j‰¬«S)NrÑ)rÚunique)r+rÒr#s €€rr,zExpr.unique..·s ø€˜×/Ñ/°Ó4×;Ñ;È>Ð;ÓZ€rr-)r#rÒs``rrÕz Expr.uniquesù€ðj~‰~Ü Zó ð rcó,‡—‰jˆfd„«S)uReturn absolute value of each element. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, -2], "b": [-3, 4]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").abs()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 1 3 1 2 4 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 3 │ │ 2 ┆ 4 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1,2]] b: [[3,4]] cóB•—‰j|«j«Sr")rr(r*s €rr,zExpr.abs..ér–rr-r/s`rr(zExpr.absºsø€ð^~‰~ÓLÓMÐMr©Úreversecó0‡‡—‰jˆˆfd„«S)u>Return cumulative sum. Arguments: reverse: reverse the operation Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 1, 3, 5, 5], "b": [2, 4, 4, 6, 6]}) >>> df_pl = pl.DataFrame({"a": [1, 1, 3, 5, 5], "b": [2, 4, 4, 6, 6]}) >>> df_pa = pa.table({"a": [1, 1, 3, 5, 5], "b": [2, 4, 4, 6, 6]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a", "b").cum_sum()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 1 2 1 2 6 2 5 10 3 10 16 4 15 22 >>> my_library_agnostic_function(df_pl) shape: (5, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 2 │ │ 2 ┆ 6 │ │ 5 ┆ 10 │ │ 10 ┆ 16 │ │ 15 ┆ 22 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1,2,5,10,15]] b: [[2,6,10,16,22]] cóF•—‰j|«j‰¬«S©NrØ)rÚcum_sum©r+rÙr#s €€rr,zExpr.cum_sum..#ó ø€˜×/Ñ/°Ó4×<Ñ<ÀWÐ<ÓM€rr-©r#rÙs``rrÝz Expr.cum_sumësù€ðn~‰~Ü Mó ð rcó,‡—‰jˆfd„«S)u%Returns the difference between each element and the previous one. Returns: A new expression. Notes: pandas may change the dtype here, for example when introducing missing values in an integer column. To ensure, that the dtype doesn't change, you may want to use `fill_null` and `cast`. For example, to calculate the diff and fill missing values with `0` in a Int64 column, you could do: nw.col("a").diff().fill_null(0).cast(nw.Int64) Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 1, 3, 5, 5]}) >>> df_pl = pl.DataFrame({"a": [1, 1, 3, 5, 5]}) >>> df_pa = pa.table({"a": [1, 1, 3, 5, 5]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(a_diff=nw.col("a").diff()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a_diff 0 NaN 1 0.0 2 2.0 3 2.0 4 0.0 >>> my_library_agnostic_function(df_pl) shape: (5, 1) ┌────────┠│ a_diff │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•â•â•â•¡ │ null │ │ 0 │ │ 2 │ │ 2 │ │ 0 │ └────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a_diff: int64 ---- a_diff: [[null,0,2,2,0]] cóB•—‰j|«j«Sr")rÚdiffr*s €rr,zExpr.diff..arªrr-r/s`rrãz Expr.diff&sø€ðv~‰~ÓMÓNÐNrcó0‡‡—‰jˆˆfd„«S)u`Shift values by `n` positions. Arguments: n: Number of positions to shift values by. Returns: A new expression. Notes: pandas may change the dtype here, for example when introducing missing values in an integer column. To ensure, that the dtype doesn't change, you may want to use `fill_null` and `cast`. For example, to shift and fill missing values with `0` in a Int64 column, you could do: nw.col("a").shift(1).fill_null(0).cast(nw.Int64) Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 1, 3, 5, 5]}) >>> df_pl = pl.DataFrame({"a": [1, 1, 3, 5, 5]}) >>> df_pa = pa.table({"a": [1, 1, 3, 5, 5]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(a_shift=nw.col("a").shift(n=1)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a_shift 0 NaN 1 1.0 2 1.0 3 3.0 4 5.0 >>> my_library_agnostic_function(df_pl) shape: (5, 1) ┌─────────┠│ a_shift │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•¡ │ null │ │ 1 │ │ 1 │ │ 3 │ │ 5 │ └─────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a_shift: int64 ---- a_shift: [[null,1,1,3,5]] cóD•—‰j|«j‰«Sr")rÚshift©r+Únr#s €€rr,zExpr.shift..¡sø€¨$×*AÑ*AÀ#Ó*F×*LÑ*LÈQÓ*O€rr-©r#rès``rræz Expr.shiftcsù€ð|~‰~ÔOÓPÐPr©rµcóÚ‡‡‡‡—‰€Ot‰t«s d}t|«‚t‰j ««Št‰j ««Š‰j ˆˆˆˆfd„«S)u! Replace all values by different values. This function must replace all non-null input values (else it raises an error). Arguments: old: Sequence of values to replace. It also accepts a mapping of values to their replacement as syntactic sugar for `replace_all(old=list(mapping.keys()), new=list(mapping.values()))`. new: Sequence of values to replace by. Length must match the length of `old`. return_dtype: The data type of the resulting expression. If set to `None` (default), the data type is determined automatically based on the other inputs. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> df_pd = pd.DataFrame({"a": [3, 0, 1, 2]}) >>> df_pl = pl.DataFrame({"a": [3, 0, 1, 2]}) >>> df_pa = pa.table({"a": [3, 0, 1, 2]}) Let's define dataframe-agnostic functions: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... b=nw.col("a").replace_strict( ... [0, 1, 2, 3], ... ["zero", "one", "two", "three"], ... return_dtype=nw.String, ... ) ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 3 three 1 0 zero 2 1 one 3 2 two >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌─────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ str │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ 3 ┆ three │ │ 0 ┆ zero │ │ 1 ┆ one │ │ 2 ┆ two │ └─────┴───────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: string ---- a: [[3,0,1,2]] b: [["three","zero","one","two"]] zB`new` argument is required if `old` argument is not a Mapping typecóJ•—‰j|«j‰‰‰¬«S)Nrê)rÚreplace_strict)r+ÚnewÚoldrµr#s €€€€rr,z%Expr.replace_strict..õs*ø€˜×/Ñ/°Ó4×CÑCØS |ðDó€r)rr Ú TypeErrorÚlistÚvaluesÚkeysr.)r#rïrîrµÚmsgs```` rrízExpr.replace_strict£sZû€ðR ˆ;ܘc¤7Ô+ØZÜ “nÐ$äs—z‘z“|Ó$ˆCÜs—x‘x“zÓ"ˆCà~‰~ö ó ð r©Ú descendingÚ nulls_lastcó4‡‡‡—‰jˆˆˆfd„«S)u Sort this column. Place null values first. Arguments: descending: Sort in descending order. nulls_last: Place null values last instead of first. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> df_pd = pd.DataFrame({"a": [5, None, 1, 2]}) >>> df_pl = pl.DataFrame({"a": [5, None, 1, 2]}) >>> df_pa = pa.table({"a": [5, None, 1, 2]}) Let's define dataframe-agnostic functions: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").sort()).to_native() >>> def func_descend(df): ... df = nw.from_native(df) ... df = df.select(nw.col("a").sort(descending=True)) ... return nw.to_native(df) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 1 NaN 2 1.0 3 2.0 0 5.0 >>> my_library_agnostic_function(df_pl) shape: (4, 1) ┌──────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•â•¡ │ null │ │ 1 │ │ 2 │ │ 5 │ └──────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[null,1,2,5]] >>> func_descend(df_pd) a 1 NaN 0 5.0 3 2.0 2 1.0 >>> func_descend(df_pl) shape: (4, 1) ┌──────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•â•¡ │ null │ │ 5 │ │ 2 │ │ 1 │ └──────┘ >>> func_descend(df_pa) pyarrow.Table a: int64 ---- a: [[null,5,2,1]] cóH•—‰j|«j‰‰¬«S)Nrõ)rÚsort)r+rör÷r#s €€€rr,zExpr.sort..Ls'ø€˜×/Ñ/°Ó4×9Ñ9Ø%°*ð:ó€rr-)r#rör÷s```rrúz Expr.sortúsú€ðb~‰~õ ó ð rcó8‡‡‡‡—‰jˆˆˆˆfd„«S)u2Check if this expression is between the given lower and upper bounds. Arguments: lower_bound: Lower bound value. upper_bound: Upper bound value. closed: Define which sides of the interval are closed (inclusive). Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2, 3, 4, 5]}) >>> df_pl = pl.DataFrame({"a": [1, 2, 3, 4, 5]}) >>> df_pa = pa.table({"a": [1, 2, 3, 4, 5]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").is_between(2, 4, "right")).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 False 1 False 2 True 3 True 4 False >>> my_library_agnostic_function(df_pl) shape: (5, 1) ┌───────┠│ a │ │ --- │ │ bool │ â•žâ•â•â•â•â•â•â•â•¡ │ false │ │ false │ │ true │ │ true │ │ false │ └───────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: bool ---- a: [[false,false,true,true,false]] cóH•—‰j|«j‰‰‰«Sr")rÚ is_between)r+ÚclosedÚ lower_boundr#Ú upper_bounds €€€€rr,z!Expr.is_between..Œs$ø€˜×/Ñ/°Ó4×?Ñ?ؘ[¨&ó€rr-)r#rÿrrþs````rrýzExpr.is_betweenRsû€ðr~‰~ö ó ð rc󖇇—t‰t«r+t‰ttf«s‰j ˆˆfd„«Sd}t |«‚)uCheck if elements of this expression are present in the other iterable. Arguments: other: iterable Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2, 9, 10]}) >>> df_pl = pl.DataFrame({"a": [1, 2, 9, 10]}) >>> df_pa = pa.table({"a": [1, 2, 9, 10]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns(b=nw.col("a").is_in([1, 2])).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 1 True 1 2 True 2 9 False 3 10 False >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌─────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ bool │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ 1 ┆ true │ │ 2 ┆ true │ │ 9 ┆ false │ │ 10 ┆ false │ └─────┴───────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: bool ---- a: [[1,2,9,10]] b: [[true,true,false,false]] cóD•—‰j|«j‰«Sr")rÚis_inrBs €€rr,zExpr.is_in..Èsø€¨d×.EÑ.EÀcÓ.J×.PÑ.PÐQVÓ.W€rzyNarwhals `is_in` doesn't accept expressions as an argument, as opposed to Polars. You should provide an iterable instead.)rrÚstrÚbytesr.ÚNotImplementedError)r#rrôs`` rrz Expr.is_in‘s@ù€ôl eœXÔ &¬z¸%Ä#ÄuÀÔ/NØ—>‘>Ô"WÓXÐ XðNˆCÜ% cÓ*Ð *rcó0‡‡—‰jˆˆfd„«S)u«Filters elements based on a condition, returning a new expression. Arguments: predicates: Conditions to filter by (which get ANDed together). Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [2, 3, 4, 5, 6, 7], "b": [10, 11, 12, 13, 14, 15]}) >>> df_pl = pl.DataFrame({"a": [2, 3, 4, 5, 6, 7], "b": [10, 11, 12, 13, 14, 15]}) >>> df_pa = pa.table({"a": [2, 3, 4, 5, 6, 7], "b": [10, 11, 12, 13, 14, 15]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a").filter(nw.col("a") > 4), ... nw.col("b").filter(nw.col("b") < 13), ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 3 5 10 4 6 11 5 7 12 >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 5 ┆ 10 │ │ 6 ┆ 11 │ │ 7 ┆ 12 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[5,6,7]] b: [[10,11,12]] c 󌕗‰j|«jt‰«Dcgc]}t||«‘Œc}ŽScc}wr")rÚfilterrr)r+ÚpredÚ predicatesr#s €€rr,zExpr.filter..s>ø€Ð;˜×/Ñ/°Ó4×;Ñ;Ü;BÀ:Ó;NÖO°4Ô# C¨Õ.ÒOð€ùÚOsªAr-©r#r s``rr z Expr.filterÍsù€ðl~‰~ô ó ð rcó,‡—‰jˆfd„«S)u Returns a boolean Series indicating which values are null. Returns: A new expression. Notes: pandas, Polars and PyArrow handle null values differently. Polars and PyArrow distinguish between NaN and Null, whereas pandas doesn't. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame( ... {"a": [2, 4, None, 3, 5], "b": [2.0, 4.0, float("nan"), 3.0, 5.0]} ... ) >>> df_pl = pl.DataFrame( ... {"a": [2, 4, None, 3, 5], "b": [2.0, 4.0, float("nan"), 3.0, 5.0]} ... ) >>> df_pa = pa.table( ... {"a": [2, 4, None, 3, 5], "b": [2.0, 4.0, float("nan"), 3.0, 5.0]} ... ) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... a_is_null=nw.col("a").is_null(), b_is_null=nw.col("b").is_null() ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b a_is_null b_is_null 0 2.0 2.0 False False 1 4.0 4.0 False False 2 NaN NaN True True 3 3.0 3.0 False False 4 5.0 5.0 False False >>> my_library_agnostic_function(df_pl) # nan != null for polars shape: (5, 4) ┌──────┬─────┬───────────┬───────────┠│ a ┆ b ┆ a_is_null ┆ b_is_null │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ bool ┆ bool │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2 ┆ 2.0 ┆ false ┆ false │ │ 4 ┆ 4.0 ┆ false ┆ false │ │ null ┆ NaN ┆ true ┆ false │ │ 3 ┆ 3.0 ┆ false ┆ false │ │ 5 ┆ 5.0 ┆ false ┆ false │ └──────┴─────┴───────────┴───────────┘ >>> my_library_agnostic_function(df_pa) # nan != null for pyarrow pyarrow.Table a: int64 b: double a_is_null: bool b_is_null: bool ---- a: [[2,4,null,3,5]] b: [[2,4,nan,3,5]] a_is_null: [[false,false,true,false,false]] b_is_null: [[false,false,false,false,false]] cóB•—‰j|«j«Sr")rÚis_nullr*s €rr,zExpr.is_null..OrÅrr-r/s`rrz Expr.is_null sø€ðL~‰~ÓPÓQÐQrcó,‡—‰jˆfd„«S)u†Find elements where boolean expression is True. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, None, None, 2]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").is_null().arg_true()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 1 1 2 2 >>> my_library_agnostic_function(df_pl) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ u32 │ â•žâ•â•â•â•â•â•¡ │ 1 │ │ 2 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[1,2]] cóB•—‰j|«j«Sr")rÚarg_truer*s €rr,zExpr.arg_true..~rÐrr-r/s`rrz Expr.arg_trueQsø€ðZ~‰~ÓQÓRÐRrc󨇇‡‡—‰‰ d}t|«‚‰€‰€ d}t|«‚‰‰dvrd‰›}t|«‚‰jˆˆˆˆfd„«S)u Fill null values with given value. Arguments: value: Value used to fill null values. strategy: Strategy used to fill null values. limit: Number of consecutive null values to fill when using the 'forward' or 'backward' strategy. Returns: A new expression. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame( ... { ... "a": [2, 4, None, None, 3, 5], ... "b": [2.0, 4.0, float("nan"), float("nan"), 3.0, 5.0], ... } ... ) >>> df_pl = pl.DataFrame( ... { ... "a": [2, 4, None, None, 3, 5], ... "b": [2.0, 4.0, float("nan"), float("nan"), 3.0, 5.0], ... } ... ) >>> df_pa = pa.table( ... { ... "a": [2, 4, None, None, 3, 5], ... "b": [2.0, 4.0, float("nan"), float("nan"), 3.0, 5.0], ... } ... ) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns(nw.col("a", "b").fill_null(0)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 2.0 2.0 1 4.0 4.0 2 0.0 0.0 3 0.0 0.0 4 3.0 3.0 5 5.0 5.0 >>> my_library_agnostic_function(df_pl) # nan != null for polars shape: (6, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ f64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 2 ┆ 2.0 │ │ 4 ┆ 4.0 │ │ 0 ┆ NaN │ │ 0 ┆ NaN │ │ 3 ┆ 3.0 │ │ 5 ┆ 5.0 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) # nan != null for pyarrow pyarrow.Table a: int64 b: double ---- a: [[2,4,0,0,3,5]] b: [[2,4,nan,nan,3,5]] Using a strategy: >>> def func_strategies(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("a", "b") ... .fill_null(strategy="forward", limit=1) ... .name.suffix("_filled") ... ).to_native() >>> func_strategies(df_pd) a b a_filled b_filled 0 2.0 2.0 2.0 2.0 1 4.0 4.0 4.0 4.0 2 NaN NaN 4.0 4.0 3 NaN NaN NaN NaN 4 3.0 3.0 3.0 3.0 5 5.0 5.0 5.0 5.0 >>> func_strategies(df_pl) # nan != null for polars shape: (6, 4) ┌──────┬─────┬──────────┬──────────┠│ a ┆ b ┆ a_filled ┆ b_filled │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ i64 ┆ f64 │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ 2 ┆ 2.0 ┆ 2 ┆ 2.0 │ │ 4 ┆ 4.0 ┆ 4 ┆ 4.0 │ │ null ┆ NaN ┆ 4 ┆ NaN │ │ null ┆ NaN ┆ null ┆ NaN │ │ 3 ┆ 3.0 ┆ 3 ┆ 3.0 │ │ 5 ┆ 5.0 ┆ 5 ┆ 5.0 │ └──────┴─────┴──────────┴──────────┘ >>> func_strategies(df_pa) # nan != null for pyarrow pyarrow.Table a: int64 b: double a_filled: int64 b_filled: double ---- a: [[2,4,null,null,3,5]] b: [[2,4,nan,nan,3,5]] a_filled: [[2,4,4,null,3,5]] b_filled: [[2,4,nan,nan,3,5]] z*cannot specify both `value` and `strategy`z0must specify either a fill `value` or `strategy`>ÚforwardÚbackwardzstrategy not supported: cóJ•—‰j|«j‰‰‰¬«S)N)ÚvalueÚstrategyÚlimit)rÚ fill_null)r+rr#rrs €€€€rr,z Expr.fill_null.. s)ø€˜×/Ñ/°Ó4×>Ñ>Ø h°eð?ó€r)Ú ValueErrorr.)r#rrrrôs```` rrzExpr.fill_null€ssû€ðF Ð  Ð!5Ø>ˆCܘS“/Ð !Ø ˆ=˜XÐ-ØDˆCܘS“/Ð !Ø Ð  HÐ4KÑ$KØ,¨X¨JÐ7ˆCܘS“/Ð !Ø~‰~ö ó ð rcó,‡—‰jˆfd„«S)u Remove missing values. Returns: A new expression. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> df_pd = pd.DataFrame({"a": [2.0, 4.0, float("nan"), 3.0, None, 5.0]}) >>> df_pl = pl.DataFrame({"a": [2.0, 4.0, float("nan"), 3.0, None, 5.0]}) >>> df_pa = pa.table({"a": [2.0, 4.0, float("nan"), 3.0, None, 5.0]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").drop_nulls()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 2.0 1 4.0 3 3.0 5 5.0 >>> my_library_agnostic_function(df_pl) # nan != null for polars shape: (5, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 2.0 │ │ 4.0 │ │ NaN │ │ 3.0 │ │ 5.0 │ └─────┘ >>> my_library_agnostic_function(df_pa) # nan != null for pyarrow pyarrow.Table a: double ---- a: [[2,4,nan,3,5]] cóB•—‰j|«j«Sr")rÚ drop_nullsr*s €rr,z!Expr.drop_nulls..Ir’rr-r/s`rrzExpr.drop_nullssø€ðl~‰~ÓSÓTÐTr©ÚfractionÚwith_replacementÚseedcó<‡‡‡‡‡—‰jˆˆˆˆˆfd„«S)u¡Sample randomly from this expression. Arguments: n: Number of items to return. Cannot be used with fraction. fraction: Fraction of items to return. Cannot be used with n. with_replacement: Allow values to be sampled more than once. seed: Seed for the random number generator. If set to None (default), a random seed is generated for each sample operation. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> df_pd = pd.DataFrame({"a": [1, 2, 3]}) >>> df_pl = pl.DataFrame({"a": [1, 2, 3]}) >>> df_pa = pa.table({"a": [1, 2, 3]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a").sample(fraction=1.0, with_replacement=True) ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) # doctest: +SKIP a 2 3 0 1 2 3 >>> my_library_agnostic_function(df_pl) # doctest: +SKIP shape: (3, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 3 │ │ 3 │ └─────┘ >>> my_library_agnostic_function(df_pa) # doctest: +SKIP pyarrow.Table a: int64 ---- a: [[1,3,3]] cóL•—‰j|«j‰‰‰‰¬«S)Nr)rÚsample)r+r rèr"r#r!s €€€€€rr,zExpr.sample..Šs,ø€˜×/Ñ/°Ó4×;Ñ;ؘHÐ7GÈdð<ó€rr-)r#rèr r!r"s`````rr%z Expr.sampleKsü€ð|~‰~÷ ó ð rcó0‡‡—‰jˆˆfd„«S)u- Compute expressions over the given groups. Arguments: keys: Names of columns to compute window expression over. Must be names of columns, as opposed to expressions - so, this is a bit less flexible than Polars' `Expr.over`. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1, 2, 3], "b": [1, 1, 2]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... a_min_per_group=nw.col("a").min().over("b") ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b a_min_per_group 0 1 1 1 1 2 1 1 2 3 2 3 >>> my_library_agnostic_function(df_pl) shape: (3, 3) ┌─────┬─────┬─────────────────┠│ a ┆ b ┆ a_min_per_group │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 1 ┆ 1 ┆ 1 │ │ 2 ┆ 1 ┆ 1 │ │ 3 ┆ 2 ┆ 3 │ └─────┴─────┴─────────────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 a_min_per_group: int64 ---- a: [[1,2,3]] b: [[1,1,2]] a_min_per_group: [[1,1,3]] cóV•—‰j|«jt‰««Sr")rÚoverr)r+rór#s €€rr,zExpr.over..Ês!ø€˜×/Ñ/°Ó4×9Ñ9¼'À$»-ÓH€rr-)r#rós``rr(z Expr.oversù€ðt~‰~Ü Hó ð rcó,‡—‰jˆfd„«S)u!Return a boolean mask indicating duplicated values. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1, 2, 3, 1], "b": ["a", "a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.all().is_duplicated()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 True True 1 False True 2 False False 3 True False >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌───────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ true ┆ true │ │ false ┆ true │ │ false ┆ false │ │ true ┆ false │ └───────┴───────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: bool b: bool ---- a: [[true,false,false,true]] b: [[true,true,false,false]] cóB•—‰j|«j«Sr")rÚ is_duplicatedr*s €rr,z$Expr.is_duplicated.. sø€¨$×*AÑ*AÀ#Ó*F×*TÑ*TÓ*V€rr-r/s`rr+zExpr.is_duplicatedÍsø€ðf~‰~ÓVÓWÐWrcó,‡—‰jˆfd„«S)uReturn a boolean mask indicating unique values. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1, 2, 3, 1], "b": ["a", "a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.all().is_unique()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 False False 1 True False 2 True True 3 False True >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌───────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ false ┆ false │ │ true ┆ false │ │ true ┆ true │ │ false ┆ true │ └───────┴───────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: bool b: bool ---- a: [[false,true,true,false]] b: [[false,false,true,true]] cóB•—‰j|«j«Sr")rÚ is_uniquer*s €rr,z Expr.is_unique..5 óø€¨$×*AÑ*AÀ#Ó*F×*PÑ*PÓ*R€rr-r/s`rr.zExpr.is_unique sø€ðf~‰~ÓRÓSÐSrcó,‡—‰jˆfd„«S)uuCount null values. Returns: A new expression. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1, 2, None, 1], "b": ["a", None, "b", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.all().null_count()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 1 2 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 2 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1]] b: [[2]] cóB•—‰j|«j«Sr")rÚ null_countr*s €rr,z!Expr.null_count..h r’rr-r/s`rr2zExpr.null_count7 sø€ðb~‰~ÓSÓTÐTrcó,‡—‰jˆfd„«S)u=Return a boolean mask indicating the first occurrence of each distinct value. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1, 2, 3, 1], "b": ["a", "a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.all().is_first_distinct()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 True True 1 True False 2 True True 3 False True >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌───────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ true ┆ true │ │ true ┆ false │ │ true ┆ true │ │ false ┆ true │ └───────┴───────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: bool b: bool ---- a: [[true,true,true,false]] b: [[true,false,true,true]] cóB•—‰j|«j«Sr")rÚis_first_distinctr*s €rr,z(Expr.is_first_distinct..ž sø€˜×/Ñ/°Ó4×FÑFÓH€rr-r/s`rr5zExpr.is_first_distinctj sø€ðf~‰~Û Hó ð rcó,‡—‰jˆfd„«S)u;Return a boolean mask indicating the last occurrence of each distinct value. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1, 2, 3, 1], "b": ["a", "a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.all().is_last_distinct()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 False False 1 True True 2 True True 3 True True >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌───────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ false ┆ false │ │ true ┆ true │ │ true ┆ true │ │ true ┆ true │ └───────┴───────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: bool b: bool ---- a: [[false,true,true,true]] b: [[false,true,true,true]] cóB•—‰j|«j«Sr")rÚis_last_distinctr*s €rr,z'Expr.is_last_distinct..Ô sø€¨$×*AÑ*AÀ#Ó*F×*WÑ*WÓ*Y€rr-r/s`rr8zExpr.is_last_distinct¡ sø€ðf~‰~ÓYÓZÐZrcó4‡‡‡—‰jˆˆˆfd„«S)u›Get quantile value. Arguments: quantile: Quantile between 0.0 and 1.0. interpolation: Interpolation method. Returns: A new expression. Note: - pandas and Polars may have implementation differences for a given interpolation method. - [dask](https://docs.dask.org/en/stable/generated/dask.dataframe.Series.quantile.html) has its own method to approximate quantile and it doesn't implement 'nearest', 'higher', 'lower', 'midpoint' as interpolation method - use 'linear' which is closest to the native 'dask' - method. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": list(range(50)), "b": list(range(50, 100))} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a", "b").quantile(0.5, interpolation="linear") ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 24.5 74.5 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌──────┬──────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ 24.5 ┆ 74.5 │ └──────┴──────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: double b: double ---- a: [[24.5]] b: [[74.5]] cóF•—‰j|«j‰‰«Sr")rÚquantile)r+Ú interpolationr;r#s €€€rr,zExpr.quantile.. sø€˜×/Ñ/°Ó4×=Ñ=¸hÈ ÓV€rr-)r#r;r<s```rr;z Expr.quantileÖ sú€ð~~‰~Ý Vó ð rcó0‡‡—‰jˆˆfd„«S)uéGet the first `n` rows. Arguments: n: Number of rows to return. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": list(range(10))} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function that returns the first 3 rows: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").head(3)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 0 1 1 2 2 >>> my_library_agnostic_function(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 0 │ │ 1 │ │ 2 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[0,1,2]] cóD•—‰j|«j‰«Sr")rÚheadrçs €€rr,zExpr.head..K óø€¨$×*AÑ*AÀ#Ó*F×*KÑ*KÈAÓ*N€rr-rés``rr?z Expr.head óù€ðd~‰~ÔNÓOÐOrcó0‡‡—‰jˆˆfd„«S)uçGet the last `n` rows. Arguments: n: Number of rows to return. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": list(range(10))} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function that returns the last 3 rows: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").tail(3)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 7 7 8 8 9 9 >>> my_library_agnostic_function(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 7 │ │ 8 │ │ 9 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[7,8,9]] cóD•—‰j|«j‰«Sr")rÚtailrçs €€rr,zExpr.tail.. r@rr-rés``rrDz Expr.tailM rArcó0‡‡—‰jˆˆfd„«S)uÊRound underlying floating point data by `decimals` digits. Arguments: decimals: Number of decimals to round by. Returns: A new expression. Notes: For values exactly halfway between rounded decimal values pandas behaves differently than Polars and Arrow. 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 and Arrow round 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 >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1.12345, 2.56789, 3.901234]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function that rounds to the first decimal: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").round(1)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 1.1 1 2.6 2 3.9 >>> my_library_agnostic_function(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 1.1 │ │ 2.6 │ │ 3.9 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: double ---- a: [[1.1,2.6,3.9]] cóD•—‰j|«j‰«Sr")rÚround)r+Údecimalsr#s €€rr,zExpr.round..¼ sø€¨$×*AÑ*AÀ#Ó*F×*LÑ*LÈXÓ*V€rr-)r#rHs``rrGz Expr.round sù€ðv~‰~ÔVÓWÐWrcó,‡—‰jˆfd„«S)uõReturn the number of elements in the column. Null values count towards the total. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": ["x", "y", "z"], "b": [1, 2, 1]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function that computes the len over different values of "b" column: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a").filter(nw.col("b") == 1).len().alias("a1"), ... nw.col("a").filter(nw.col("b") == 2).len().alias("a2"), ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a1 a2 0 2 1 >>> my_library_agnostic_function(df_pl) shape: (1, 2) ┌─────┬─────┠│ a1 ┆ a2 │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 2 ┆ 1 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a1: int64 a2: int64 ---- a1: [[2]] a2: [[1]] cóB•—‰j|«j«Sr")rÚlenr*s €rr,zExpr.len..ð r–rr-r/s`rrKzExpr.len¾ sø€ðd~‰~ÓLÓMÐMrcó4‡‡‡—‰jˆˆˆfd„«S)uRTake every nth value in the Series and return as new Series. Arguments: n: Gather every *n*-th row. offset: Starting index. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1, 2, 3, 4], "b": [5, 6, 7, 8]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function in which gather every 2 rows, starting from a offset of 1: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").gather_every(n=2, offset=1)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 1 2 3 4 >>> my_library_agnostic_function(df_pl) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 4 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[2,4]] cóH•—‰j|«j‰‰¬«S)N)rèÚoffset)rÚ gather_every)r+rèrNr#s €€€rr,z#Expr.gather_every..% s"ø€˜×/Ñ/°Ó4×AÑAÀAÈfÐAÓU€rr-)r#rèrNs```rrOzExpr.gather_everyò sú€ðd~‰~Ý Uó ð rcó4‡‡‡—‰jˆˆˆfd„«S)uKClip values in the Series. Arguments: lower_bound: Lower bound value. upper_bound: Upper bound value. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> s = [1, 2, 3] >>> df_pd = pd.DataFrame({"s": s}) >>> df_pl = pl.DataFrame({"s": s}) >>> df_pa = pa.table({"s": s}) We define a library agnostic function: >>> def func_lower(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("s").clip(2)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func_lower`: >>> func_lower(df_pd) s 0 2 1 2 2 3 >>> func_lower(df_pl) shape: (3, 1) ┌─────┠│ s │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 2 │ │ 3 │ └─────┘ >>> func_lower(df_pa) pyarrow.Table s: int64 ---- s: [[2,2,3]] We define another library agnostic function: >>> def func_upper(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("s").clip(upper_bound=2)).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func_upper`: >>> func_upper(df_pd) s 0 1 1 2 2 2 >>> func_upper(df_pl) shape: (3, 1) ┌─────┠│ s │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 1 │ │ 2 │ │ 2 │ └─────┘ >>> func_upper(df_pa) pyarrow.Table s: int64 ---- s: [[1,2,2]] We can have both at the same time >>> s = [-1, 1, -3, 3, -5, 5] >>> df_pd = pd.DataFrame({"s": s}) >>> df_pl = pl.DataFrame({"s": s}) >>> df_pa = pa.table({"s": s}) We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("s").clip(-1, 3)).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) s 0 -1 1 1 2 -1 3 3 4 -1 5 3 >>> my_library_agnostic_function(df_pl) shape: (6, 1) ┌─────┠│ s │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ -1 │ │ 1 │ │ -1 │ │ 3 │ │ -1 │ │ 3 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table s: int64 ---- s: [[-1,1,-1,3,-1,3]] cóF•—‰j|«j‰‰«Sr")rÚclip)r+rÿr#rs €€€rr,zExpr.clip..¬ sø€˜×/Ñ/°Ó4×9Ñ9¸+À{ÓS€rr-)r#rÿrs```rrRz Expr.clip* sú€ðB~‰~Ý Só ð rcó,‡—‰jˆfd„«S)u¼Compute the most occurring value(s). Can return multiple values. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": [1, 1, 2, 3], ... "b": [1, 1, 2, 2], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").mode()).sort("a").to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 1 >>> my_library_agnostic_function(df_pl) shape: (1, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 1 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[1]] cóB•—‰j|«j«Sr")rÚmoder*s €rr,zExpr.mode..â rªrr-r/s`rrUz Expr.mode¯ sø€ðf~‰~ÓMÓNÐNrcó,‡—‰jˆfd„«S)uReturns boolean values indicating which original values are finite. Warning: Different backend handle null values differently. `is_finite` will return False for NaN and Null's in the Dask and pandas non-nullable backend, while for Polars, PyArrow and pandas nullable backends null values are kept as such. Returns: Expression of `Boolean` data type. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [float("nan"), float("inf"), 2.0, None]} We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").is_finite()).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.DataFrame(data)) a 0 False 1 False 2 True 3 False >>> my_library_agnostic_function(pl.DataFrame(data)) shape: (4, 1) ┌───────┠│ a │ │ --- │ │ bool │ â•žâ•â•â•â•â•â•â•â•¡ │ false │ │ false │ │ true │ │ null │ └───────┘ >>> my_library_agnostic_function(pa.table(data)) pyarrow.Table a: bool ---- a: [[false,false,true,null]] cóB•—‰j|«j«Sr")rÚ is_finiter*s €rr,z Expr.is_finite.. r/rr-r/s`rrXzExpr.is_finiteä sø€ðh~‰~ÓRÓSÐSrcó0‡‡—‰jˆˆfd„«S)uÜ Return the cumulative count of the non-null values in the column. Arguments: reverse: reverse the operation Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": ["x", "k", None, "d"]} We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("a").cum_count().alias("cum_count"), ... nw.col("a").cum_count(reverse=True).alias("cum_count_reverse"), ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.DataFrame(data)) a cum_count cum_count_reverse 0 x 1 3 1 k 2 2 2 None 2 1 3 d 3 1 >>> my_library_agnostic_function(pl.DataFrame(data)) shape: (4, 3) ┌──────┬───────────┬───────────────────┠│ a ┆ cum_count ┆ cum_count_reverse │ │ --- ┆ --- ┆ --- │ │ str ┆ u32 ┆ u32 │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ x ┆ 1 ┆ 3 │ │ k ┆ 2 ┆ 2 │ │ null ┆ 2 ┆ 1 │ │ d ┆ 3 ┆ 1 │ └──────┴───────────┴───────────────────┘ >>> my_library_agnostic_function(pa.table(data)) pyarrow.Table a: string cum_count: uint32 cum_count_reverse: uint32 ---- a: [["x","k",null,"d"]] cum_count: [[1,2,2,3]] cum_count_reverse: [[3,2,1,1]] cóF•—‰j|«j‰¬«SrÜ)rÚ cum_countrÞs €€rr,z Expr.cum_count..U s ø€˜×/Ñ/°Ó4×>Ñ>ÀwÐ>ÓO€rr-ràs``rr[zExpr.cum_count sù€ðt~‰~Ü Oó ð rcó0‡‡—‰jˆˆfd„«S)uh Return the cumulative min of the non-null values in the column. Arguments: reverse: reverse the operation Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [3, 1, None, 2]} We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("a").cum_min().alias("cum_min"), ... nw.col("a").cum_min(reverse=True).alias("cum_min_reverse"), ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.DataFrame(data)) a cum_min cum_min_reverse 0 3.0 3.0 1.0 1 1.0 1.0 1.0 2 NaN NaN NaN 3 2.0 1.0 2.0 >>> my_library_agnostic_function(pl.DataFrame(data)) shape: (4, 3) ┌──────┬─────────┬─────────────────┠│ a ┆ cum_min ┆ cum_min_reverse │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 3 ┆ 3 ┆ 1 │ │ 1 ┆ 1 ┆ 1 │ │ null ┆ null ┆ null │ │ 2 ┆ 1 ┆ 2 │ └──────┴─────────┴─────────────────┘ >>> my_library_agnostic_function(pa.table(data)) pyarrow.Table a: int64 cum_min: int64 cum_min_reverse: int64 ---- a: [[3,1,null,2]] cum_min: [[3,1,null,1]] cum_min_reverse: [[1,1,null,2]] cóF•—‰j|«j‰¬«SrÜ)rÚcum_minrÞs €€rr,zExpr.cum_min..“ rßrr-ràs``rr^z Expr.cum_minX óù€ðt~‰~Ü Mó ð rcó0‡‡—‰jˆˆfd„«S)uh Return the cumulative max of the non-null values in the column. Arguments: reverse: reverse the operation Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1, 3, None, 2]} We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("a").cum_max().alias("cum_max"), ... nw.col("a").cum_max(reverse=True).alias("cum_max_reverse"), ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.DataFrame(data)) a cum_max cum_max_reverse 0 1.0 1.0 3.0 1 3.0 3.0 3.0 2 NaN NaN NaN 3 2.0 3.0 2.0 >>> my_library_agnostic_function(pl.DataFrame(data)) shape: (4, 3) ┌──────┬─────────┬─────────────────┠│ a ┆ cum_max ┆ cum_max_reverse │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 1 ┆ 1 ┆ 3 │ │ 3 ┆ 3 ┆ 3 │ │ null ┆ null ┆ null │ │ 2 ┆ 3 ┆ 2 │ └──────┴─────────┴─────────────────┘ >>> my_library_agnostic_function(pa.table(data)) pyarrow.Table a: int64 cum_max: int64 cum_max_reverse: int64 ---- a: [[1,3,null,2]] cum_max: [[1,3,null,3]] cum_max_reverse: [[3,3,null,2]] cóF•—‰j|«j‰¬«SrÜ)rÚcum_maxrÞs €€rr,zExpr.cum_max..Ñ rßrr-ràs``rrbz Expr.cum_max– r_rcó0‡‡—‰jˆˆfd„«S)už Return the cumulative product of the non-null values in the column. Arguments: reverse: reverse the operation Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1, 3, None, 2]} We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("a").cum_prod().alias("cum_prod"), ... nw.col("a").cum_prod(reverse=True).alias("cum_prod_reverse"), ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.DataFrame(data)) a cum_prod cum_prod_reverse 0 1.0 1.0 6.0 1 3.0 3.0 6.0 2 NaN NaN NaN 3 2.0 6.0 2.0 >>> my_library_agnostic_function(pl.DataFrame(data)) shape: (4, 3) ┌──────┬──────────┬──────────────────┠│ a ┆ cum_prod ┆ cum_prod_reverse │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 1 ┆ 1 ┆ 6 │ │ 3 ┆ 3 ┆ 6 │ │ null ┆ null ┆ null │ │ 2 ┆ 6 ┆ 2 │ └──────┴──────────┴──────────────────┘ >>> my_library_agnostic_function(pa.table(data)) pyarrow.Table a: int64 cum_prod: int64 cum_prod_reverse: int64 ---- a: [[1,3,null,2]] cum_prod: [[1,3,null,6]] cum_prod_reverse: [[6,6,null,2]] cóF•—‰j|«j‰¬«SrÜ)rÚcum_prodrÞs €€rr,zExpr.cum_prod.. s ø€˜×/Ñ/°Ó4×=Ñ=ÀgÐ=ÓN€rr-ràs``rrez Expr.cum_prodÔ sù€ðt~‰~Ü Nó ð r)r¢ÚcentercóX‡‡‡‡—t‰‰¬«\ŠŠ‰jˆˆˆˆfd„«S)u¯ Apply a rolling sum (moving sum) over the values. !!! warning This functionality is considered **unstable**. It may be changed at any point without it being considered a breaking change. A window of length `window_size` will traverse the values. The resulting values will be aggregated to their sum. The window at a given row will include the row itself and the `window_size - 1` elements before it. Arguments: window_size: The length of the window in number of elements. It must be a strictly positive integer. min_periods: The number of values in the window that should be non-null before computing a result. If set to `None` (default), it will be set equal to `window_size`. If provided, it must be a strictly positive integer, and less than or equal to `window_size` center: Set the labels at the center of the window. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1.0, 2.0, None, 4.0]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_rolling_sum(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... b=nw.col("a").rolling_sum(window_size=3, min_periods=1) ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> agnostic_rolling_sum(df_pd) a b 0 1.0 1.0 1 2.0 3.0 2 NaN 3.0 3 4.0 6.0 >>> agnostic_rolling_sum(df_pl) shape: (4, 2) ┌──────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1.0 ┆ 1.0 │ │ 2.0 ┆ 3.0 │ │ null ┆ 3.0 │ │ 4.0 ┆ 6.0 │ └──────┴─────┘ >>> agnostic_rolling_sum(df_pa) # doctest:+ELLIPSIS pyarrow.Table a: double b: double ---- a: [[1,2,null,4]] b: [[1,3,3,6]] ©Ú window_sizer¢cóJ•—‰j|«j‰‰‰¬«S©N)rir¢rf)rÚ rolling_sum©r+rfr¢r#ris €€€€rr,z"Expr.rolling_sum..g s,ø€˜×/Ñ/°Ó4×@Ñ@Ø'Ø'ØðAó€r©rr.©r#rir¢rfs````rrlzExpr.rolling_sum ó2û€ô`$?Ø#°ô$ Ñ ˆ [ð~‰~ö ó ð rcóX‡‡‡‡—t‰‰¬«\ŠŠ‰jˆˆˆˆfd„«S)u» Apply a rolling mean (moving mean) over the values. !!! warning This functionality is considered **unstable**. It may be changed at any point without it being considered a breaking change. A window of length `window_size` will traverse the values. The resulting values will be aggregated to their mean. The window at a given row will include the row itself and the `window_size - 1` elements before it. Arguments: window_size: The length of the window in number of elements. It must be a strictly positive integer. min_periods: The number of values in the window that should be non-null before computing a result. If set to `None` (default), it will be set equal to `window_size`. If provided, it must be a strictly positive integer, and less than or equal to `window_size` center: Set the labels at the center of the window. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [1.0, 2.0, None, 4.0]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_rolling_mean(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... b=nw.col("a").rolling_mean(window_size=3, min_periods=1) ... ).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> agnostic_rolling_mean(df_pd) a b 0 1.0 1.0 1 2.0 1.5 2 NaN 1.5 3 4.0 3.0 >>> agnostic_rolling_mean(df_pl) shape: (4, 2) ┌──────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1.0 ┆ 1.0 │ │ 2.0 ┆ 1.5 │ │ null ┆ 1.5 │ │ 4.0 ┆ 3.0 │ └──────┴─────┘ >>> agnostic_rolling_mean(df_pa) # doctest:+ELLIPSIS pyarrow.Table a: double b: double ---- a: [[1,2,null,4]] b: [[1,1.5,1.5,3]] rhcóJ•—‰j|«j‰‰‰¬«Srk)rÚ rolling_meanrms €€€€rr,z#Expr.rolling_mean..à s,ø€˜×/Ñ/°Ó4×AÑAØ'Ø'ØðBó€rrnros````rrszExpr.rolling_meann rprcó—t|«Sr")ÚExprStringNamespacer/s rrzExpr.strÊ s €ä" 4Ó(Ð(rcó—t|«Sr")ÚExprDateTimeNamespacer/s rÚdtzExpr.dtÎ s €ä$ TÓ*Ð*rcó—t|«Sr")ÚExprCatNamespacer/s rÚcatzExpr.catÒ s €ä Ó%Ð%rcó—t|«Sr")ÚExprNameNamespacer/s rr4z Expr.nameÖ ó €ä  Ó&Ð&rcó—t|«Sr")ÚExprListNamespacer/s rrñz Expr.listÚ r~r)r$zCallable[[Any], Any]ÚreturnÚNone)rr)r4rrr)r7úCallable[[Any], Self]r8rr9rrr)r#rr>zDType | type[DType]rr)rÚobjectrr)rrrr)r#rrú float | Noneržr…rŸr…r r…r¡Úboolr¢Úintr£r†rr)r¯r‡rrr")r7rƒrµú DType | Nonerr)r#rrr©rr)rÒr†rr)r#rrÙr†rr)rèr‡rr)rïz!Sequence[Any] | Mapping[Any, Any]rîzSequence[Any] | NonerµzDType | type[DType] | Nonerr)rör†r÷r†rr)Úboth)rÿrrrrþrrr)r rrr)NNN)rú Any | Nonerz%Literal['forward', 'backward'] | Nonerú int | Nonerr) r#rrèrŒr r…r!r†r"rŒrr)róústr | Iterable[str]rr)r;Úfloatr<z;Literal['nearest', 'higher', 'lower', 'midpoint', 'linear']rr)é )r)rHr‡rr)r#rrèr‡rNr‡rr)NN)rÿr‹rr‹rr) r#rrir‡r¢rŒrfr†rr)r#rrzExprStringNamespace[Self])r#rrzExprDateTimeNamespace[Self])r#rrzExprCatNamespace[Self])r#rrzExprNameNamespace[Self])r#rrzExprListNamespace[Self])ZÚ__name__Ú __module__Ú __qualname__r%r0r3r:r=rArHrKrPrTrWrZr]r`rcrfrirmrprsrvryr|rr‚r…rˆr‹rŽr‘r•ršr¦r©r­r²r¶r¹r)r¾rÁrÄrÉrÌrÏrÕr(rÝrãrærírúrýrr rrrrr%r(r+r.r2r5r8r;r?rDrGrKrOrRrUrXr[r^rbrerlrsÚpropertyrrxr{r4rñr6rrrr#sÉ„ó4óTó 0Tód6/óp9 óx ó  ó  ó ó ó  ó ó ó ó ó ó ó ó ó ó  ó  ó  ó  ó ó ó ó ó óUó,Nó\,Nðb!Ø!Ø"&Ø"ØØØ"ñc Øðc ððc ðð c ð  ð c ð ð c ððc ððc ððc ð óc óJ,Oó\/Qðb"#õ1Wðl&*ðG à'ðG ð#ðG ð ó G óR+OóZ,Nó\,Nó\,Nó\.Ró`.Ró`,Pó\,Sð\05õ7 ór/Nðb05õ9 óv;Oóz>QðF%)ðU ð 48ñ U à .ðU ð"ðU ð 1ð U ð ó U ðn*/À5õU ðrAGð= Øð= Ø-0ð= Ø:=ð= à ó= ó~:+óx: óxFRóP-Sðb!Ø:>Ø ð P àðP ð8ðP ðð P ð ó P óf6UðtðB ð"&Ø!&Øñ B ØðB à ðB ðð B ð ð B ð ð B ð óB óH< ó|3Xój3Tój1Uóf5 ón3[ðjA àðA ðSðA ð ó A ôF2Pôh2Pôh;Xóz2Nôh4 ðt#'Ø"&ðC àðC ð ðC ð ó C óJ3Oój4Tðl27õ< ð|05õ< ð|05õ< ð|16õ< ðD#'Øñ Z ØðZ àðZ ð ð Z ð ð Z ð ó Z ð@#'Øñ Z ØðZ àðZ ð ð Z ð ð Z ð ó Z ðxò)óð)ðò+óð+ðò&óð&ðò'óð'ðò'óñ'rÚExprT)Úboundcó—eZdZdd„Zdd„Zy)rzcó—||_yr"©Ú_expr©r#rs rr%zExprCatNamespace.__init__ã ó €Øˆ rcó@‡—‰jjˆfd„«S)ufGet unique categories from column. Returns: A new expression. Examples: Let's create some dataframes: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"fruits": ["apple", "mango", "mango"]} >>> df_pd = pd.DataFrame(data, dtype="category") >>> df_pl = pl.DataFrame(data, schema={"fruits": pl.Categorical}) We define a dataframe-agnostic function to get unique categories from column 'fruits': >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("fruits").cat.get_categories()).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) fruits 0 apple 1 mango >>> my_library_agnostic_function(df_pl) shape: (2, 1) ┌────────┠│ fruits │ │ --- │ │ str │ â•žâ•â•â•â•â•â•â•â•â•¡ │ apple │ │ mango │ └────────┘ cój•—‰jj|«jj«Sr")r™rr{Úget_categoriesr*s €rr,z1ExprCatNamespace.get_categories..s%ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×MÑMÓO€r©r™r.r/s`rržzExprCatNamespace.get_categoriesæ s ø€ðRz‰z×#Ñ#Û Oó ð rN©r#rrr”rr‚©r#rrr”)rr‘r’r%ržr6rrrzrzâ s „óô+ rrzcó¾—eZdZdd„Zdd„Zdddœ dd„Zddœ dd„Zddd „Zdd „Zdd „Z ddœdd „Z ddd„Z ddd„Z ddd„Z dd d„Zdd„Zdd„Zy )!rucó—||_yr"r˜ršs rr%zExprStringNamespace.__init__r›rcó@‡—‰jjˆfd„«S)uÊReturn the length of each string as the number of characters. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"words": ["foo", "Café", "345", "æ±äº¬", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... words_len=nw.col("words").str.len_chars() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) words words_len 0 foo 3.0 1 Café 4.0 2 345 3.0 3 æ±äº¬ 2.0 4 None NaN >>> my_library_agnostic_function(df_pl) shape: (5, 2) ┌───────┬───────────┠│ words ┆ words_len │ │ --- ┆ --- │ │ str ┆ u32 │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ foo ┆ 3 │ │ Café ┆ 4 │ │ 345 ┆ 3 │ │ æ±äº¬ ┆ 2 │ │ null ┆ null │ └───────┴───────────┘ cój•—‰jj|«jj«Sr")r™rrÚ len_charsr*s €rr,z/ExprStringNamespace.len_chars..Hs%ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×HÑHÓJ€rrŸr/s`rr¦zExprStringNamespace.len_charss ø€ð^z‰z×#Ñ#Û Jó ð rFr›©ÚliteralrècóP‡‡‡‡‡—‰jjˆˆˆˆˆfd„«S)uReplace first matching regex/literal substring with a new string value. Arguments: pattern: A valid regular expression pattern. value: String that will replace the matched substring. literal: Treat `pattern` as a literal string. n: Number of matches to replace. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"foo": ["123abc", "abc abc123"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... df = df.with_columns(replaced=nw.col("foo").str.replace("abc", "")) ... return df.to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) foo replaced 0 123abc 123 1 abc abc123 abc123 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌────────────┬──────────┠│ foo ┆ replaced │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ 123abc ┆ 123 │ │ abc abc123 ┆ abc123 │ └────────────┴──────────┘ cót•—‰jj|«jj‰‰‰‰¬«S)Nr§)r™rrÚreplace)r+r¨rèÚpatternr#rs €€€€€rr,z-ExprStringNamespace.replace..|s6ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×FÑFؘ¨°1ðGó€rrŸ)r#r¬rr¨rès`````rr«zExprStringNamespace.replaceKs"ü€ð`z‰z×#Ñ#÷ ó ð r©r¨cóL‡‡‡‡—‰jjˆˆˆˆfd„«S)uèReplace all matching regex/literal substring with a new string value. Arguments: pattern: A valid regular expression pattern. value: String that will replace the matched substring. literal: Treat `pattern` as a literal string. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"foo": ["123abc", "abc abc123"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... df = df.with_columns(replaced=nw.col("foo").str.replace_all("abc", "")) ... return df.to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) foo replaced 0 123abc 123 1 abc abc123 123 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌────────────┬──────────┠│ foo ┆ replaced │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ 123abc ┆ 123 │ │ abc abc123 ┆ 123 │ └────────────┴──────────┘ cór•—‰jj|«jj‰‰‰¬«S©Nr­)r™rrÚ replace_all)r+r¨r¬r#rs €€€€rr,z1ExprStringNamespace.replace_all..±s4ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×JÑJؘ¨ðKó€rrŸ)r#r¬rr¨s````rr±zExprStringNamespace.replace_alls"û€ð^z‰z×#Ñ#ö ó ð rNcóD‡‡—‰jjˆˆfd„«S)agRemove leading and trailing characters. Arguments: characters: The set of characters to be removed. All combinations of this set of characters will be stripped from the start and end of the string. If set to None (default), all leading and trailing whitespace is removed instead. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> from typing import Any >>> data = {"fruits": ["apple", "\nmango"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrame) -> dict[str, Any]: ... df = nw.from_native(df_native) ... df = df.with_columns(stripped=nw.col("fruits").str.strip_chars()) ... return df.to_dict(as_series=False) We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) {'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']} >>> my_library_agnostic_function(df_pl) {'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']} cól•—‰jj|«jj‰«Sr")r™rrÚ strip_chars)r+Ú charactersr#s €€rr,z1ExprStringNamespace.strip_chars..Ùs'ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×JÑJÈ:ÓV€rrŸ)r#rµs``rr´zExprStringNamespace.strip_chars¶s ù€ðDz‰z×#Ñ#Ü Vó ð rcóD‡‡—‰jjˆˆfd„«S)u{Check if string values start with a substring. Arguments: prefix: prefix substring Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"fruits": ["apple", "mango", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... has_prefix=nw.col("fruits").str.starts_with("app") ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) fruits has_prefix 0 apple True 1 mango False 2 None None >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌────────┬────────────┠│ fruits ┆ has_prefix │ │ --- ┆ --- │ │ str ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ apple ┆ true │ │ mango ┆ false │ │ null ┆ null │ └────────┴────────────┘ cól•—‰jj|«jj‰«Sr")r™rrÚ starts_with©r+Úprefixr#s €€rr,z1ExprStringNamespace.starts_with.. s'ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×JÑJÈ6ÓR€rrŸ©r#rºs``rr¸zExprStringNamespace.starts_withÜs ù€ð\z‰z×#Ñ#Ü Ró ð rcóD‡‡—‰jjˆˆfd„«S)uwCheck if string values end with a substring. Arguments: suffix: suffix substring Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"fruits": ["apple", "mango", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... has_suffix=nw.col("fruits").str.ends_with("ngo") ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) fruits has_suffix 0 apple False 1 mango True 2 None None >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌────────┬────────────┠│ fruits ┆ has_suffix │ │ --- ┆ --- │ │ str ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ apple ┆ false │ │ mango ┆ true │ │ null ┆ null │ └────────┴────────────┘ cól•—‰jj|«jj‰«Sr")r™rrÚ ends_with©r+r#Úsuffixs €€rr,z/ExprStringNamespace.ends_with..=s'ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×HÑHÈÓP€rrŸ©r#rÀs``rr¾zExprStringNamespace.ends_withs ù€ð\z‰z×#Ñ#Ü Pó ð rcóH‡‡‡—‰jjˆˆˆfd„«S)uê Check if string contains a substring that matches a pattern. Arguments: pattern: A Character sequence or valid regular expression pattern. literal: If True, treats the pattern as a literal string. If False, assumes the pattern is a regular expression. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"pets": ["cat", "dog", "rabbit and parrot", "dove", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... default_match=nw.col("pets").str.contains("parrot|Dove"), ... case_insensitive_match=nw.col("pets").str.contains("(?i)parrot|Dove"), ... literal_match=nw.col("pets").str.contains( ... "parrot|Dove", literal=True ... ), ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) pets default_match case_insensitive_match literal_match 0 cat False False False 1 dog False False False 2 rabbit and parrot True True False 3 dove False True False 4 None None None None >>> my_library_agnostic_function(df_pl) shape: (5, 4) ┌───────────────────┬───────────────┬────────────────────────┬───────────────┠│ pets ┆ default_match ┆ case_insensitive_match ┆ literal_match │ │ --- ┆ --- ┆ --- ┆ --- │ │ str ┆ bool ┆ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ cat ┆ false ┆ false ┆ false │ │ dog ┆ false ┆ false ┆ false │ │ rabbit and parrot ┆ true ┆ true ┆ false │ │ dove ┆ false ┆ true ┆ false │ │ null ┆ null ┆ null ┆ null │ └───────────────────┴───────────────┴────────────────────────┴───────────────┘ cóp•—‰jj|«jj‰‰¬«Sr°)r™rrÚcontains)r+r¨r¬r#s €€€rr,z.ExprStringNamespace.contains..xs2ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×GÑGØ ðHó€rrŸ)r#r¬r¨s```rrÄzExprStringNamespace.contains@s"ú€ðnz‰z×#Ñ#õ ó ð rcóH‡‡‡—‰jjˆˆˆfd„«S)u[ Create subslices of the string values of an expression. Arguments: offset: Start index. Negative indexing is supported. length: Length of the slice. If set to `None` (default), the slice is taken to the end of the string. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"s": ["pear", None, "papaya", "dragonfruit"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... s_sliced=nw.col("s").str.slice(4, length=3) ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) # doctest: +NORMALIZE_WHITESPACE s s_sliced 0 pear 1 None None 2 papaya ya 3 dragonfruit onf >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌─────────────┬──────────┠│ s ┆ s_sliced │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ pear ┆ │ │ null ┆ null │ │ papaya ┆ ya │ │ dragonfruit ┆ onf │ └─────────────┴──────────┘ Using negative indexes: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns(s_sliced=nw.col("s").str.slice(-3)).to_native() >>> my_library_agnostic_function(df_pd) s s_sliced 0 pear ear 1 None None 2 papaya aya 3 dragonfruit uit >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌─────────────┬──────────┠│ s ┆ s_sliced │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ pear ┆ ear │ │ null ┆ null │ │ papaya ┆ aya │ │ dragonfruit ┆ uit │ └─────────────┴──────────┘ cóp•—‰jj|«jj‰‰¬«S©N)rNÚlength©r™rrÚslice)r+rÈrNr#s €€€rr,z+ExprStringNamespace.slice..Ês2ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×DÑDØ fðEó€rrŸ)r#rNrÈs```rrÊzExprStringNamespace.slice}s"ú€ðXz‰z×#Ñ#õ ó ð rcóD‡‡—‰jjˆˆfd„«S)uÄTake the first n elements of each string. Arguments: n: Number of elements to take. Negative indexing is **not** supported. Returns: A new expression. Notes: If the length of the string has fewer than `n` characters, the full string is returned. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"lyrics": ["Atatata", "taata", "taatatata", "zukkyun"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... lyrics_head=nw.col("lyrics").str.head() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) lyrics lyrics_head 0 Atatata Atata 1 taata taata 2 taatatata taata 3 zukkyun zukky >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌───────────┬─────────────┠│ lyrics ┆ lyrics_head │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ Atatata ┆ Atata │ │ taata ┆ taata │ │ taatatata ┆ taata │ │ zukkyun ┆ zukky │ └───────────┴─────────────┘ cón•—‰jj|«jjd‰«S)NrrÉrçs €€rr,z*ExprStringNamespace.head..s)ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×DÑDÀQÈÓJ€rrŸrés``rr?zExprStringNamespace.headÏs ù€ðfz‰z×#Ñ#Ü Jó ð rcóD‡‡—‰jjˆˆfd„«S)uÃTake the last n elements of each string. Arguments: n: Number of elements to take. Negative indexing is **not** supported. Returns: A new expression. Notes: If the length of the string has fewer than `n` characters, the full string is returned. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"lyrics": ["Atatata", "taata", "taatatata", "zukkyun"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... lyrics_tail=nw.col("lyrics").str.tail() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) lyrics lyrics_tail 0 Atatata atata 1 taata taata 2 taatatata atata 3 zukkyun kkyun >>> my_library_agnostic_function(df_pl) shape: (4, 2) ┌───────────┬─────────────┠│ lyrics ┆ lyrics_tail │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ Atatata ┆ atata │ │ taata ┆ taata │ │ taatatata ┆ atata │ │ zukkyun ┆ kkyun │ └───────────┴─────────────┘ cór•—‰jj|«jj‰ d¬«SrÇrÉrçs €€rr,z*ExprStringNamespace.tail..:s4ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×DÑDØr $ðEó€rrŸrés``rrDzExprStringNamespace.tails"ù€ðfz‰z×#Ñ#ô ó ð rcóD‡‡—‰jjˆˆfd„«S)uv Convert to Datetime dtype. Warning: As different backends auto-infer format in different ways, if `format=None` there is no guarantee that the result will be equal. Arguments: format: Format to use for conversion. If set to None (default), the format is inferred from the data. Returns: A new expression. Notes: pandas defaults to nanosecond time unit, Polars to microsecond. Prior to pandas 2.0, nanoseconds were the only time unit supported in pandas, with no ability to set any other one. The ability to set the time unit in pandas, if the version permits, will arrive. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = ["2020-01-01", "2020-01-02"] >>> df_pd = pd.DataFrame({"a": data}) >>> df_pl = pl.DataFrame({"a": data}) >>> df_pa = pa.table({"a": data}) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a").str.to_datetime(format="%Y-%m-%d") ... ).to_native() We can then pass any supported library such as pandas, Polars, or PyArrow: >>> my_library_agnostic_function(df_pd) a 0 2020-01-01 1 2020-01-02 >>> my_library_agnostic_function(df_pl) shape: (2, 1) ┌─────────────────────┠│ a │ │ --- │ │ datetime[μs] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2020-01-01 00:00:00 │ │ 2020-01-02 00:00:00 │ └─────────────────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: timestamp[us] ---- a: [[2020-01-01 00:00:00.000000,2020-01-02 00:00:00.000000]] cón•—‰jj|«jj‰¬«S)N)Úformat)r™rrÚ to_datetime©r+rÑr#s €€rr,z1ExprStringNamespace.to_datetime..}s+ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×JÑJÐRXÐJÓY€rrŸ©r#rÑs``rrÒzExprStringNamespace.to_datetime?s ù€ðzz‰z×#Ñ#Ü Yó ð rcó@‡—‰jjˆfd„«S)u<Transform string to uppercase variant. Returns: A new expression. Notes: The PyArrow backend will convert 'ß' to 'ẞ' instead of 'SS'. For more info see [the related issue](https://github.com/apache/arrow/issues/34599). There may be other unicode-edge-case-related variations across implementations. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"fruits": ["apple", "mango", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... upper_col=nw.col("fruits").str.to_uppercase() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) fruits upper_col 0 apple APPLE 1 mango MANGO 2 None None >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌────────┬───────────┠│ fruits ┆ upper_col │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ apple ┆ APPLE │ │ mango ┆ MANGO │ │ null ┆ null │ └────────┴───────────┘ cój•—‰jj|«jj«Sr")r™rrÚ to_uppercaser*s €rr,z2ExprStringNamespace.to_uppercase..²ó%ø€˜Ÿ ™ ×5Ñ5°cÓ:×>Ñ>×KÑKÓM€rrŸr/s`rr×z ExprStringNamespace.to_uppercase€s ø€ðbz‰z×#Ñ#Û Mó ð rcó@‡—‰jjˆfd„«S)u"Transform string to lowercase variant. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"fruits": ["APPLE", "MANGO", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... lower_col=nw.col("fruits").str.to_lowercase() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) fruits lower_col 0 APPLE apple 1 MANGO mango 2 None None >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌────────┬───────────┠│ fruits ┆ lower_col │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ APPLE ┆ apple │ │ MANGO ┆ mango │ │ null ┆ null │ └────────┴───────────┘ cój•—‰jj|«jj«Sr")r™rrÚ to_lowercaser*s €rr,z2ExprStringNamespace.to_lowercase..árØrrŸr/s`rrÛz ExprStringNamespace.to_lowercaseµs ø€ðVz‰z×#Ñ#Û Mó ð rr r¡) r¬rrrr¨r†rèr‡rr”) r#rr¬rrrr¨r†rr”r")r#rrµú str | Nonerr”©r#rrºrrr”©r#rrÀrrr”)r#rr¬rr¨r†rr”)r#rrNr‡rÈrŒrr”)é)r#rrèr‡rr”)r#rrÑrÜrr”)rr‘r’r%r¦r«r±r´r¸r¾rÄrÊr?rDrÒr×rÛr6rrrurusº„óó1 ðhð3 à ó3 ôj$ óL0 ód0 ðd?Dõ; ôzP ôd5 ôn7 ôr? óB3 ôj- rrucó¶—eZdZdd„Zdd„Zdd„Zdd„Zdd„Zdd„Zdd„Z dd„Z dd „Z dd „Z dd „Z dd „Zdd „Zdd„Zdd„Zdd„Zdd„Zdd„Zdd„Zdd„Zddd„Zy)rwcó—||_yr"r˜ršs rr%zExprDateTimeNamespace.__init__ær›rcó@‡—‰jjˆfd„«S)uòExtract the date from underlying DateTime representation. Returns: A new expression. Raises: NotImplementedError: If pandas default backend is being used. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [datetime(2012, 1, 7, 10, 20), datetime(2023, 3, 10, 11, 32)]} >>> df_pd = pd.DataFrame(data).convert_dtypes(dtype_backend="pyarrow") >>> df_pl = pl.DataFrame(data) We define a library agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a").dt.date()).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a 0 2012-01-07 1 2023-03-10 >>> my_library_agnostic_function(df_pl) # docetst shape: (2, 1) ┌────────────┠│ a │ │ --- │ │ date │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2012-01-07 │ │ 2023-03-10 │ └────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚdater*s €rr,z,ExprDateTimeNamespace.date..ó%ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×BÑBÓD€rrŸr/s`rräzExprDateTimeNamespace.dateés ø€ðVz‰z×#Ñ#Û Dó ð rcó@‡—‰jjˆfd„«S)u¾Extract year from underlying DateTime representation. Returns the year number in the calendar date. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "datetime": [ ... datetime(1978, 6, 1), ... datetime(2024, 12, 13), ... datetime(2065, 1, 1), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("datetime").dt.year().alias("year") ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) datetime year 0 1978-06-01 1978 1 2024-12-13 2024 2 2065-01-01 2065 >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌─────────────────────┬──────┠│ datetime ┆ year │ │ --- ┆ --- │ │ datetime[μs] ┆ i32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ 1978-06-01 00:00:00 ┆ 1978 │ │ 2024-12-13 00:00:00 ┆ 2024 │ │ 2065-01-01 00:00:00 ┆ 2065 │ └─────────────────────┴──────┘ cój•—‰jj|«jj«Sr")r™rrxÚyearr*s €rr,z,ExprDateTimeNamespace.year..LrårrŸr/s`rrèzExprDateTimeNamespace.yearó ø€ðfz‰z×#Ñ#Û Dó ð rcó@‡—‰jjˆfd„«S)uÈExtract month from underlying DateTime representation. Returns the month number starting from 1. The return value ranges from 1 to 12. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "datetime": [ ... datetime(1978, 6, 1), ... datetime(2024, 12, 13), ... datetime(2065, 1, 1), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("datetime").dt.year().alias("year"), ... nw.col("datetime").dt.month().alias("month"), ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) datetime year month 0 1978-06-01 1978 6 1 2024-12-13 2024 12 2 2065-01-01 2065 1 >>> my_library_agnostic_function(df_pl) shape: (3, 3) ┌─────────────────────┬──────┬───────┠│ datetime ┆ year ┆ month │ │ --- ┆ --- ┆ --- │ │ datetime[μs] ┆ i32 ┆ i8 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ 1978-06-01 00:00:00 ┆ 1978 ┆ 6 │ │ 2024-12-13 00:00:00 ┆ 2024 ┆ 12 │ │ 2065-01-01 00:00:00 ┆ 2065 ┆ 1 │ └─────────────────────┴──────┴───────┘ cój•—‰jj|«jj«Sr")r™rrxÚmonthr*s €rr,z-ExprDateTimeNamespace.month..„s%ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×CÑCÓE€rrŸr/s`rrìzExprDateTimeNamespace.monthOs ø€ðhz‰z×#Ñ#Û Eó ð rcó@‡—‰jjˆfd„«S)u­ Extract day from underlying DateTime representation. Returns the day of month starting from 1. The return value ranges from 1 to 31. (The last day of month differs by months.) Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "datetime": [ ... datetime(1978, 6, 1), ... datetime(2024, 12, 13), ... datetime(2065, 1, 1), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("datetime").dt.year().alias("year"), ... nw.col("datetime").dt.month().alias("month"), ... nw.col("datetime").dt.day().alias("day"), ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) datetime year month day 0 1978-06-01 1978 6 1 1 2024-12-13 2024 12 13 2 2065-01-01 2065 1 1 >>> my_library_agnostic_function(df_pl) shape: (3, 4) ┌─────────────────────┬──────┬───────┬─────┠│ datetime ┆ year ┆ month ┆ day │ │ --- ┆ --- ┆ --- ┆ --- │ │ datetime[μs] ┆ i32 ┆ i8 ┆ i8 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1978-06-01 00:00:00 ┆ 1978 ┆ 6 ┆ 1 │ │ 2024-12-13 00:00:00 ┆ 2024 ┆ 12 ┆ 13 │ │ 2065-01-01 00:00:00 ┆ 2065 ┆ 1 ┆ 1 │ └─────────────────────┴──────┴───────┴─────┘ cój•—‰jj|«jj«Sr")r™rrxÚdayr*s €rr,z+ExprDateTimeNamespace.day..½s%ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×AÑAÓC€rrŸr/s`rrïzExprDateTimeNamespace.day‡s ø€ðjz‰z×#Ñ#Û Có ð rcó@‡—‰jjˆfd„«S)uäExtract hour from underlying DateTime representation. Returns the hour number from 0 to 23. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "datetime": [ ... datetime(1978, 1, 1, 1), ... datetime(2024, 10, 13, 5), ... datetime(2065, 1, 1, 10), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("datetime").dt.hour().alias("hour") ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) datetime hour 0 1978-01-01 01:00:00 1 1 2024-10-13 05:00:00 5 2 2065-01-01 10:00:00 10 >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌─────────────────────┬──────┠│ datetime ┆ hour │ │ --- ┆ --- │ │ datetime[μs] ┆ i8 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ 1978-01-01 01:00:00 ┆ 1 │ │ 2024-10-13 05:00:00 ┆ 5 │ │ 2065-01-01 10:00:00 ┆ 10 │ └─────────────────────┴──────┘ cój•—‰jj|«jj«Sr")r™rrxÚhourr*s €rr,z,ExprDateTimeNamespace.hour..ôrårrŸr/s`rròzExprDateTimeNamespace.hourÀrércó@‡—‰jjˆfd„«S)uðExtract minutes from underlying DateTime representation. Returns the minute number from 0 to 59. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "datetime": [ ... datetime(1978, 1, 1, 1, 1), ... datetime(2024, 10, 13, 5, 30), ... datetime(2065, 1, 1, 10, 20), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("datetime").dt.hour().alias("hour"), ... nw.col("datetime").dt.minute().alias("minute"), ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) datetime hour minute 0 1978-01-01 01:01:00 1 1 1 2024-10-13 05:30:00 5 30 2 2065-01-01 10:20:00 10 20 >>> my_library_agnostic_function(df_pl) shape: (3, 3) ┌─────────────────────┬──────┬────────┠│ datetime ┆ hour ┆ minute │ │ --- ┆ --- ┆ --- │ │ datetime[μs] ┆ i8 ┆ i8 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•¡ │ 1978-01-01 01:01:00 ┆ 1 ┆ 1 │ │ 2024-10-13 05:30:00 ┆ 5 ┆ 30 │ │ 2065-01-01 10:20:00 ┆ 10 ┆ 20 │ └─────────────────────┴──────┴────────┘ cój•—‰jj|«jj«Sr")r™rrxÚminuter*s €rr,z.ExprDateTimeNamespace.minute..,ó%ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×DÑDÓF€rrŸr/s`rrõzExprDateTimeNamespace.minute÷s ø€ðhz‰z×#Ñ#Û Fó ð rcó@‡—‰jjˆfd„«S)uÅ Extract seconds from underlying DateTime representation. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "datetime": [ ... datetime(1978, 1, 1, 1, 1, 1), ... datetime(2024, 10, 13, 5, 30, 14), ... datetime(2065, 1, 1, 10, 20, 30), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("datetime").dt.hour().alias("hour"), ... nw.col("datetime").dt.minute().alias("minute"), ... nw.col("datetime").dt.second().alias("second"), ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) datetime hour minute second 0 1978-01-01 01:01:01 1 1 1 1 2024-10-13 05:30:14 5 30 14 2 2065-01-01 10:20:30 10 20 30 >>> my_library_agnostic_function(df_pl) shape: (3, 4) ┌─────────────────────┬──────┬────────┬────────┠│ datetime ┆ hour ┆ minute ┆ second │ │ --- ┆ --- ┆ --- ┆ --- │ │ datetime[μs] ┆ i8 ┆ i8 ┆ i8 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•¡ │ 1978-01-01 01:01:01 ┆ 1 ┆ 1 ┆ 1 │ │ 2024-10-13 05:30:14 ┆ 5 ┆ 30 ┆ 14 │ │ 2065-01-01 10:20:30 ┆ 10 ┆ 20 ┆ 30 │ └─────────────────────┴──────┴────────┴────────┘ cój•—‰jj|«jj«Sr")r™rrxÚsecondr*s €rr,z.ExprDateTimeNamespace.second..crörrŸr/s`rrùzExprDateTimeNamespace.second/s ø€ðfz‰z×#Ñ#Û Fó ð rcó@‡—‰jjˆfd„«S)uŒ Extract milliseconds from underlying DateTime representation. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "datetime": [ ... datetime(1978, 1, 1, 1, 1, 1, 0), ... datetime(2024, 10, 13, 5, 30, 14, 505000), ... datetime(2065, 1, 1, 10, 20, 30, 67000), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("datetime").dt.hour().alias("hour"), ... nw.col("datetime").dt.minute().alias("minute"), ... nw.col("datetime").dt.second().alias("second"), ... nw.col("datetime").dt.millisecond().alias("millisecond"), ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) datetime hour minute second millisecond 0 1978-01-01 01:01:01.000 1 1 1 0 1 2024-10-13 05:30:14.505 5 30 14 505 2 2065-01-01 10:20:30.067 10 20 30 67 >>> my_library_agnostic_function(df_pl) shape: (3, 5) ┌─────────────────────────┬──────┬────────┬────────┬─────────────┠│ datetime ┆ hour ┆ minute ┆ second ┆ millisecond │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ datetime[μs] ┆ i8 ┆ i8 ┆ i8 ┆ i32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 1978-01-01 01:01:01 ┆ 1 ┆ 1 ┆ 1 ┆ 0 │ │ 2024-10-13 05:30:14.505 ┆ 5 ┆ 30 ┆ 14 ┆ 505 │ │ 2065-01-01 10:20:30.067 ┆ 10 ┆ 20 ┆ 30 ┆ 67 │ └─────────────────────────┴──────┴────────┴────────┴─────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚ millisecondr*s €rr,z3ExprDateTimeNamespace.millisecond..›ó%ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×IÑIÓK€rrŸr/s`rrüz!ExprDateTimeNamespace.millisecondfó ø€ðhz‰z×#Ñ#Û Kó ð rcó@‡—‰jjˆfd„«S)uŒ Extract microseconds from underlying DateTime representation. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "datetime": [ ... datetime(1978, 1, 1, 1, 1, 1, 0), ... datetime(2024, 10, 13, 5, 30, 14, 505000), ... datetime(2065, 1, 1, 10, 20, 30, 67000), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("datetime").dt.hour().alias("hour"), ... nw.col("datetime").dt.minute().alias("minute"), ... nw.col("datetime").dt.second().alias("second"), ... nw.col("datetime").dt.microsecond().alias("microsecond"), ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) datetime hour minute second microsecond 0 1978-01-01 01:01:01.000 1 1 1 0 1 2024-10-13 05:30:14.505 5 30 14 505000 2 2065-01-01 10:20:30.067 10 20 30 67000 >>> my_library_agnostic_function(df_pl) shape: (3, 5) ┌─────────────────────────┬──────┬────────┬────────┬─────────────┠│ datetime ┆ hour ┆ minute ┆ second ┆ microsecond │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ datetime[μs] ┆ i8 ┆ i8 ┆ i8 ┆ i32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 1978-01-01 01:01:01 ┆ 1 ┆ 1 ┆ 1 ┆ 0 │ │ 2024-10-13 05:30:14.505 ┆ 5 ┆ 30 ┆ 14 ┆ 505000 │ │ 2065-01-01 10:20:30.067 ┆ 10 ┆ 20 ┆ 30 ┆ 67000 │ └─────────────────────────┴──────┴────────┴────────┴─────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚ microsecondr*s €rr,z3ExprDateTimeNamespace.microsecond..ÓrýrrŸr/s`rrz!ExprDateTimeNamespace.microsecondžrþrcó@‡—‰jjˆfd„«S)uv Extract Nanoseconds from underlying DateTime representation. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "datetime": [ ... datetime(1978, 1, 1, 1, 1, 1, 0), ... datetime(2024, 10, 13, 5, 30, 14, 500000), ... datetime(2065, 1, 1, 10, 20, 30, 60000), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("datetime").dt.hour().alias("hour"), ... nw.col("datetime").dt.minute().alias("minute"), ... nw.col("datetime").dt.second().alias("second"), ... nw.col("datetime").dt.nanosecond().alias("nanosecond"), ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) datetime hour minute second nanosecond 0 1978-01-01 01:01:01.000 1 1 1 0 1 2024-10-13 05:30:14.500 5 30 14 500000000 2 2065-01-01 10:20:30.060 10 20 30 60000000 >>> my_library_agnostic_function(df_pl) shape: (3, 5) ┌─────────────────────────┬──────┬────────┬────────┬────────────┠│ datetime ┆ hour ┆ minute ┆ second ┆ nanosecond │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ datetime[μs] ┆ i8 ┆ i8 ┆ i8 ┆ i32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 1978-01-01 01:01:01 ┆ 1 ┆ 1 ┆ 1 ┆ 0 │ │ 2024-10-13 05:30:14.500 ┆ 5 ┆ 30 ┆ 14 ┆ 500000000 │ │ 2065-01-01 10:20:30.060 ┆ 10 ┆ 20 ┆ 30 ┆ 60000000 │ └─────────────────────────┴──────┴────────┴────────┴────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚ nanosecondr*s €rr,z2ExprDateTimeNamespace.nanosecond.. s%ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×HÑHÓJ€rrŸr/s`rrz ExprDateTimeNamespace.nanosecondÖs ø€ðhz‰z×#Ñ#Û Jó ð rcó@‡—‰jjˆfd„«S)uGet ordinal day. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [datetime(2020, 1, 1), datetime(2020, 8, 3)]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... a_ordinal_day=nw.col("a").dt.ordinal_day() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a a_ordinal_day 0 2020-01-01 1 1 2020-08-03 216 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌─────────────────────┬───────────────┠│ a ┆ a_ordinal_day │ │ --- ┆ --- │ │ datetime[μs] ┆ i16 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2020-01-01 00:00:00 ┆ 1 │ │ 2020-08-03 00:00:00 ┆ 216 │ └─────────────────────┴───────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚ ordinal_dayr*s €rr,z3ExprDateTimeNamespace.ordinal_day..8rýrrŸr/s`rrz!ExprDateTimeNamespace.ordinal_days ø€ðRz‰z×#Ñ#Û Kó ð rcó@‡—‰jjˆfd„«S)uæGet total minutes. Returns: A new expression. Notes: The function outputs the total minutes in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using `fill_null()` and `cast` in this case. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [timedelta(minutes=10), timedelta(minutes=20, seconds=40)]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... a_total_minutes=nw.col("a").dt.total_minutes() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a a_total_minutes 0 0 days 00:10:00 10 1 0 days 00:20:40 20 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌──────────────┬─────────────────┠│ a ┆ a_total_minutes │ │ --- ┆ --- │ │ duration[μs] ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 10m ┆ 10 │ │ 20m 40s ┆ 20 │ └──────────────┴─────────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚ total_minutesr*s €rr,z5ExprDateTimeNamespace.total_minutes..jó%ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×KÑKÓM€rrŸr/s`rr z#ExprDateTimeNamespace.total_minutes;ó ø€ð\z‰z×#Ñ#Û Mó ð rcó@‡—‰jjˆfd„«S)uGet total seconds. Returns: A new expression. Notes: The function outputs the total seconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using `fill_null()` and `cast` in this case. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [timedelta(seconds=10), timedelta(seconds=20, milliseconds=40)]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... a_total_seconds=nw.col("a").dt.total_seconds() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a a_total_seconds 0 0 days 00:00:10 10 1 0 days 00:00:20.040000 20 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌──────────────┬─────────────────┠│ a ┆ a_total_seconds │ │ --- ┆ --- │ │ duration[μs] ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 10s ┆ 10 │ │ 20s 40ms ┆ 20 │ └──────────────┴─────────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚ total_secondsr*s €rr,z5ExprDateTimeNamespace.total_seconds..œr rrŸr/s`rrz#ExprDateTimeNamespace.total_secondsmr rcó@‡—‰jjˆfd„«S)uáGet total milliseconds. Returns: A new expression. Notes: The function outputs the total milliseconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using `fill_null()` and `cast` in this case. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": [ ... timedelta(milliseconds=10), ... timedelta(milliseconds=20, microseconds=40), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... a_total_milliseconds=nw.col("a").dt.total_milliseconds() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a a_total_milliseconds 0 0 days 00:00:00.010000 10 1 0 days 00:00:00.020040 20 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌──────────────┬──────────────────────┠│ a ┆ a_total_milliseconds │ │ --- ┆ --- │ │ duration[μs] ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 10ms ┆ 10 │ │ 20040µs ┆ 20 │ └──────────────┴──────────────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚtotal_millisecondsr*s €rr,z:ExprDateTimeNamespace.total_milliseconds..Óó%ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×PÑPÓR€rrŸr/s`rrz(ExprDateTimeNamespace.total_millisecondsŸó ø€ðfz‰z×#Ñ#Û Ró ð rcó@‡—‰jjˆfd„«S)uâGet total microseconds. Returns: A new expression. Notes: The function outputs the total microseconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using `fill_null()` and `cast` in this case. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": [ ... timedelta(microseconds=10), ... timedelta(milliseconds=1, microseconds=200), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... a_total_microseconds=nw.col("a").dt.total_microseconds() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a a_total_microseconds 0 0 days 00:00:00.000010 10 1 0 days 00:00:00.001200 1200 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌──────────────┬──────────────────────┠│ a ┆ a_total_microseconds │ │ --- ┆ --- │ │ duration[μs] ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 10µs ┆ 10 │ │ 1200µs ┆ 1200 │ └──────────────┴──────────────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚtotal_microsecondsr*s €rr,z:ExprDateTimeNamespace.total_microseconds.. rrrŸr/s`rrz(ExprDateTimeNamespace.total_microsecondsÖrrcó@‡—‰jjˆfd„«S)u1 Get total nanoseconds. Returns: A new expression. Notes: The function outputs the total nanoseconds in the int dtype by default, however, pandas may change the dtype to float when there are missing values, consider using `fill_null()` and `cast` in this case. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import timedelta >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = ["2024-01-01 00:00:00.000000001", "2024-01-01 00:00:00.000000002"] >>> df_pd = pd.DataFrame({"a": pd.to_datetime(data)}) >>> df_pl = pl.DataFrame({"a": data}).with_columns( ... pl.col("a").str.to_datetime(time_unit="ns") ... ) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... a_diff_total_nanoseconds=nw.col("a").diff().dt.total_nanoseconds() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a a_diff_total_nanoseconds 0 2024-01-01 00:00:00.000000001 NaN 1 2024-01-01 00:00:00.000000002 1.0 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌───────────────────────────────┬──────────────────────────┠│ a ┆ a_diff_total_nanoseconds │ │ --- ┆ --- │ │ datetime[ns] ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2024-01-01 00:00:00.000000001 ┆ null │ │ 2024-01-01 00:00:00.000000002 ┆ 1 │ └───────────────────────────────┴──────────────────────────┘ cój•—‰jj|«jj«Sr")r™rrxÚtotal_nanosecondsr*s €rr,z9ExprDateTimeNamespace.total_nanoseconds..>s%ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×OÑOÓQ€rrŸr/s`rrz'ExprDateTimeNamespace.total_nanoseconds s ø€ð`z‰z×#Ñ#Û Qó ð rcóD‡‡—‰jjˆˆfd„«S)uÌ Convert a Date/Time/Datetime column into a String column with the given format. Arguments: format: Format to format temporal column with. Returns: A new expression. Notes: Unfortunately, different libraries interpret format directives a bit differently. - Chrono, the library used by Polars, uses `"%.f"` for fractional seconds, whereas pandas and Python stdlib use `".%f"`. - PyArrow interprets `"%S"` as "seconds, including fractional seconds" whereas most other tools interpret it as "just seconds, as 2 digits". Therefore, we make the following adjustments: - for pandas-like libraries, we replace `"%S.%f"` with `"%S%.f"`. - for PyArrow, we replace `"%S.%f"` with `"%S"`. Workarounds like these don't make us happy, and we try to avoid them as much as possible, but here we feel like it's the best compromise. If you just want to format a date/datetime Series as a local datetime string, and have it work as consistently as possible across libraries, we suggest using: - `"%Y-%m-%dT%H:%M:%S%.f"` for datetimes - `"%Y-%m-%d"` for dates though note that, even then, different tools may return a different number of trailing zeros. Nonetheless, this is probably consistent enough for most applications. If you have an application where this is not enough, please open an issue and let us know. Examples: >>> from datetime import datetime >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = [ ... datetime(2020, 3, 1), ... datetime(2020, 4, 1), ... datetime(2020, 5, 1), ... ] >>> df_pd = pd.DataFrame({"a": data}) >>> df_pl = pl.DataFrame({"a": data}) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a").dt.to_string("%Y/%m/%d %H:%M:%S") ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd) a 0 2020/03/01 00:00:00 1 2020/04/01 00:00:00 2 2020/05/01 00:00:00 >>> my_library_agnostic_function(df_pl) shape: (3, 1) ┌─────────────────────┠│ a │ │ --- │ │ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2020/03/01 00:00:00 │ │ 2020/04/01 00:00:00 │ │ 2020/05/01 00:00:00 │ └─────────────────────┘ cól•—‰jj|«jj‰«Sr")r™rrxÚ to_stringrÓs €€rr,z1ExprDateTimeNamespace.to_string..”s'ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×GÑGÈÓO€rrŸrÔs``rrzExprDateTimeNamespace.to_stringAs ù€ðdz‰z×#Ñ#Ü Oó ð rcóD‡‡—‰jjˆˆfd„«S)u¼Replace time zone. Arguments: time_zone: Target time zone. Returns: A new expression. Examples: >>> from datetime import datetime, timezone >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = { ... "a": [ ... datetime(2024, 1, 1, tzinfo=timezone.utc), ... datetime(2024, 1, 2, tzinfo=timezone.utc), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a").dt.replace_time_zone("Asia/Kathmandu") ... ).to_native() We can then pass pandas / PyArrow / Polars / any other supported library: >>> my_library_agnostic_function(df_pd) a 0 2024-01-01 00:00:00+05:45 1 2024-01-02 00:00:00+05:45 >>> my_library_agnostic_function(df_pl) shape: (2, 1) ┌──────────────────────────────┠│ a │ │ --- │ │ datetime[μs, Asia/Kathmandu] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2024-01-01 00:00:00 +0545 │ │ 2024-01-02 00:00:00 +0545 │ └──────────────────────────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: timestamp[us, tz=Asia/Kathmandu] ---- a: [[2023-12-31 18:15:00.000000Z,2024-01-01 18:15:00.000000Z]] cól•—‰jj|«jj‰«Sr")r™rrxÚreplace_time_zone©r+r#Ú time_zones €€rr,z9ExprDateTimeNamespace.replace_time_zone..Ðó(ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×OÑOÐPYÓZ€rrŸ)r#r"s``rr z'ExprDateTimeNamespace.replace_time_zone—s ù€ðpz‰z×#Ñ#Ü Zó ð rcób‡‡—‰€ d}t|«‚‰jjˆˆfd„«S)u6 Convert to a new time zone. If converting from a time-zone-naive column, then conversion happens as if converting from UTC. Arguments: time_zone: Target time zone. Returns: A new expression. Examples: >>> from datetime import datetime, timezone >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = { ... "a": [ ... datetime(2024, 1, 1, tzinfo=timezone.utc), ... datetime(2024, 1, 2, tzinfo=timezone.utc), ... ] ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("a").dt.convert_time_zone("Asia/Kathmandu") ... ).to_native() We can then pass pandas / PyArrow / Polars / any other supported library: >>> my_library_agnostic_function(df_pd) a 0 2024-01-01 05:45:00+05:45 1 2024-01-02 05:45:00+05:45 >>> my_library_agnostic_function(df_pl) shape: (2, 1) ┌──────────────────────────────┠│ a │ │ --- │ │ datetime[μs, Asia/Kathmandu] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2024-01-01 05:45:00 +0545 │ │ 2024-01-02 05:45:00 +0545 │ └──────────────────────────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: timestamp[us, tz=Asia/Kathmandu] ---- a: [[2024-01-01 00:00:00.000000Z,2024-01-02 00:00:00.000000Z]] z…Target `time_zone` cannot be `None` in `convert_time_zone`. Please use `replace_time_zone(None)` if you want to remove the time zone.cól•—‰jj|«jj‰«Sr")r™rrxÚconvert_time_zoner!s €€rr,z9ExprDateTimeNamespace.convert_time_zone..r#r)rðr™r.)r#r"rôs`` rr&z'ExprDateTimeNamespace.convert_time_zoneÓs8ù€ðv Ð ðZˆCܘC“.Ð Øz‰z×#Ñ#Ü Zó ð rcón‡‡—‰dvrd‰›d}t|«‚‰jjˆˆfd„«S)uÖ Return a timestamp in the given time unit. Arguments: time_unit: {'ns', 'us', 'ms'} Time unit. Returns: A new expression. Examples: >>> from datetime import date >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"date": [date(2001, 1, 1), None, date(2001, 1, 3)]} >>> df_pd = pd.DataFrame(data, dtype="datetime64[ns]") >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.col("date").dt.timestamp().alias("timestamp_us"), ... nw.col("date").dt.timestamp("ms").alias("timestamp_ms"), ... ).to_native() We can then pass pandas / PyArrow / Polars / any other supported library: >>> my_library_agnostic_function(df_pd) date timestamp_us timestamp_ms 0 2001-01-01 9.783072e+14 9.783072e+11 1 NaT NaN NaN 2 2001-01-03 9.784800e+14 9.784800e+11 >>> my_library_agnostic_function(df_pl) shape: (3, 3) ┌────────────┬─────────────────┬──────────────┠│ date ┆ timestamp_us ┆ timestamp_ms │ │ --- ┆ --- ┆ --- │ │ date ┆ i64 ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2001-01-01 ┆ 978307200000000 ┆ 978307200000 │ │ null ┆ null ┆ null │ │ 2001-01-03 ┆ 978480000000000 ┆ 978480000000 │ └────────────┴─────────────────┴──────────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table date: date32[day] timestamp_us: int64 timestamp_ms: int64 ---- date: [[2001-01-01,null,2001-01-03]] timestamp_us: [[978307200000000,null,978480000000000]] timestamp_ms: [[978307200000,null,978480000000]] >ÚmsÚnsÚusz=invalid `time_unit` Expected one of {'ns', 'us', 'ms'}, got ú.cól•—‰jj|«jj‰«Sr")r™rrxÚ timestamp)r+r#Ú time_units €€rr,z1ExprDateTimeNamespace.timestamp..Ws'ø€˜Ÿ ™ ×5Ñ5°cÓ:×=Ñ=×GÑGÈ ÓR€r)rr™r.)r#r.rôs`` rr-zExprDateTimeNamespace.timestampsMù€ðv Ð.Ñ .ðAØAJÀ ÈQðPð ô˜S“/Ð !Øz‰z×#Ñ#Ü Ró ð rNr r¡)r#rrÑrrr”)r#rr"rÜrr”)r#rr"rrr”)r*)r#rr.zLiteral['ns', 'us', 'ms']rr”)rr‘r’r%rärèrìrïròrõrùrürrrr rrrrrr r&r-r6rrrwrwås„óó- ó^5 ón6 óp7 ór5 ón6 óp5 ón6 óp6 óp6 óp+ óZ0 ód0 ód5 ón5 ón2 óhT ól: óx@ õDC rrwcóD—eZdZd d„Zd d„Zd d„Zd d„Zd d„Zd d„Zd d„Z y)r}có—||_yr"r˜ršs rr%zExprNameNamespace.__init__\r›rcó@‡—‰jjˆfd„«S)aKeep the original root name of the expression. Returns: A new expression. Notes: This will undo any previous renaming operations on the expression. Due to implementation constraints, this method can only be called as the last expression in a chain. Only one name operation per expression will work. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> data = {"foo": [1, 2], "BAR": [4, 5]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.col("foo").alias("alias_for_foo").name.keep() ... ).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd).columns Index(['foo'], dtype='object') >>> my_library_agnostic_function(df_pl).columns ['foo'] cój•—‰jj|«jj«Sr")r™rr4Úkeepr*s €rr,z(ExprNameNamespace.keep..ƒs%ø€˜Ÿ ™ ×5Ñ5°cÓ:×?Ñ?×DÑDÓF€rrŸr/s`rr3zExprNameNamespace.keep_s ø€ðFz‰z×#Ñ#Û Fó ð rcóD‡‡—‰jjˆˆfd„«S)aŸRename the output of an expression by mapping a function over the root name. Arguments: function: Function that maps a root name to a new name. Returns: A new expression. Notes: This will undo any previous renaming operations on the expression. Due to implementation constraints, this method can only be called as the last expression in a chain. Only one name operation per expression will work. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> data = {"foo": [1, 2], "BAR": [4, 5]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> renaming_func = lambda s: s[::-1] # reverse column name >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("foo", "BAR").name.map(renaming_func)).to_native() We can then pass either pandas or Polars to `func`: >>> my_library_agnostic_function(df_pd).columns Index(['oof', 'RAB'], dtype='object') >>> my_library_agnostic_function(df_pl).columns ['oof', 'RAB'] cól•—‰jj|«jj‰«Sr")r™rr4Úmap)r+r7r#s €€rr,z'ExprNameNamespace.map..¬s'ø€˜Ÿ ™ ×5Ñ5°cÓ:×?Ñ?×CÑCÀHÓM€rrŸ)r#r7s``rr6zExprNameNamespace.map†s ù€ðJz‰z×#Ñ#Ü Mó ð rcóD‡‡—‰jjˆˆfd„«S)atAdd a prefix to the root column name of the expression. Arguments: prefix: Prefix to add to the root column name. Returns: A new expression. Notes: This will undo any previous renaming operations on the expression. Due to implementation constraints, this method can only be called as the last expression in a chain. Only one name operation per expression will work. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> data = {"foo": [1, 2], "BAR": [4, 5]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def add_colname_prefix(df_native: IntoFrameT, prefix: str) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("foo", "BAR").name.prefix(prefix)).to_native() We can then pass either pandas or Polars to `func`: >>> add_colname_prefix(df_pd, "with_prefix_").columns Index(['with_prefix_foo', 'with_prefix_BAR'], dtype='object') >>> add_colname_prefix(df_pl, "with_prefix_").columns ['with_prefix_foo', 'with_prefix_BAR'] cól•—‰jj|«jj‰«Sr")r™rr4rºr¹s €€rr,z*ExprNameNamespace.prefix..Õó'ø€˜Ÿ ™ ×5Ñ5°cÓ:×?Ñ?×FÑFÀvÓN€rrŸr»s``rrºzExprNameNamespace.prefix¯s ù€ðJz‰z×#Ñ#Ü Nó ð rcóD‡‡—‰jjˆˆfd„«S)asAdd a suffix to the root column name of the expression. Arguments: suffix: Suffix to add to the root column name. Returns: A new expression. Notes: This will undo any previous renaming operations on the expression. Due to implementation constraints, this method can only be called as the last expression in a chain. Only one name operation per expression will work. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> data = {"foo": [1, 2], "BAR": [4, 5]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def add_colname_suffix(df_native: IntoFrameT, suffix: str) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("foo", "BAR").name.suffix(suffix)).to_native() We can then pass either pandas or Polars to `func`: >>> add_colname_suffix(df_pd, "_with_suffix").columns Index(['foo_with_suffix', 'BAR_with_suffix'], dtype='object') >>> add_colname_suffix(df_pl, "_with_suffix").columns ['foo_with_suffix', 'BAR_with_suffix'] cól•—‰jj|«jj‰«Sr")r™rr4rÀr¿s €€rr,z*ExprNameNamespace.suffix..ýr9rrŸrÁs``rrÀzExprNameNamespace.suffixØs ù€ðHz‰z×#Ñ#Ü Nó ð rcó@‡—‰jjˆfd„«S)a–Make the root column name lowercase. Returns: A new expression. Notes: This will undo any previous renaming operations on the expression. Due to implementation constraints, this method can only be called as the last expression in a chain. Only one name operation per expression will work. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> data = {"foo": [1, 2], "BAR": [4, 5]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def to_lower(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("foo", "BAR").name.to_lowercase()).to_native() We can then pass either pandas or Polars to `func`: >>> to_lower(df_pd).columns Index(['foo', 'bar'], dtype='object') >>> to_lower(df_pl).columns ['foo', 'bar'] cój•—‰jj|«jj«Sr")r™rr4rÛr*s €rr,z0ExprNameNamespace.to_lowercase.."ó%ø€˜Ÿ ™ ×5Ñ5°cÓ:×?Ñ?×LÑLÓN€rrŸr/s`rrÛzExprNameNamespace.to_lowercases ø€ðBz‰z×#Ñ#Û Nó ð rcó@‡—‰jjˆfd„«S)a•Make the root column name uppercase. Returns: A new expression. Notes: This will undo any previous renaming operations on the expression. Due to implementation constraints, this method can only be called as the last expression in a chain. Only one name operation per expression will work. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> data = {"foo": [1, 2], "BAR": [4, 5]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> def to_upper(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("foo", "BAR").name.to_uppercase()).to_native() We can then pass either pandas or Polars to `func`: >>> to_upper(df_pd).columns Index(['FOO', 'BAR'], dtype='object') >>> to_upper(df_pl).columns ['FOO', 'BAR'] cój•—‰jj|«jj«Sr")r™rr4r×r*s €rr,z0ExprNameNamespace.to_uppercase..Fr>rrŸr/s`rr×zExprNameNamespace.to_uppercase%s ø€ð@z‰z×#Ñ#Û Nó ð rNr r¡)r#rr7zCallable[[str], str]rr”rÝrÞ) rr‘r’r%r3r6rºrÀrÛr×r6rrr}r}[s*„óó% óN' óR' óR& óP# ôJ" rr}có—eZdZdd„Zdd„Zy)r€có—||_yr"r˜ršs rr%zExprListNamespace.__init__Kr›rcó@‡—‰jjˆfd„«S)uðReturn the number of elements in each list. Null values count towards the total. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = {"a": [[1, 2], [3, 4, None], None, []]} Let's define a dataframe-agnostic function: >>> def agnostic_list_len(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns(a_len=nw.col("a").list.len()).to_native() We can then pass pandas / PyArrow / Polars / any other supported library: >>> agnostic_list_len( ... pd.DataFrame(data).astype({"a": pd.ArrowDtype(pa.list_(pa.int64()))}) ... ) # doctest: +SKIP a a_len 0 [1. 2.] 2 1 [ 3. 4. nan] 3 2 3 [] 0 >>> agnostic_list_len(pl.DataFrame(data)) shape: (4, 2) ┌──────────────┬───────┠│ a ┆ a_len │ │ --- ┆ --- │ │ list[i64] ┆ u32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ [1, 2] ┆ 2 │ │ [3, 4, null] ┆ 3 │ │ null ┆ null │ │ [] ┆ 0 │ └──────────────┴───────┘ >>> agnostic_list_len(pa.table(data)) pyarrow.Table a: list child 0, item: int64 a_len: uint32 ---- a: [[[1,2],[3,4,null],null,[]]] a_len: [[2,3,null,0]] cój•—‰jj|«jj«Sr")r™rrñrKr*s €rr,z'ExprListNamespace.len..†s%ø€˜Ÿ ™ ×5Ñ5°cÓ:×?Ñ?×CÑCÓE€rrŸr/s`rrKzExprListNamespace.lenNs ø€ðnz‰z×#Ñ#Û Eó ð rNr r¡)rr‘r’r%rKr6rrr€r€Js „óô9 rr€có&‡—dˆfd„ }t|«S)usCreates an expression that references one or more columns by their name(s). Arguments: names: Name(s) of the columns to use in the aggregation function. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pl = pl.DataFrame({"a": [1, 2], "b": [3, 4]}) >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [3, 4]}) >>> df_pa = pa.table({"a": [1, 2], "b": [3, 4]}) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("a") * nw.col("b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 3 1 8 >>> my_library_agnostic_function(df_pl) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 3 │ │ 8 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[3,8]] có4•—|jt‰«ŽSr")Úcolr)r+Únamess €rÚfunczcol..funcºsø€Øˆsw‰wœ ›Ð'Ð'r©r+rrr©r)rHrIs` rrGrGŠsø€õ`(ô ‹:Ðrcó&‡—dˆfd„ }t|«S)uÞCreates an expression that references one or more columns by their index(es). Notes: `nth` is not supported for Polars version<1.0.0. Please use [`col`](/api-reference/narwhals/#narwhals.col) instead. Arguments: indices: One or more indices representing the columns to retrieve. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.nth(0) * 2).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 2 1 4 >>> my_library_agnostic_function(df_pl) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 4 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[2,4]] có4•—|jt‰«ŽSr")Únthr)r+Úindicess €rrIznth..funcôsø€Øˆsw‰wœ Ó(Ð)Ð)rrJrK)rOrIs` rrNrNÀsø€õh*ô ‹:Ðrcó—td„«S)uÊInstantiate an expression representing all columns. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]}) >>> df_pl = pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]}) >>> df_pa = pa.table({"a": [1, 2, 3], "b": [4, 5, 6]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.all() * 2).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b 0 2 8 1 4 10 2 6 12 >>> my_library_agnostic_function(df_pl) shape: (3, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 2 ┆ 8 │ │ 4 ┆ 10 │ │ 6 ┆ 12 │ └─────┴─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[2,4,6]] b: [[8,10,12]] có"—|j«Sr")rš©r+s rr,zall_..+s €˜CŸG™G›I€rrKr6rrÚall_rSûs€ô` Ñ%Ó &Ð&rcó —dd„}t|«S)uÂReturn the number of rows. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [5, 10]}) >>> df_pl = pl.DataFrame({"a": [1, 2], "b": [5, 10]}) >>> df_pa = pa.table({"a": [1, 2], "b": [5, 10]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.len()).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) len 0 2 >>> my_library_agnostic_function(df_pl) shape: (1, 1) ┌─────┠│ len │ │ --- │ │ u32 │ â•žâ•â•â•â•â•â•¡ │ 2 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table len: int64 ---- len: [[2]] có"—|j«Sr")rKrRs rrIzlen_..funcZs€Øw‰w‹yÐrrJrK)rIs rÚlen_rV/s€óVô ‹:Ðrcó ‡—tˆfd„«S)u!Sum all values. Note: Syntactic sugar for ``nw.col(columns).sum()`` Arguments: columns: Name(s) of the columns to use in the aggregation function Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pl = pl.DataFrame({"a": [1, 2]}) >>> df_pd = pd.DataFrame({"a": [1, 2]}) >>> df_pa = pa.table({"a": [1, 2]}) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.sum("a")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 3 >>> my_library_agnostic_function(df_pl) shape: (1, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 3 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[3]] có"•—|j‰ŽSr")r)©r+Úcolumnss €rr,zsum..óø€˜G˜CŸG™G WÐ-€rrK©rZs`rr)r)`óø€ô` Ó-Ó .Ð.rcó ‡—tˆfd„«S)u5Get the mean value. Note: Syntactic sugar for ``nw.col(columns).mean()`` Arguments: columns: Name(s) of the columns to use in the aggregation function Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pl = pl.DataFrame({"a": [1, 8, 3]}) >>> df_pd = pd.DataFrame({"a": [1, 8, 3]}) >>> df_pa = pa.table({"a": [1, 8, 3]}) We define a dataframe agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.mean("a")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 4.0 >>> my_library_agnostic_function(df_pl) shape: (1, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 4.0 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: double ---- a: [[4]] có"•—|j‰ŽSr")r©rYs €rr,zmean..Ãsø€˜H˜CŸH™H gÐ.€rrKr\s`rr©r©“sø€ô` Ó.Ó /Ð/rcó ‡—tˆfd„«S)uÊ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 Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> 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: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.median("a")).to_native() We can then pass any supported library such as pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 4.0 >>> my_library_agnostic_function(df_pl) shape: (1, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 4.0 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: double ---- a: [[4]] có"•—|j‰ŽSr")r­rYs €rr,zmedian..÷sø€˜J˜CŸJ™J¨Ð0€rrKr\s`rr­r­Æsø€ôb Ó0Ó 1Ð1rcó ‡—tˆfd„«S)uYReturn the minimum value. Note: Syntactic sugar for ``nw.col(columns).min()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [5, 10]}) >>> df_pl = pl.DataFrame({"a": [1, 2], "b": [5, 10]}) >>> df_pa = pa.table({"a": [1, 2], "b": [5, 10]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.min("b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) b 0 5 >>> my_library_agnostic_function(df_pl) shape: (1, 1) ┌─────┠│ b │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 5 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table b: int64 ---- b: [[5]] có"•—|j‰ŽSr")r¾rYs €rr,zmin..*r[rrKr\s`rr¾r¾úr]rcó ‡—tˆfd„«S)uYReturn the maximum value. Note: Syntactic sugar for ``nw.col(columns).max()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Returns: A new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pd = pd.DataFrame({"a": [1, 2], "b": [5, 10]}) >>> df_pl = pl.DataFrame({"a": [1, 2], "b": [5, 10]}) >>> df_pa = pa.table({"a": [1, 2], "b": [5, 10]}) Let's define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.max("a")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 2 >>> my_library_agnostic_function(df_pl) shape: (1, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[2]] có"•—|j‰ŽSr")rÁrYs €rr,zmax..]r[rrKr\s`rrÁrÁ-r]rcó>‡—‰s d}t|«‚tˆfd„«S)uûSum all values horizontally across columns. Warning: Unlike Polars, we support horizontal sum over numeric columns only. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [5, 10, None]} >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.sum_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 6.0 1 12.0 2 3.0 >>> my_library_agnostic_function(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 6 │ │ 12 │ │ 3 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 ---- a: [[6,12,3]] z:At least one expression must be passed to `sum_horizontal`c ón•—|jt‰«Dcgc]}t||«‘Œc}ŽScc}wr")Úsum_horizontalrr©r+ÚvÚexprss €rr,z sum_horizontal..šó2ø€Ð&C×&Ñ&Ü18¸³Ö @¨AÔ  QÕ'Ò @ð €ùÚ @ó›2©rr©rkrôs` rrhrh`s*ø€ñl ØJˆÜ˜‹oÐÜ ó ó ðrcó>‡—‰s d}t|«‚tˆfd„«S)u4Get the minimum value horizontally across columns. Notes: We support `min_horizontal` over numeric columns only. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = { ... "a": [1, 8, 3], ... "b": [4, 5, None], ... "c": ["x", "y", "z"], ... } We define a dataframe-agnostic function that computes the horizontal min of "a" and "b" columns: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.min_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.DataFrame(data)) a 0 1.0 1 5.0 2 3.0 >>> my_library_agnostic_function(pl.DataFrame(data)) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 1 │ │ 5 │ │ 3 │ └─────┘ >>> my_library_agnostic_function(pa.table(data)) pyarrow.Table a: int64 ---- a: [[1,5,3]] z:At least one expression must be passed to `min_horizontal`c ón•—|jt‰«Dcgc]}t||«‘Œc}ŽScc}wr")Úmin_horizontalrrris €rr,z min_horizontal..Ürlrmrnros` rrrrr ó*ø€ñp ØJˆÜ˜‹oÐÜ ó ó ðrcó>‡—‰s d}t|«‚tˆfd„«S)u4Get the maximum value horizontally across columns. Notes: We support `max_horizontal` over numeric columns only. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = { ... "a": [1, 8, 3], ... "b": [4, 5, None], ... "c": ["x", "y", "z"], ... } We define a dataframe-agnostic function that computes the horizontal max of "a" and "b" columns: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.max_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.DataFrame(data)) a 0 4.0 1 8.0 2 3.0 >>> my_library_agnostic_function(pl.DataFrame(data)) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 4 │ │ 8 │ │ 3 │ └─────┘ >>> my_library_agnostic_function(pa.table(data)) pyarrow.Table a: int64 ---- a: [[4,8,3]] z:At least one expression must be passed to `max_horizontal`c ón•—|jt‰«Dcgc]}t||«‘Œc}ŽScc}wr")Úmax_horizontalrrris €rr,z max_horizontal..rlrmrnros` rrvrvârsrcó$—eZdZdd„Zdd„Zdd„Zy)ÚWhencó&—t|g«|_yr")rÚ _predicatesr s rr%z When.__init__%s€Ü" J <Ó0ˆÕrcóT—|jDcgc]}t||«‘Œc}Scc}wr")rzr)r#r+rjs rÚ_extract_predicateszWhen._extract_predicates(s$€Ø37×3CÑ3CÖD¨aÔ! # qÕ)ÒDÐDùÒDs%có$‡‡—tˆˆfd„«S)Ncór•—|j‰j|«Žjt|‰««Sr")Úwhenr|Úthenr©r+r#rs €€rr,zWhen.then..-s2ø€˜˜Ÿ™ $×":Ñ":¸3Ó"?Ð@×EÑEÜ! # uÓ-ó€r)ÚThen©r#rs``rr€z When.then+óù€Üô ó ð rN)r úIntoExpr | Iterable[IntoExpr]rr‚rJ)rrrr‚)rr‘r’r%r|r€r6rrrxrx$s„ó1óEô rrxcó—eZdZdd„Zy)r‚có$‡‡—tˆˆfd„«S)NcóX•—‰j|«jt|‰««Sr")rÚ otherwiserrs €€rr,z Then.otherwise..6s'ø€˜×/Ñ/°Ó4×>Ñ>Ü! # uÓ-ó€rrKrƒs``rr‰zThen.otherwise4r„rN)rrrr)rr‘r’r‰r6rrr‚r‚3s„ô rr‚có—t|ŽS)u¦ Start a `when-then-otherwise` expression. Expression similar to an `if-else` statement in Python. Always initiated by a `pl.when().then()`, and optionally followed by chaining one or more `.when().then()` statements. Chained when-then operations should be read as Python `if, elif, ... elif` blocks, not as `if, if, ... if`, i.e. the first condition that evaluates to `True` will be picked. If none of the conditions are `True`, an optional `.otherwise()` can be appended at the end. If not appended, and none of the conditions are `True`, `None` will be returned. Arguments: predicates: Condition(s) that must be met in order to apply the subsequent statement. Accepts one or more boolean expressions, which are implicitly combined with `&`. String input is parsed as a column name. Returns: A "when" object, which `.then` can be called on. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pl = pl.DataFrame({"a": [1, 2, 3], "b": [5, 10, 15]}) >>> df_pd = pd.DataFrame({"a": [1, 2, 3], "b": [5, 10, 15]}) >>> df_pa = pa.table({"a": [1, 2, 3], "b": [5, 10, 15]}) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns( ... nw.when(nw.col("a") < 3).then(5).otherwise(6).alias("a_when") ... ).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b a_when 0 1 5 5 1 2 10 5 2 3 15 6 >>> my_library_agnostic_function(df_pl) shape: (3, 3) ┌─────┬─────┬────────┠│ a ┆ b ┆ a_when │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•¡ │ 1 ┆ 5 ┆ 5 │ │ 2 ┆ 10 ┆ 5 │ │ 3 ┆ 15 ┆ 6 │ └─────┴─────┴────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 b: int64 a_when: int64 ---- a: [[1,2,3]] b: [[5,10,15]] a_when: [[5,5,6]] )rx)r s rrr<s€ôF Ð Ðrcó>‡—‰s d}t|«‚tˆfd„«S)u Compute the bitwise AND horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": [False, False, True, True, False, None], ... "b": [False, True, True, None, None, None], ... } >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data).convert_dtypes(dtype_backend="pyarrow") >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select("a", "b", all=nw.all_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b all 0 False False False 1 False True False 2 True True True 3 True 4 False False 5 >>> my_library_agnostic_function(df_pl) shape: (6, 3) ┌───────┬───────┬───────┠│ a ┆ b ┆ all │ │ --- ┆ --- ┆ --- │ │ bool ┆ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ false ┆ false ┆ false │ │ false ┆ true ┆ false │ │ true ┆ true ┆ true │ │ true ┆ null ┆ null │ │ false ┆ null ┆ false │ │ null ┆ null ┆ null │ └───────┴───────┴───────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: bool b: bool all: bool ---- a: [[false,false,true,true,false,null]] b: [[false,true,true,null,null,null]] all: [[false,false,true,null,false,null]] z:At least one expression must be passed to `all_horizontal`c ón•—|jt‰«Dcgc]}t||«‘Œc}ŽScc}wr")Úall_horizontalrrris €rr,z all_horizontal..Çrlrmrnros` rrr‚ó*ø€ñB ØJˆÜ˜‹oÐÜ ó ó ðrNc󠇇—t‰«r d}t|«‚t‰ttf«rd‰›}t |«‚t ˆˆfd„«S)uPReturn an expression representing a literal value. Arguments: value: The value to use as literal. dtype: The data type of the literal value. If not provided, the data type will be inferred. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> df_pl = pl.DataFrame({"a": [1, 2]}) >>> df_pd = pd.DataFrame({"a": [1, 2]}) >>> df_pa = pa.table({"a": [1, 2]}) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_columns(nw.lit(3)).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a literal 0 1 3 1 2 3 >>> my_library_agnostic_function(df_pl) shape: (2, 2) ┌─────┬─────────┠│ a ┆ literal │ │ --- ┆ --- │ │ i64 ┆ i32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•¡ │ 1 ┆ 3 │ │ 2 ┆ 3 │ └─────┴─────────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: int64 literal: int64 ---- a: [[1,2]] literal: [[3,3]] zvnumpy arrays are not supported as literal values. Consider using `with_columns` to create a new column from the array.z,Nested datatypes are not supported yet. Got có(•—|j‰‰«Sr")Úlit)r+r>rs €€rr,zlit.. sø€˜CŸG™G E¨5Ó1€r)r rrrñÚtuplerr)rr>rôs`` rr‘r‘ÍsVù€ôdeÔð Sð ô˜‹oÐä%œ$¤˜Ô'Ø<¸U¸GÐDˆÜ! #Ó&Ð&ä Ô1Ó 2Ð2rcó>‡—‰s d}t|«‚tˆfd„«S)u Compute the bitwise OR horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": [False, False, True, True, False, None], ... "b": [False, True, True, None, None, None], ... } >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data).convert_dtypes(dtype_backend="pyarrow") >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select("a", "b", any=nw.any_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a b any 0 False False False 1 False True True 2 True True True 3 True True 4 False 5 >>> my_library_agnostic_function(df_pl) shape: (6, 3) ┌───────┬───────┬───────┠│ a ┆ b ┆ any │ │ --- ┆ --- ┆ --- │ │ bool ┆ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ false ┆ false ┆ false │ │ false ┆ true ┆ true │ │ true ┆ true ┆ true │ │ true ┆ null ┆ true │ │ false ┆ null ┆ null │ │ null ┆ null ┆ null │ └───────┴───────┴───────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: bool b: bool any: bool ---- a: [[false,false,true,true,false,null]] b: [[false,true,true,null,null,null]] any: [[false,true,true,true,null,null]] z:At least one expression must be passed to `any_horizontal`c ón•—|jt‰«Dcgc]}t||«‘Œc}ŽScc}wr")Úany_horizontalrrris €rr,z any_horizontal..Rrlrmrnros` rr•r• rŽrcó>‡—‰s d}t|«‚tˆfd„«S)uICompute the mean of all values horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Returns: A new expression. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": [1, 8, 3], ... "b": [4, 5, None], ... "c": ["x", "y", "z"], ... } >>> df_pl = pl.DataFrame(data) >>> df_pd = pd.DataFrame(data) >>> df_pa = pa.table(data) We define a dataframe-agnostic function that computes the horizontal mean of "a" and "b" columns: >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.mean_horizontal("a", "b")).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(df_pd) a 0 2.5 1 6.5 2 3.0 >>> my_library_agnostic_function(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 2.5 │ │ 6.5 │ │ 3.0 │ └─────┘ >>> my_library_agnostic_function(df_pa) pyarrow.Table a: double ---- a: [[2.5,6.5,3]] z;At least one expression must be passed to `mean_horizontal`c ón•—|jt‰«Dcgc]}t||«‘Œc}ŽScc}wr")Úmean_horizontalrrris €rr,z!mean_horizontal..–s2ø€Ð'C×'Ñ'Ü18¸³Ö @¨AÔ  QÕ'Ò @ð €ùÚ @rmrnros` rr˜r˜Xs*ø€ñt ØKˆÜ˜‹oÐÜ ó ó ðrÚF©Ú separatorr£có,‡‡‡‡—tˆˆˆˆfd„«S)uJ Horizontally concatenate columns into a single string column. Arguments: exprs: Columns to concatenate into a single string column. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. Non-`String` columns are cast to `String`. *more_exprs: Additional columns to concatenate into a single string column, specified as positional arguments. separator: String that will be used to separate the values of each column. ignore_nulls: Ignore null values (default is `False`). If set to `False`, null values will be propagated and if the row contains any null values, the output is null. Returns: A new expression. Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> data = { ... "a": [1, 2, 3], ... "b": ["dogs", "cats", None], ... "c": ["play", "swim", "walk"], ... } We define a dataframe-agnostic function that computes the horizontal string concatenation of different columns >>> def my_library_agnostic_function(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select( ... nw.concat_str( ... [ ... nw.col("a") * 2, ... nw.col("b"), ... nw.col("c"), ... ], ... separator=" ", ... ).alias("full_sentence") ... ).to_native() We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> my_library_agnostic_function(pd.DataFrame(data)) full_sentence 0 2 dogs play 1 4 cats swim 2 None >>> my_library_agnostic_function(pl.DataFrame(data)) shape: (3, 1) ┌───────────────┠│ full_sentence │ │ --- │ │ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2 dogs play │ │ 4 cats swim │ │ null │ └───────────────┘ >>> my_library_agnostic_function(pa.table(data)) pyarrow.Table full_sentence: string ---- full_sentence: [["2 dogs play","4 cats swim",null]] c 󺕗|jt‰g«Dcgc]}t||«‘Œc}g‰Dcgc]}t||«‘Œc}¢­‰‰dœŽScc}wcc}w)Nrš)Ú concat_strrr)r+rjrkr£Ú more_exprsr›s €€€€rr,zconcat_str..és]ø€NC—N‘NÜ07¸¸Ó0@Ö A¨1Ô ˜s AÕ &Ò Að à1;Ö <¨AÔ  QÕ'Ò <ñ ð Ø%ò  €ùÚ AùÚ rˆrr) rkr…rŸrr›rr£r†rr)5Ú __future__rÚtypingrrrrrr r r r Únarwhals.dependenciesr Únarwhals.dtypesrÚnarwhals.utilsrrÚtyping_extensionsrrÚnarwhals.typingrrrr”rzrurwr}r€rGrNrSrVr)r©r­r¾rÁrhrrrvrxr‚rrr‘r•r˜ržÚ__all__r6rrúr¨s…ðÝ"å ÝÝÝÝÝÝÝÝå0Ý+Ý6Ý"áÝ&å%Ý(ó÷y6'ñy6'ñxm ˜tÔ$€ô/ w˜u‘~ô/ ôdN  ˜' %™.ôN  ôbs ˜G E™Nôs ôl#l ˜ ™ôl ô^= ˜ ™ô= ó@3ól7óv0'óh.ób0/óf00óf12óh0/óf0/óf=ó@?óD?÷D  ñ  ô ˆ4ô óCóLHôV=3ó@HóVAðNØñ SØ (ðSàðSððSðð Sð  ó Sðn ð r