U )3gžÜã@snddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlm Z dd lm Z dd l m Z dd l mZer¬dd lmZdd lmZddlmZddddœdd„ZGdd„dƒZe dedZGdd„deeƒZGdd„deeƒZGdd„deeƒZGdd„deeƒZddd œd!d"„Zd#dd$œd%d&„Zdd'œd(d)„Zdd'œd*d+„Zd,dd-œd.d/„Z d,dd-œd0d1„Z!d,dd-œd2d3„Z"d,dd-œd4d5„Z#d6dd7œd8d9„Z$d6dd7œd:d;„Z%d6dd7œdd?„d?ƒZ'Gd@dA„dAeƒZ(d6d?dBœdCdD„Z)d6dd7œdEdF„Z*dXddHddIœdJdK„Z+d6dd7œdLdM„Z,d6dd7œdNdO„Z-dPdQdRœd6dSd,dTddUœdVdW„Z.dgZ/dGS)Yé)Ú annotations)Ú TYPE_CHECKING)ÚAny)ÚCallable)ÚGeneric)ÚIterable)ÚLiteral)ÚSequence)ÚTypeVar)Úis_numpy_array)Úflatten)ÚSelf)ÚDType)ÚIntoExprÚExprr)ÚexprÚotherÚreturncCs4ddlm}t|tƒr | |¡St||ƒr0|jS|S)Nr)ÚSeries)Znarwhals.seriesrÚ isinstancerÚ_callZ_compliant_series)rrr©rú1/tmp/pip-unpacked-wheel-hfsjijke/narwhals/expr.pyÚextract_compliants     rc @s¼eZdZdddœdd„Zddœdd „Zd dd œd d „Zdddddœdd„Zddddœdd„Zdddœdd„Zdddœdd„Z dddœdd„Z dddœdd „Z dddœd!d"„Z dddœd#d$„Z dddœd%d&„Zdddœd'd(„Zdddœd)d*„Zdddœd+d,„Zdddœd-d.„Zdddœd/d0„Zdddœd1d2„Zdddœd3d4„Zdddœd5d6„Zdddœd7d8„Zdddœd9d:„Zdddœd;d<„Zdddœd=d>„Zdddœd?d@„ZdddœdAdB„ZdddœdCdD„ZdddœdEdF„ZdddœdGdH„ZddœdIdJ„Z ddœdKdL„Z!ddœdMdN„Z"ddœdOdP„Z#dQdRœdSddTœdUdV„Z$ddœdWdX„Z%ddœdYdZ„Z&ddœd[d\„Z'ddœd]d^„Z(ddœd_d`„Z)dadbœdcdddœdedf„Z*ddœdgdh„Z+ddœdidj„Z,ddœdkdl„Z-dSddmœdndo„Z.dpdpdddqœdrds„Z/dadadtœdcdcdduœdvdw„Z0dÅddd ddyœdzd{„Z1dddœd|d}„Z2ddd~œdd€„Z3ddœdd‚„Z4ddœdƒd„„Z5ddd…œd†d‡„Z6ddœdˆd‰„Z7dÆdŠdadŠd‹œddŒddcdŒddŽœdd„Z8d‘dd’œd“d”„Z9ddœd•d–„Z:ddœd—d˜„Z;ddœd™dš„ZdŸd dd¡œd¢d£„Z?dÇdSddmœd¥d¦„Z@dÈdSddmœd§d¨„ZAdÉdSddªœd«d¬„ZBddœd­d®„ZCdÊddSdSdd¯œd°d±„ZDdËd²d²dd³œd´dµ„ZEddd¶œd·d¸„ZFeGdd¹d¶œdºd»„ƒZHeGdd¼d¶œd½d¾„ƒZIeGdd¿d¶œdÀdÁ„ƒZJeGddÂd¶œdÃdÄ„ƒZKdŠS)ÌrúCallable[[Any], Any]ÚNone©ÚcallrcCs ||_dS©N©r©ÚselfrrrrÚ__init__!sz Expr.__init__r ©rcsˆ ‡fdd„¡S)Ncsˆ |¡ ¡ ¡Sr)rÚabsÚsum©Úplx©r!rrÚ(óz$Expr._taxicab_norm..©Ú __class__r(rr(rÚ _taxicab_norm%szExpr._taxicab_normÚstr)Únamercsˆ ‡‡fdd„¡S)u¶ Rename the expression. Arguments: name: The new name. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select((nw.col("b") + 10).alias("c")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) c 0 14 1 15 >>> func(df_pl) shape: (2, 1) ┌─────┠│ c │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 14 │ │ 15 │ └─────┘ >>> func(df_pa) pyarrow.Table c: int64 ---- c: [[14,15]] csˆ |¡ ˆ¡Sr)rÚaliasr&©r/r!rrr)Xr*zExpr.alias..r+)r!r/rr1rr0+s-z Expr.aliaszCallable[[Any], Self]r)ÚfunctionÚargsÚkwargsrcOs||f|ž|ŽS)u¹ Pipe function call. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").pipe(lambda x: x + 1)) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 2 1 3 2 4 3 5 >>> func(df_pl) shape: (4, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 3 │ │ 4 │ │ 5 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[2,3,4,5]] r)r!r2r3r4rrrÚpipeZs.z Expr.pipezDType | type[DType])r!Údtypercsˆ ‡‡fdd„¡S)uh Redefine an object's data type. Arguments: dtype: Data type that the object will be cast into. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select( ... nw.col("foo").cast(nw.Float32), nw.col("bar").cast(nw.UInt8) ... ) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) foo bar 0 1.0 6 1 2.0 7 2 3.0 8 >>> func(df_pl) shape: (3, 2) ┌─────┬─────┠│ foo ┆ bar │ │ --- ┆ --- │ │ f32 ┆ u8 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1.0 ┆ 6 │ │ 2.0 ┆ 7 │ │ 3.0 ┆ 8 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table foo: float bar: uint8 ---- foo: [[1,2,3]] bar: [[6,7,8]] csˆ |¡ ˆ¡Sr)rÚcastr&©r6r!rrr)¾r*zExpr.cast..r+)r!r6rr8rr7Šs3 ÿz Expr.castÚobject)rrcsˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__eq__rr&©rr!rrr)Är*zExpr.__eq__..r+©r!rrr;rr:Âs ÿz Expr.__eq__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__ne__rr&r;rrr)Ér*zExpr.__ne__..r+r<rr;rr=Çs ÿz Expr.__ne__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__and__rr&r;rrr)Îr*zExpr.__and__..r+r<rr;rr>Ìs ÿz Expr.__and__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__rand__rr&r;rrr)Ór*zExpr.__rand__..r+r<rr;rr?Ñs ÿz Expr.__rand__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__or__rr&r;rrr)Ør*zExpr.__or__..r+r<rr;rr@Ös ÿz Expr.__or__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__ror__rr&r;rrr)Ýr*zExpr.__ror__..r+r<rr;rrAÛs ÿz Expr.__ror__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__add__rr&r;rrr)âr*zExpr.__add__..r+r<rr;rrBàs ÿz Expr.__add__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__radd__rr&r;rrr)çr*zExpr.__radd__..r+r<rr;rrCås ÿz Expr.__radd__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__sub__rr&r;rrr)ìr*zExpr.__sub__..r+r<rr;rrDês ÿz Expr.__sub__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__rsub__rr&r;rrr)ñr*zExpr.__rsub__..r+r<rr;rrEïs ÿz Expr.__rsub__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ __truediv__rr&r;rrr)ör*z"Expr.__truediv__..r+r<rr;rrFôs ÿzExpr.__truediv__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ __rtruediv__rr&r;rrr)ûr*z#Expr.__rtruediv__..r+r<rr;rrGùs ÿzExpr.__rtruediv__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__mul__rr&r;rrr)r*zExpr.__mul__..r+r<rr;rrHþs ÿz Expr.__mul__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__rmul__rr&r;rrr)r*zExpr.__rmul__..r+r<rr;rrIs ÿz Expr.__rmul__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__le__rr&r;rrr) r*zExpr.__le__..r+r<rr;rrJs ÿz Expr.__le__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__lt__rr&r;rrr)r*zExpr.__lt__..r+r<rr;rrK s ÿz Expr.__lt__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__gt__rr&r;rrr)r*zExpr.__gt__..r+r<rr;rrLs ÿz Expr.__gt__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__ge__rr&r;rrr)r*zExpr.__ge__..r+r<rr;rrMs ÿz Expr.__ge__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__pow__rr&r;rrr)r*zExpr.__pow__..r+r<rr;rrNs ÿz Expr.__pow__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__rpow__rr&r;rrr)#r*zExpr.__rpow__..r+r<rr;rrO!s ÿz Expr.__rpow__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ __floordiv__rr&r;rrr)(r*z#Expr.__floordiv__..r+r<rr;rrP&s ÿzExpr.__floordiv__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ __rfloordiv__rr&r;rrr)-r*z$Expr.__rfloordiv__..r+r<rr;rrQ+s ÿzExpr.__rfloordiv__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__mod__rr&r;rrr)2r*zExpr.__mod__..r+r<rr;rrR0s ÿz Expr.__mod__csˆ ‡‡fdd„¡S)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ__rmod__rr&r;rrr)7r*zExpr.__rmod__..r+r<rr;rrS5s ÿz Expr.__rmod__csˆ ‡fdd„¡S)Ncsˆ |¡ ¡Sr)rÚ __invert__r&r(rrr)<r*z!Expr.__invert__..r+r(rr(rrT;szExpr.__invert__csˆ ‡fdd„¡S)uF Return whether any of the values in the column are `True` Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").any()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 True True >>> func(df_pl) shape: (1, 2) ┌──────┬──────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ true ┆ true │ └──────┴──────┘ >>> func(df_pa) pyarrow.Table a: bool b: bool ---- a: [[true]] b: [[true]] csˆ |¡ ¡Sr)rÚanyr&r(rrr)gr*zExpr.any..r+r(rr(rrU>s)zExpr.anycsˆ ‡fdd„¡S)uS Return whether all values in the column are `True`. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").all()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 False True >>> func(df_pl) shape: (1, 2) ┌───────┬──────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ false ┆ true │ └───────┴──────┘ >>> func(df_pa) pyarrow.Table a: bool b: bool ---- a: [[false]] b: [[true]] csˆ |¡ ¡Sr)rÚallr&r(rrr)’r*zExpr.all..r+r(rr(rrVis)zExpr.allcsˆ ‡fdd„¡S)uî Get mean value. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").mean()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 0.0 4.0 >>> func(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 0.0 ┆ 4.0 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: double b: double ---- a: [[0]] b: [[4]] csˆ |¡ ¡Sr)rÚmeanr&r(rrr)½r*zExpr.mean..r+r(rr(rrW”s)z Expr.meané©ÚddofÚint)rZrcsˆ ‡‡fdd„¡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. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").std(ddof=0)) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 17.79513 1.265789 >>> func(df_pl) shape: (1, 2) ┌──────────┬──────────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ 17.79513 ┆ 1.265789 │ └──────────┴──────────┘ >>> func(df_pa) pyarrow.Table a: double b: double ---- a: [[17.795130420052185]] b: [[1.2657891697365016]] csˆ |¡jˆdS)NrY)rÚstdr&©rZr!rrr)ír*zExpr.std..r+)r!rZrr]rr\¿s.zExpr.stdcsˆ ‡fdd„¡S)ué Return the sum value. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").sum()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 15 150 >>> func(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 15 ┆ 150 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[15]] b: [[150]] csˆ |¡ ¡Sr)rr%r&r(rrr)r*zExpr.sum..r+r(rr(rr%ïs)zExpr.sumcsˆ ‡fdd„¡S)uç Returns the minimum value(s) from a column(s). Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.min("a", "b")) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 1 3 >>> func(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 3 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1]] b: [[3]] csˆ |¡ ¡Sr)rÚminr&r(rrr)Cr*zExpr.min..r+r(rr(rr^s)zExpr.mincsˆ ‡fdd„¡S)uÿ Returns the maximum value(s) from a column(s). Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.max("a", "b")) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 20 100 >>> func(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 20 ┆ 100 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[20]] b: [[100]] csˆ |¡ ¡Sr)rÚmaxr&r(rrr)nr*zExpr.max..r+r(rr(rr_Es)zExpr.maxcsˆ ‡fdd„¡S)u  Returns the number of non-null elements in the column. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.all().count()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 3 2 >>> func(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 3 ┆ 2 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[3]] b: [[2]] csˆ |¡ ¡Sr)rÚcountr&r(rrr)™r*zExpr.count..r+r(rr(rr`ps)z Expr.countcsˆ ‡fdd„¡S)u Returns count of unique values Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").n_unique()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 5 3 >>> func(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 5 ┆ 3 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[5]] b: [[3]] csˆ |¡ ¡Sr)rÚn_uniquer&r(rrr)Är*zExpr.n_unique..r+r(rr(rra›s)z Expr.n_uniqueF©Úmaintain_orderÚbool)rcrcsˆ ‡‡fdd„¡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. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").unique(maintain_order=True)) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 1 2 1 3 4 2 5 6 >>> func(df_pl) shape: (3, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 2 │ │ 3 ┆ 4 │ │ 5 ┆ 6 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1,3,5]] b: [[2,4,6]] csˆ |¡jˆdS)Nrb)rÚuniquer&©rcr!rrr)ùr*zExpr.unique..r+)r!rcrrfrreÆs2 ÿz Expr.uniquecsˆ ‡fdd„¡S)u Return absolute value of each element. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").abs()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 1 3 1 2 4 >>> func(df_pl) shape: (2, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 3 │ │ 2 ┆ 4 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1,2]] b: [[3,4]] csˆ |¡ ¡Sr)rr$r&r(rrr)(r*zExpr.abs..r+r(rr(rr$üs,zExpr.abscsˆ ‡fdd„¡S)u Return cumulative sum. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").cum_sum()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 1 2 1 2 6 2 5 10 3 10 16 4 15 22 >>> func(df_pl) shape: (5, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 2 │ │ 2 ┆ 6 │ │ 5 ┆ 10 │ │ 10 ┆ 16 │ │ 15 ┆ 22 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1,2,5,10,15]] b: [[2,6,10,16,22]] csˆ |¡ ¡Sr)rÚcum_sumr&r(rrr)[r*zExpr.cum_sum..r+r(rr(rrg*s1z Expr.cum_sumcsˆ ‡fdd„¡S)u& Returns the difference between each element and the previous one. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(a_diff=nw.col("a").diff()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a_diff 0 NaN 1 0.0 2 2.0 3 2.0 4 0.0 >>> func(df_pl) shape: (5, 1) ┌────────┠│ a_diff │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•â•â•â•¡ │ null │ │ 0 │ │ 2 │ │ 2 │ │ 0 │ └────────┘ >>> func(df_pa) pyarrow.Table a_diff: int64 ---- a_diff: [[null,0,2,2,0]] csˆ |¡ ¡Sr)rÚdiffr&r(rrr)•r*zExpr.diff..r+r(rr(rrh]s8z Expr.diff)Únrcsˆ ‡‡fdd„¡S)u Shift values by `n` positions. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(a_shift=nw.col("a").shift(n=1)) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a_shift 0 NaN 1 1.0 2 1.0 3 3.0 4 5.0 >>> func(df_pl) shape: (5, 1) ┌─────────┠│ a_shift │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•¡ │ null │ │ 1 │ │ 1 │ │ 3 │ │ 5 │ └─────────┘ >>> func(df_pa) pyarrow.Table a_shift: int64 ---- a_shift: [[null,1,1,3,5]] csˆ |¡ ˆ¡Sr)rÚshiftr&©rir!rrr)Ïr*zExpr.shift..r+©r!rirrkrrj—s8z Expr.shiftz Sequence[Any])ÚoldÚnewÚ return_dtypercsˆ ‡‡‡‡fdd„¡S)u¹ Replace old values with new values. This function must replace all non-null input values (else it raises an error), and the return dtype must be specified. Arguments: old: Sequence of old values to replace. new: Sequence of new values to replace. return_dtype: Return dtype. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns( ... b=nw.col("a").replace_strict( ... [0,1,2,3], ['zero', 'one', 'two', 'three'] ... return_dtype=nw.String, ... ) ... ) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 3 three 1 0 zero 2 1 one 3 2 two >>> func(df_pl) shape: (4, 2) ┌─────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ str │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ 3 ┆ three │ │ 0 ┆ zero │ │ 1 ┆ one │ │ 2 ┆ two │ └─────┴───────┘ >>> func(df_pa) pyarrow.Table a: int64 b: string ---- a: [[3,0,1,2]] b: [["three","zero","one","two"]] csˆ |¡jˆˆˆdS)N)ro)rÚreplace_strictr&©rnrmror!rrr)s ÿz%Expr.replace_strict..r+)r!rmrnrorrqrrpÑs>ÿzExpr.replace_strict©Ú descendingÚ nulls_last)rsrtrcsˆ ‡‡‡fdd„¡S)už Sort this column. Place null values first. Arguments: descending: Sort in descending order. nulls_last: Place null values last instead of first. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").sort()) >>> 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`: >>> func(df_pd) a 1 NaN 2 1.0 3 2.0 0 5.0 >>> func(df_pl) shape: (4, 1) ┌──────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•â•¡ │ null │ │ 1 │ │ 2 │ │ 5 │ └──────┘ >>> func(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]] csˆ |¡jˆˆdS)Nrr)rÚsortr&©rsrtr!rrr)dr*zExpr.sort..r+)r!rsrtrrvrrusNÿz Expr.sortÚboth)Ú lower_boundÚ upper_boundÚclosedrcsˆ ‡‡‡‡fdd„¡S)u5 Check 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). 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]}) >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").is_between(2, 4, "right")) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 False 1 False 2 True 3 True 4 False >>> func(df_pl) shape: (5, 1) ┌───────┠│ a │ │ --- │ │ bool │ â•žâ•â•â•â•â•â•â•â•¡ │ false │ │ false │ │ true │ │ true │ │ false │ └───────┘ >>> func(df_pa) pyarrow.Table a: bool ---- a: [[false,false,true,true,false]] csˆ |¡ ˆˆˆ¡Sr)rÚ is_betweenr&©rzrxr!ryrrr)¡r*z!Expr.is_between..r+)r!rxryrzrr|rr{hs8ÿzExpr.is_betweencs<tˆtƒr,tˆttfƒs,ˆ ‡‡fdd„¡Sd}t|ƒ‚dS)u Check if elements of this expression are present in the other iterable. Arguments: other: iterable Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(b=nw.col("a").is_in([1, 2])) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 1 True 1 2 True 2 9 False 3 10 False >>> func(df_pl) shape: (4, 2) ┌─────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ bool │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ 1 ┆ true │ │ 2 ┆ true │ │ 9 ┆ false │ │ 10 ┆ false │ └─────┴───────┘ >>> func(df_pa) pyarrow.Table a: int64 b: bool ---- a: [[1,2,9,10]] b: [[true,true,false,false]] csˆ |¡ ˆ¡Sr)rÚis_inr&r;rrr)Ør*zExpr.is_in..zyNarwhals `is_in` doesn't accept expressions as an argument, as opposed to Polars. You should provide an iterable instead.N)rrr.Úbytesr,ÚNotImplementedError)r!rÚmsgrr;rr}¤s3z Expr.is_in©Ú predicatesrcsˆ ‡‡fdd„¡S)uL Filters elements based on a condition, returning a new expression. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select( ... nw.col("a").filter(nw.col("a") > 4), ... nw.col("b").filter(nw.col("b") < 13), ... ) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 3 5 10 4 6 11 5 7 12 >>> func(df_pl) shape: (3, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 5 ┆ 10 │ │ 6 ┆ 11 │ │ 7 ┆ 12 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[5,6,7]] b: [[10,11,12]] cs"ˆ ˆ¡j‡fdd„tˆƒDƒŽS)Ncsg|]}tˆ|ƒ‘qSr©r)Ú.0Úpredr&rrÚ sz1Expr.filter....)rÚfilterr r&©r‚r!r&rr)s ÿzExpr.filter..r+©r!r‚rrˆrr‡Ýs0 ÿz Expr.filtercsˆ ‡fdd„¡S)u Returns a boolean Series indicating which values are null. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns( ... a_is_null=nw.col("a").is_null(), b_is_null=nw.col("b").is_null() ... ) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(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 >>> func(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 │ └──────┴─────┴───────────┴───────────┘ >>> func(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]] csˆ |¡ ¡Sr)rÚis_nullr&r(rrr)Vr*zExpr.is_null..r+r(rr(rrŠsCz Expr.is_nullcsˆ ‡fdd„¡S)u‡ Find elements where boolean expression is True. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").is_null().arg_true()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 1 1 2 2 >>> func(df_pl) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ u32 │ â•žâ•â•â•â•â•â•¡ │ 1 │ │ 2 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[1,2]] csˆ |¡ ¡Sr)rÚarg_truer&r(rrr)‚r*zExpr.arg_true..r+r(rr(rr‹Xs*z Expr.arg_true©Úvaluercsˆ ‡‡fdd„¡S)u§ Fill null values with given value. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(nw.col("a", "b").fill_null(0)) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 2.0 2.0 1 4.0 4.0 2 0.0 0.0 3 3.0 3.0 4 5.0 5.0 >>> func(df_pl) # nan != null for polars shape: (5, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ f64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 2 ┆ 2.0 │ │ 4 ┆ 4.0 │ │ 0 ┆ NaN │ │ 3 ┆ 3.0 │ │ 5 ┆ 5.0 │ └─────┴─────┘ >>> func(df_pa) # nan != null for pyarrow pyarrow.Table a: int64 b: double ---- a: [[2,4,0,3,5]] b: [[2,4,nan,3,5]] csˆ |¡ ˆ¡Sr)rÚ fill_nullr&©r!rrrr)Ár*z Expr.fill_null..r+rrrrrŽ„s=zExpr.fill_nullcsˆ ‡fdd„¡S)u  Remove missing values. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").drop_nulls()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 2.0 1 4.0 3 3.0 5 5.0 >>> func(df_pl) # nan != null for polars shape: (5, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 2.0 │ │ 4.0 │ │ NaN │ │ 3.0 │ │ 5.0 │ └─────┘ >>> func(df_pa) # nan != null for pyarrow pyarrow.Table a: double ---- a: [[2,4,nan,3,5]] csˆ |¡ ¡Sr)rÚ drop_nullsr&r(rrr)÷r*z!Expr.drop_nulls..r+r(rr(rrÄs3zExpr.drop_nullsN©ÚfractionÚwith_replacementÚseedú int | Nonez float | None)r!rir’r“r”rcsˆ ‡‡‡‡‡fdd„¡S)ut 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. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").sample(fraction=1.0, with_replacement=True)) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) # doctest: +SKIP a 2 3 0 1 2 3 >>> func(df_pl) # doctest: +SKIP shape: (3, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 3 │ │ 3 │ └─────┘ >>> func(df_pa) # doctest: +SKIP pyarrow.Table a: int64 ---- a: [[1,3,3]] csˆ |¡jˆˆˆˆdS)Nr‘)rÚsampler&©r’rir”r!r“rrr)3s ÿzExpr.sample..r+)r!rir’r“r”rr—rr–ùs9ÿz Expr.sampleústr | Iterable[str])Úkeysrcsˆ ‡‡fdd„¡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`. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(a_min_per_group=nw.col("a").min().over("b")) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b a_min_per_group 0 1 1 1 1 2 1 1 2 3 2 3 >>> func(df_pl) shape: (3, 3) ┌─────┬─────┬─────────────────┠│ a ┆ b ┆ a_min_per_group │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 1 ┆ 1 ┆ 1 │ │ 2 ┆ 1 ┆ 1 │ │ 3 ┆ 2 ┆ 3 │ └─────┴─────┴─────────────────┘ >>> func(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]] csˆ |¡ tˆƒ¡Sr)rÚoverr r&©r™r!rrr)mr*zExpr.over..r+)r!r™rr›rrš8s5z Expr.overcsˆ ‡fdd„¡S)u" Return a boolean mask indicating duplicated values. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.all().is_duplicated()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 True True 1 False True 2 False False 3 True False >>> func(df_pl) shape: (4, 2) ┌───────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ true ┆ true │ │ false ┆ true │ │ false ┆ false │ │ true ┆ false │ └───────┴───────┘ >>> func(df_pa) pyarrow.Table a: bool b: bool ---- a: [[true,false,false,true]] b: [[true,true,false,false]] csˆ |¡ ¡Sr)rÚ is_duplicatedr&r(rrr)Ÿr*z$Expr.is_duplicated..r+r(rr(rrœos0zExpr.is_duplicatedcsˆ ‡fdd„¡S)u Return a boolean mask indicating unique values. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.all().is_unique()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 False False 1 True False 2 True True 3 False True >>> func(df_pl) shape: (4, 2) ┌───────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ false ┆ false │ │ true ┆ false │ │ true ┆ true │ │ false ┆ true │ └───────┴───────┘ >>> func(df_pa) pyarrow.Table a: bool b: bool ---- a: [[false,true,true,false]] b: [[false,false,true,true]] csˆ |¡ ¡Sr)rÚ is_uniquer&r(rrr)Ñr*z Expr.is_unique..r+r(rr(rr¡s0zExpr.is_uniquecsˆ ‡fdd„¡S)uv Count null values. Notes: pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.all().null_count()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 1 2 >>> func(df_pl) shape: (1, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 2 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1]] b: [[2]] csˆ |¡ ¡Sr)rÚ null_countr&r(rrr)r*z!Expr.null_count..r+r(rr(rržÓs.zExpr.null_countcsˆ ‡fdd„¡S)u> Return a boolean mask indicating the first occurrence of each distinct value. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.all().is_first_distinct()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 True True 1 True False 2 True True 3 False True >>> func(df_pl) shape: (4, 2) ┌───────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ true ┆ true │ │ true ┆ false │ │ true ┆ true │ │ false ┆ true │ └───────┴───────┘ >>> func(df_pa) pyarrow.Table a: bool b: bool ---- a: [[true,true,true,false]] b: [[true,false,true,true]] csˆ |¡ ¡Sr)rÚis_first_distinctr&r(rrr)3r*z(Expr.is_first_distinct..r+r(rr(rrŸs0zExpr.is_first_distinctcsˆ ‡fdd„¡S)u3Return a boolean mask indicating the last occurrence of each distinct value. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.all().is_last_distinct()) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 False False 1 True True 2 True True 3 True True >>> func(df_pl) shape: (4, 2) ┌───────┬───────┠│ a ┆ b │ │ --- ┆ --- │ │ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ false ┆ false │ │ true ┆ true │ │ true ┆ true │ │ true ┆ true │ └───────┴───────┘ >>> func(df_pa) pyarrow.Table a: bool b: bool ---- a: [[false,true,true,true]] b: [[false,true,true,true]] csˆ |¡ ¡Sr)rÚis_last_distinctr&r(rrr)dr*z'Expr.is_last_distinct..r+r(rr(rr 5s/zExpr.is_last_distinctÚfloatz=Literal[('nearest', 'higher', 'lower', 'midpoint', 'linear')])ÚquantileÚ interpolationrcsˆ ‡‡‡fdd„¡S)uAGet quantile value. 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. Arguments: quantile: Quantile between 0.0 and 1.0. interpolation: Interpolation method. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a", "b").quantile(0.5, interpolation="linear")) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 24.5 74.5 >>> func(df_pl) shape: (1, 2) ┌──────┬──────┠│ a ┆ b │ │ --- ┆ --- │ │ f64 ┆ f64 │ â•žâ•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ 24.5 ┆ 74.5 │ └──────┴──────┘ >>> func(df_pa) pyarrow.Table a: double b: double ---- a: [[24.5]] b: [[74.5]] csˆ |¡ ˆˆ¡Sr)rr¢r&©r£r¢r!rrr)žr*zExpr.quantile..r+)r!r¢r£rr¤rr¢fs7ÿz Expr.quantileé csˆ ‡‡fdd„¡S)uê Get the first `n` rows. Arguments: n: Number of rows to return. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").head(3)) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 0 1 1 2 2 >>> func(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 0 │ │ 1 │ │ 2 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[0,1,2]] csˆ |¡ ˆ¡Sr)rÚheadr&rkrrr)Ðr*zExpr.head..r+rlrrkrr¦¡s/z Expr.headcsˆ ‡‡fdd„¡S)uè Get the last `n` rows. Arguments: n: Number of rows to return. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").tail(3)) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 7 7 8 8 9 9 >>> func(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 7 │ │ 8 │ │ 9 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[7,8,9]] csˆ |¡ ˆ¡Sr)rÚtailr&rkrrr)r*zExpr.tail..r+rlrrkrr§Òs/z Expr.tailr)Údecimalsrcsˆ ‡‡fdd„¡S)uË Round underlying floating point data by `decimals` digits. Arguments: decimals: Number of decimals to round by. Notes: For values exactly halfway between rounded decimal values pandas 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").round(1)) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 1.1 1 2.6 2 3.9 >>> func(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 1.1 │ │ 2.6 │ │ 3.9 │ └─────┘ >>> func(df_pa) pyarrow.Table a: double ---- a: [[1.1,2.6,3.9]] csˆ |¡ ˆ¡Sr)rÚroundr&©r¨r!rrr);r*zExpr.round..r+)r!r¨rrªrr©s8z Expr.roundcsˆ ‡fdd„¡S)uö Return the number of elements in the column. Null values count towards the total. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... 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"), ... ) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a1 a2 0 2 1 >>> func(df_pl) shape: (1, 2) ┌─────┬─────┠│ a1 ┆ a2 │ │ --- ┆ --- │ │ u32 ┆ u32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 2 ┆ 1 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a1: int64 a2: int64 ---- a1: [[2]] a2: [[1]] csˆ |¡ ¡Sr)rÚlenr&r(rrr)lr*zExpr.len..r+r(rr(rr«=s/zExpr.len)r!riÚoffsetrcsˆ ‡‡‡fdd„¡S)uS Take every nth value in the Series and return as new Series. Arguments: n: Gather every *n*-th row. offset: Starting index. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").gather_every(n=2, offset=1)) We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 1 2 3 4 >>> func(df_pl) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 4 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[2,4]] csˆ |¡jˆˆdS)N)rir¬)rÚ gather_everyr&©rir¬r!rrr)žr*z#Expr.gather_every..r+)r!rir¬rr®rr­ns/ÿzExpr.gather_everyz Any | None)rxryrcsˆ ‡‡‡fdd„¡S)uÊ Clip values in the Series. Arguments: lower_bound: Lower bound value. upper_bound: Upper bound value. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func_lower(df): ... return df.select(nw.col("s").clip(2)) 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: >>> @nw.narwhalify ... def func_upper(df): ... return df.select(nw.col("s").clip(upper_bound=2)) 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("s").clip(-1, 3)) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) s 0 -1 1 1 2 -1 3 3 4 -1 5 3 >>> func(df_pl) shape: (6, 1) ┌─────┠│ s │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ -1 │ │ 1 │ │ -1 │ │ 3 │ │ -1 │ │ 3 │ └─────┘ >>> func(df_pa) pyarrow.Table s: int64 ---- s: [[-1,1,-1,3,-1,3]] csˆ |¡ ˆˆ¡Sr)rÚclipr&©rxr!ryrrr)! r*zExpr.clip..r+)r!rxryrr°rr¯£s~z Expr.clip©r!rcsˆ ‡fdd„¡S)u´Compute the most occurring value(s). Can return multiple values. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").mode()).sort("a") We can then pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 1 >>> func(df_pl) shape: (1, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 1 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[1]] csˆ |¡ ¡Sr)rÚmoder&r(rrr)R r*zExpr.mode..r+r(rr(rr²# s/z Expr.modezExprStringNamespace[Self]cCst|ƒSr)ÚExprStringNamespacer(rrrr.T szExpr.strzExprDateTimeNamespace[Self]cCst|ƒSr)ÚExprDateTimeNamespacer(rrrÚdtX szExpr.dtzExprCatNamespace[Self]cCst|ƒSr)ÚExprCatNamespacer(rrrÚcat\ szExpr.catzExprNameNamespace[Self]cCst|ƒSr)ÚExprNameNamespacer(rrrr/` sz Expr.name)rw)N)r¥)r¥)r)r)NN)LÚ__name__Ú __module__Ú __qualname__r"r-r0r5r7r:r=r>r?r@rArBrCrDrErFrGrHrIrJrKrLrMrNrOrPrQrRrSrTrUrVrWr\r%r^r_r`rarer$rgrhrjrprur{r}r‡rŠr‹rŽrr–ršrœrržrŸr r¢r¦r§r©r«r­r¯r²Úpropertyr.rµr·r/rrrrr sª/08+++0+++++6.3::DTÿ<96E,@7þú?722021;11:17ý1ÚT)Úboundc@s.eZdZddddœdd„Zdddœdd „Zd S) r¶r r½r©r!rrcCs ||_dSr©Ú_expr©r!rrrrr"i szExprCatNamespace.__init__r±csˆj ‡fdd„¡S)u Get unique categories from column. Examples: Let's create some dataframes: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> 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': >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("fruits").cat.get_categories()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) fruits 0 apple 1 mango >>> func(df_pl) shape: (2, 1) ┌────────┠│ fruits │ │ --- │ │ str │ â•žâ•â•â•â•â•â•â•â•â•¡ │ apple │ │ mango │ └────────┘ csˆj |¡j ¡Sr)rÁrr·Úget_categoriesr&r(rrr)“ r*z1ExprCatNamespace.get_categories..©rÁr,r(rr(rrÃl s& ÿzExprCatNamespace.get_categoriesN)r¹rºr»r"rÃrrrrr¶h sr¶c@s,eZdZddddœdd„Zdddœdd „Zd d d œd d ddddœdd„Zd dœdd d dddœdd„Zd6ddddœdd„Zdd ddœdd„Zdd ddœd d!„Z d dœdd ddd"œd#d$„Z d7ddd%dd&œd'd(„Z d8dddd*œd+d,„Z d9dddd*œd-d.„Z d:dddd/œd0d1„Zdddœd2d3„Zdddœd4d5„ZdS);r³r r½rr¿cCs ||_dSrrÀrÂrrrr"˜ szExprStringNamespace.__init__r±csˆj ‡fdd„¡S)uµ Return the length of each string as the number of characters. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = {"words": ["foo", "Café", "345", "æ±äº¬", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(words_len=nw.col("words").str.len_chars()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) words words_len 0 foo 3.0 1 Café 4.0 2 345 3.0 3 æ±äº¬ 2.0 4 None NaN >>> func(df_pl) shape: (5, 2) ┌───────┬───────────┠│ words ┆ words_len │ │ --- ┆ --- │ │ str ┆ u32 │ â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ foo ┆ 3 │ │ Café ┆ 4 │ │ 345 ┆ 3 │ │ æ±äº¬ ┆ 2 │ │ null ┆ null │ └───────┴───────────┘ csˆj |¡j ¡Sr)rÁrr.Ú len_charsr&r(rrr)Å r*z/ExprStringNamespace.len_chars..rÄr(rr(rrÅ› s*zExprStringNamespace.len_charsFrX©Úliteralrir.rdr[)ÚpatternrrÇrircsˆj ‡‡‡‡‡fdd„¡S)a{ Replace 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = {"foo": ["123abc", "abc abc123"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... df = df.with_columns(replaced=nw.col("foo").str.replace("abc", "")) ... return df.to_dict(as_series=False) We can then pass either pandas or Polars to `func`: >>> func(df_pd) {'foo': ['123abc', 'abc abc123'], 'replaced': ['123', ' abc123']} >>> func(df_pl) {'foo': ['123abc', 'abc abc123'], 'replaced': ['123', ' abc123']} csˆj |¡jjˆˆˆˆdS)NrÆ)rÁrr.Úreplacer&©rÇrirÈr!rrrr)ì s ÿz-ExprStringNamespace.replace..rÄ)r!rÈrrÇrirrÊrrÉÇ s$ÿzExprStringNamespace.replace©rÇ)r!rÈrrÇrcsˆj ‡‡‡‡fdd„¡S)aJ 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = {"foo": ["123abc", "abc abc123"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... df = df.with_columns(replaced=nw.col("foo").str.replace_all("abc", "")) ... return df.to_dict(as_series=False) We can then pass either pandas or Polars to `func`: >>> func(df_pd) {'foo': ['123abc', 'abc abc123'], 'replaced': ['123', ' 123']} >>> func(df_pl) {'foo': ['123abc', 'abc abc123'], 'replaced': ['123', ' 123']} csˆj |¡jjˆˆˆdS©NrË)rÁrr.Ú replace_allr&©rÇrÈr!rrrr) sÿz1ExprStringNamespace.replace_all..rÄ)r!rÈrrÇrrÎrrÍñ s!ÿzExprStringNamespace.replace_allNú str | None)r!Ú charactersrcsˆj ‡‡fdd„¡S)ac Remove 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = {"fruits": ["apple", "\nmango"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... 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`: >>> func(df_pd) {'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']} >>> func(df_pl) {'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']} csˆj |¡j ˆ¡Sr)rÁrr.Ú strip_charsr&©rÐr!rrr)7 r*z1ExprStringNamespace.strip_chars..rÄ)r!rÐrrÒrrÑ s ÿzExprStringNamespace.strip_chars©r!Úprefixrcsˆj ‡‡fdd„¡S)uf Check if string values start with a substring. Arguments: prefix: prefix substring Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = {"fruits": ["apple", "mango", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(has_prefix=nw.col("fruits").str.starts_with("app")) We can then pass either pandas or Polars to `func`: >>> func(df_pd) fruits has_prefix 0 apple True 1 mango False 2 None None >>> func(df_pl) shape: (3, 2) ┌────────┬────────────┠│ fruits ┆ has_prefix │ │ --- ┆ --- │ │ str ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ apple ┆ true │ │ mango ┆ false │ │ null ┆ null │ └────────┴────────────┘ csˆj |¡j ˆ¡Sr)rÁrr.Ú starts_withr&©rÔr!rrr)d r*z1ExprStringNamespace.starts_with..rÄ©r!rÔrrÖrrÕ: s) ÿzExprStringNamespace.starts_with©r!Úsuffixrcsˆj ‡‡fdd„¡S)ub Check if string values end with a substring. Arguments: suffix: suffix substring Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = {"fruits": ["apple", "mango", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(has_suffix=nw.col("fruits").str.ends_with("ngo")) We can then pass either pandas or Polars to `func`: >>> func(df_pd) fruits has_suffix 0 apple False 1 mango True 2 None None >>> func(df_pl) shape: (3, 2) ┌────────┬────────────┠│ fruits ┆ has_suffix │ │ --- ┆ --- │ │ str ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ apple ┆ false │ │ mango ┆ true │ │ null ┆ null │ └────────┴────────────┘ csˆj |¡j ˆ¡Sr)rÁrr.Ú ends_withr&©r!rÙrrr)‘ r*z/ExprStringNamespace.ends_with..rÄrÛrrÛrrÚg s) ÿzExprStringNamespace.ends_with)r!rÈrÇrcsˆj ‡‡‡fdd„¡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. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... 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 ... ), ... ) We can then pass either pandas or Polars to `func`: >>> func(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 >>> func(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 │ └───────────────────┴───────────────┴────────────────────────┴───────────────┘ csˆj |¡jjˆˆdSrÌ)rÁrr.Úcontainsr&©rÇrÈr!rrr)É r*z.ExprStringNamespace.contains..rÄ)r!rÈrÇrrÝrrÜ” s4ÿzExprStringNamespace.containsr•)r!r¬Úlengthrcsˆj ‡‡‡fdd„¡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. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = {"s": ["pear", None, "papaya", "dragonfruit"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(s_sliced=nw.col("s").str.slice(4, length=3)) We can then pass either pandas or Polars to `func`: >>> func(df_pd) # doctest: +NORMALIZE_WHITESPACE s s_sliced 0 pear 1 None None 2 papaya ya 3 dragonfruit onf >>> func(df_pl) shape: (4, 2) ┌─────────────┬──────────┠│ s ┆ s_sliced │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ pear ┆ │ │ null ┆ null │ │ papaya ┆ ya │ │ dragonfruit ┆ onf │ └─────────────┴──────────┘ Using negative indexes: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(s_sliced=nw.col("s").str.slice(-3)) >>> func(df_pd) s s_sliced 0 pear ear 1 None None 2 papaya aya 3 dragonfruit uit >>> func(df_pl) shape: (4, 2) ┌─────────────┬──────────┠│ s ┆ s_sliced │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ pear ┆ ear │ │ null ┆ null │ │ papaya ┆ aya │ │ dragonfruit ┆ uit │ └─────────────┴──────────┘ csˆj |¡jjˆˆdS)N)r¬rÞ©rÁrr.Úslicer&©rÞr¬r!rrr) r*z+ExprStringNamespace.slice..rÄ)r!r¬rÞrrárràÌ sGÿzExprStringNamespace.sliceé)r!rircsˆj ‡‡fdd„¡S)u¯ Take the first n elements of each string. Arguments: n: Number of elements to take. Negative indexing is **not** supported. 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 >>> data = {"lyrics": ["Atatata", "taata", "taatatata", "zukkyun"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(lyrics_head=nw.col("lyrics").str.head()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) lyrics lyrics_head 0 Atatata Atata 1 taata taata 2 taatatata taata 3 zukkyun zukky >>> func(df_pl) shape: (4, 2) ┌───────────┬─────────────┠│ lyrics ┆ lyrics_head │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ Atatata ┆ Atata │ │ taata ┆ taata │ │ taatatata ┆ taata │ │ zukkyun ┆ zukky │ └───────────┴─────────────┘ csˆj |¡j dˆ¡S)Nrrßr&rkrrr)E r*z*ExprStringNamespace.head..rÄrlrrkrr¦ s.zExprStringNamespace.headcsˆj ‡‡fdd„¡S)u® Take the last n elements of each string. Arguments: n: Number of elements to take. Negative indexing is **not** supported. 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 >>> data = {"lyrics": ["Atatata", "taata", "taatatata", "zukkyun"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(lyrics_tail=nw.col("lyrics").str.tail()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) lyrics lyrics_tail 0 Atatata atata 1 taata taata 2 taatatata atata 3 zukkyun kkyun >>> func(df_pl) shape: (4, 2) ┌───────────┬─────────────┠│ lyrics ┆ lyrics_tail │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ Atatata ┆ atata │ │ taata ┆ taata │ │ taatatata ┆ atata │ │ zukkyun ┆ kkyun │ └───────────┴─────────────┘ csˆj |¡j ˆ ¡Srrßr&rkrrr)u r*z*ExprStringNamespace.tail..rÄrlrrkrr§G s.zExprStringNamespace.tail©r!Úformatrcsˆj ‡‡fdd„¡S)uI Convert to Datetime dtype. 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. 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").str.to_datetime(format="%Y-%m-%d")) We can then pass any supported library such as pandas, Polars, or PyArrow: >>> func(df_pd) a 0 2020-01-01 1 2020-01-02 >>> func(df_pl) shape: (2, 1) ┌─────────────────────┠│ a │ │ --- │ │ datetime[μs] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2020-01-01 00:00:00 │ │ 2020-01-02 00:00:00 │ └─────────────────────┘ >>> func(df_pa) pyarrow.Table a: timestamp[us] ---- a: [[2020-01-01 00:00:00.000000,2020-01-02 00:00:00.000000]] csˆj |¡jjˆdS)N)rä)rÁrr.Ú to_datetimer&©rär!rrr)° r*z1ExprStringNamespace.to_datetime..rÄ©r!rärrærråw s8 ÿzExprStringNamespace.to_datetimecsˆj ‡fdd„¡S)u' Transform string to uppercase variant. 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 >>> data = {"fruits": ["apple", "mango", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(upper_col=nw.col("fruits").str.to_uppercase()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) fruits upper_col 0 apple APPLE 1 mango MANGO 2 None None >>> func(df_pl) shape: (3, 2) ┌────────┬───────────┠│ fruits ┆ upper_col │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ apple ┆ APPLE │ │ mango ┆ MANGO │ │ null ┆ null │ └────────┴───────────┘ csˆj |¡j ¡Sr)rÁrr.Ú to_uppercaser&r(rrr)ß r*z2ExprStringNamespace.to_uppercase..rÄr(rr(rrè³ s,z ExprStringNamespace.to_uppercasecsˆj ‡fdd„¡S)u  Transform string to lowercase variant. Examples: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> data = {"fruits": ["APPLE", "MANGO", None]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(lower_col=nw.col("fruits").str.to_lowercase()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) fruits lower_col 0 APPLE apple 1 MANGO mango 2 None None >>> func(df_pl) shape: (3, 2) ┌────────┬───────────┠│ fruits ┆ lower_col │ │ --- ┆ --- │ │ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ APPLE ┆ apple │ │ MANGO ┆ mango │ │ null ┆ null │ └────────┴───────────┘ csˆj |¡j ¡Sr)rÁrr.Ú to_lowercaser&r(rrr) r*z2ExprStringNamespace.to_lowercase..rÄr(rr(rréá s&z ExprStringNamespace.to_lowercase)N)N)râ)râ)N)r¹rºr»r"rÅrÉrÍrÑrÕrÚrÜràr¦r§rårèrérrrrr³— s -ÿ*'"--8K00<.r³c@sheZdZddddœdd„Zdddœdd „Zdddœd d „Zdddœd d „Zdddœdd„Zdddœdd„Zdddœdd„Z dddœdd„Z dddœdd„Z dddœdd„Z dddœdd„Z dddœdd„Zdddœdd„Zdddœd d!„Zdddœd"d#„Zdddœd$d%„Zdddœd&d'„Zdd(dd)œd*d+„Zdd,dd-œd.d/„Zdd(dd-œd0d1„Zd8dd3dd4œd5d6„Zd7S)9r´r r½rr¿cCs ||_dSrrÀrÂrrrr" szExprDateTimeNamespace.__init__r±csˆj ‡fdd„¡S)u  Extract the date from underlying DateTime representation. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").dt.date()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a 0 2012-01-07 1 2023-03-10 >>> func(df_pl) # docetst shape: (2, 1) ┌────────────┠│ a │ │ --- │ │ date │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2012-01-07 │ │ 2023-03-10 │ └────────────┘ csˆj |¡j ¡Sr)rÁrrµÚdater&r(rrr)6 r*z,ExprDateTimeNamespace.date..rÄr(rr(rrê s(zExprDateTimeNamespace.datecsˆj ‡fdd„¡S)u© Extract year from underlying DateTime representation. Returns the year number in the calendar date. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(nw.col("datetime").dt.year().alias("year")) We can then pass either pandas or Polars to `func`: >>> func(df_pd) datetime year 0 1978-06-01 1978 1 2024-12-13 2024 2 2065-01-01 2065 >>> func(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 │ └─────────────────────┴──────┘ csˆj |¡j ¡Sr)rÁrrµÚyearr&r(rrr)f r*z,ExprDateTimeNamespace.year..rÄr(rr(rrë8 s.zExprDateTimeNamespace.yearcsˆj ‡fdd„¡S)uá Extract month from underlying DateTime representation. Returns the month number starting from 1. The return value ranges from 1 to 12. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns( ... nw.col("datetime").dt.year().alias("year"), ... nw.col("datetime").dt.month().alias("month"), ... ) We can then pass either pandas or Polars to `func`: >>> func(df_pd) datetime year month 0 1978-06-01 1978 6 1 2024-12-13 2024 12 2 2065-01-01 2065 1 >>> func(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 │ └─────────────────────┴──────┴───────┘ csˆj |¡j ¡Sr)rÁrrµÚmonthr&r(rrr)™ r*z-ExprDateTimeNamespace.month..rÄr(rr(rrìh s1zExprDateTimeNamespace.monthcsˆj ‡fdd„¡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.) Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... 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"), ... ) We can then pass either pandas or Polars to `func`: >>> func(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 >>> func(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 │ └─────────────────────┴──────┴───────┴─────┘ csˆj |¡j ¡Sr)rÁrrµÚdayr&r(rrr)Í r*z+ExprDateTimeNamespace.day..rÄr(rr(rrí› s2zExprDateTimeNamespace.daycsˆj ‡fdd„¡S)uÏ Extract hour from underlying DateTime representation. Returns the hour number from 0 to 23. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(nw.col("datetime").dt.hour().alias("hour")) We can then pass either pandas or Polars to `func`: >>> func(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 >>> func(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 │ └─────────────────────┴──────┘ csˆj |¡j ¡Sr)rÁrrµÚhourr&r(rrr)ý r*z,ExprDateTimeNamespace.hour..rÄr(rr(rrîÏ s.zExprDateTimeNamespace.hourcsˆj ‡fdd„¡S)u  Extract minutes from underlying DateTime representation. Returns the minute number from 0 to 59. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns( ... nw.col("datetime").dt.hour().alias("hour"), ... nw.col("datetime").dt.minute().alias("minute"), ... ) We can then pass either pandas or Polars to `func`: >>> func(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 >>> func(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 │ └─────────────────────┴──────┴────────┘ csˆj |¡j ¡Sr)rÁrrµÚminuter&r(rrr)0 r*z.ExprDateTimeNamespace.minute..rÄr(rr(rrïÿ s1zExprDateTimeNamespace.minutecsˆj ‡fdd„¡S)uÞ Extract seconds from underlying DateTime representation. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... 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"), ... ) We can then pass either pandas or Polars to `func`: >>> func(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 >>> func(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 │ └─────────────────────┴──────┴────────┴────────┘ csˆj |¡j ¡Sr)rÁrrµÚsecondr&r(rrr)b r*z.ExprDateTimeNamespace.second..rÄr(rr(rrð2 s0zExprDateTimeNamespace.secondcsˆj ‡fdd„¡S)u¥ Extract milliseconds from underlying DateTime representation. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... 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"), ... ) We can then pass either pandas or Polars to `func`: >>> func(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 >>> func(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 │ └─────────────────────────┴──────┴────────┴────────┴─────────────┘ csˆj |¡j ¡Sr)rÁrrµÚ millisecondr&r(rrr)• r*z3ExprDateTimeNamespace.millisecond..rÄr(rr(rrñd s1z!ExprDateTimeNamespace.millisecondcsˆj ‡fdd„¡S)u¥ Extract microseconds from underlying DateTime representation. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... 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"), ... ) We can then pass either pandas or Polars to `func`: >>> func(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 >>> func(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 │ └─────────────────────────┴──────┴────────┴────────┴─────────────┘ csˆj |¡j ¡Sr)rÁrrµÚ microsecondr&r(rrr)È r*z3ExprDateTimeNamespace.microsecond..rÄr(rr(rrò— s1z!ExprDateTimeNamespace.microsecondcsˆj ‡fdd„¡S)uŽ Extract Nanoseconds from underlying DateTime representation Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... 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"), ... ) We can then pass either pandas or Polars to `func`: >>> func(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 >>> func(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 │ └─────────────────────────┴──────┴────────┴────────┴────────────┘ csˆj |¡j ¡Sr)rÁrrµÚ nanosecondr&r(rrr)û r*z2ExprDateTimeNamespace.nanosecond..rÄr(rr(rróÊ s1z ExprDateTimeNamespace.nanosecondcsˆj ‡fdd„¡S)uò Get ordinal day. Examples: >>> import pandas as pd >>> import polars as pl >>> from datetime import datetime >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(a_ordinal_day=nw.col("a").dt.ordinal_day()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a a_ordinal_day 0 2020-01-01 1 1 2020-08-03 216 >>> func(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 │ └─────────────────────┴───────────────┘ csˆj |¡j ¡Sr)rÁrrµÚ ordinal_dayr&r(rrr)!r*z3ExprDateTimeNamespace.ordinal_day..rÄr(rr(rrôý s$z!ExprDateTimeNamespace.ordinal_daycsˆj ‡fdd„¡S)uÑ Get total minutes. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(a_total_minutes=nw.col("a").dt.total_minutes()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a a_total_minutes 0 0 days 00:10:00 10 1 0 days 00:20:40 20 >>> func(df_pl) shape: (2, 2) ┌──────────────┬─────────────────┠│ a ┆ a_total_minutes │ │ --- ┆ --- │ │ duration[μs] ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 10m ┆ 10 │ │ 20m 40s ┆ 20 │ └──────────────┴─────────────────┘ csˆj |¡j ¡Sr)rÁrrµÚ total_minutesr&r(rrr)Lr*z5ExprDateTimeNamespace.total_minutes..rÄr(rr(rrõ#s)z#ExprDateTimeNamespace.total_minutescsˆj ‡fdd„¡S)uë Get total seconds. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(a_total_seconds=nw.col("a").dt.total_seconds()) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a a_total_seconds 0 0 days 00:00:10 10 1 0 days 00:00:20.040000 20 >>> func(df_pl) shape: (2, 2) ┌──────────────┬─────────────────┠│ a ┆ a_total_seconds │ │ --- ┆ --- │ │ duration[μs] ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 10s ┆ 10 │ │ 20s 40ms ┆ 20 │ └──────────────┴─────────────────┘ csˆj |¡j ¡Sr)rÁrrµÚ total_secondsr&r(rrr)wr*z5ExprDateTimeNamespace.total_seconds..rÄr(rr(rröNs)z#ExprDateTimeNamespace.total_secondscsˆj ‡fdd„¡S)uú Get total milliseconds. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns( ... a_total_milliseconds=nw.col("a").dt.total_milliseconds() ... ) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a a_total_milliseconds 0 0 days 00:00:00.010000 10 1 0 days 00:00:00.020040 20 >>> func(df_pl) shape: (2, 2) ┌──────────────┬──────────────────────┠│ a ┆ a_total_milliseconds │ │ --- ┆ --- │ │ duration[μs] ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 10ms ┆ 10 │ │ 20040µs ┆ 20 │ └──────────────┴──────────────────────┘ csˆj |¡j ¡Sr)rÁrrµÚtotal_millisecondsr&r(rrr)ªr*z:ExprDateTimeNamespace.total_milliseconds..rÄr(rr(rr÷ys0 ÿz(ExprDateTimeNamespace.total_millisecondscsˆj ‡fdd„¡S)uû Get total microseconds. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns( ... a_total_microseconds=nw.col("a").dt.total_microseconds() ... ) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a a_total_microseconds 0 0 days 00:00:00.000010 10 1 0 days 00:00:00.001200 1200 >>> func(df_pl) shape: (2, 2) ┌──────────────┬──────────────────────┠│ a ┆ a_total_microseconds │ │ --- ┆ --- │ │ duration[μs] ┆ i64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 10µs ┆ 10 │ │ 1200µs ┆ 1200 │ └──────────────┴──────────────────────┘ csˆj |¡j ¡Sr)rÁrrµÚtotal_microsecondsr&r(rrr)Þr*z:ExprDateTimeNamespace.total_microseconds..rÄr(rr(rrø­s0 ÿz(ExprDateTimeNamespace.total_microsecondscsˆj ‡fdd„¡S)uJ Get total nanoseconds. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns( ... a_diff_total_nanoseconds=nw.col("a").diff().dt.total_nanoseconds() ... ) We can then pass either pandas or Polars to `func`: >>> func(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 >>> func(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 │ └───────────────────────────────┴──────────────────────────┘ csˆj |¡j ¡Sr)rÁrrµÚtotal_nanosecondsr&r(rrr)r*z9ExprDateTimeNamespace.total_nanoseconds..rÄr(rr(rrùás- ÿz'ExprDateTimeNamespace.total_nanosecondsr.rãcsˆj ‡‡fdd„¡S)uh Convert a Date/Time/Datetime column into a String column with the given format. 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").dt.to_string("%Y/%m/%d %H:%M:%S")) We can then pass either pandas or Polars to `func`: >>> func(df_pd) a 0 2020/03/01 00:00:00 1 2020/04/01 00:00:00 2 2020/05/01 00:00:00 >>> func(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 │ └─────────────────────┘ csˆj |¡j ˆ¡Sr)rÁrrµÚ to_stringr&rærrr)]r*z1ExprDateTimeNamespace.to_string..rÄrçrrærrúsJ ÿzExprDateTimeNamespace.to_stringrÏ)r!Ú time_zonercsˆj ‡‡fdd„¡S)u Replace time zone. Arguments: time_zone: Target time zone. Examples: >>> from datetime import datetime, timezone >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").dt.replace_time_zone("Asia/Kathmandu")) We can then pass pandas / PyArrow / Polars / any other supported library: >>> func(df_pd) a 0 2024-01-01 00:00:00+05:45 1 2024-01-02 00:00:00+05:45 >>> func(df_pl) shape: (2, 1) ┌──────────────────────────────┠│ a │ │ --- │ │ datetime[μs, Asia/Kathmandu] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2024-01-01 00:00:00 +0545 │ │ 2024-01-02 00:00:00 +0545 │ └──────────────────────────────┘ >>> func(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]] csˆj |¡j ˆ¡Sr)rÁrrµÚreplace_time_zoner&©r!rûrrr)”r*z9ExprDateTimeNamespace.replace_time_zone..rÄrýrrýrrü`s3 ÿz'ExprDateTimeNamespace.replace_time_zonecs*ˆdkrd}t|ƒ‚ˆj ‡‡fdd„¡S)u  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. Examples: >>> from datetime import datetime, timezone >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a").dt.convert_time_zone("Asia/Kathmandu")) We can then pass pandas / PyArrow / Polars / any other supported library: >>> func(df_pd) a 0 2024-01-01 05:45:00+05:45 1 2024-01-02 05:45:00+05:45 >>> func(df_pl) shape: (2, 1) ┌──────────────────────────────┠│ a │ │ --- │ │ datetime[μs, Asia/Kathmandu] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2024-01-01 05:45:00 +0545 │ │ 2024-01-02 05:45:00 +0545 │ └──────────────────────────────┘ >>> func(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]] Nz…Target `time_zone` cannot be `None` in `convert_time_zone`. Please use `replace_time_zone(None)` if you want to remove the time zone.csˆj |¡j ˆ¡Sr)rÁrrµÚconvert_time_zoner&rýrrr)Ñr*z9ExprDateTimeNamespace.convert_time_zone..)Ú TypeErrorrÁr,)r!rûr€rrýrrþ—s 6 ÿz'ExprDateTimeNamespace.convert_time_zoneÚuszLiteral[('ns', 'us', 'ms')])r!Ú time_unitrcs2ˆdkrdˆ›d}t|ƒ‚ˆj ‡‡fdd„¡S)u× Return a timestamp in the given time unit. Arguments: time_unit: {'ns', 'us', 'ms'} Time unit. Examples: >>> from datetime import date >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns( ... nw.col("date").dt.timestamp().alias("timestamp_us"), ... nw.col("date").dt.timestamp("ms").alias("timestamp_ms"), ... ) We can then pass pandas / PyArrow / Polars / any other supported library: >>> func(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 >>> func(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 │ └────────────┴─────────────────┴──────────────┘ >>> func(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]] >rÚnsÚmsz=invalid `time_unit` Expected one of {'ns', 'us', 'ms'}, got Ú.csˆj |¡j ˆ¡Sr)rÁrrµÚ timestampr&©r!rrrr)r*z1ExprDateTimeNamespace.timestamp..)Ú ValueErrorrÁr,)r!rr€rrrrÔs8 ÿ ÿzExprDateTimeNamespace.timestampN)r)r¹rºr»r"rêrërìrírîrïrðrñròrórôrõrör÷rørùrúrürþrrrrrr´ s**034032333&++441N7=r´c@s„eZdZddddœdd„Zdddœdd „Zdd dd œd d „Zddddœdd„Zddddœdd„Zdddœdd„Zdddœdd„Z dS)r¸r r½rr¿cCs ||_dSrrÀrÂrrrr"szExprNameNamespace.__init__r±csˆj ‡fdd„¡S)aï Keep the original root name of the 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 >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("foo").alias("alias_for_foo").name.keep()) We can then pass either pandas or Polars to `func`: >>> func(df_pd).columns Index(['foo'], dtype='object') >>> func(df_pl).columns ['foo'] csˆj |¡j ¡Sr)rÁrr/Úkeepr&r(rrr)9r*z(ExprNameNamespace.keep..rÄr(rr(rrszExprNameNamespace.keepzCallable[[str], str])r!r2rcsˆj ‡‡fdd„¡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. 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 >>> 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 >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("foo", "BAR").name.map(renaming_func)) We can then pass either pandas or Polars to `func`: >>> func(df_pd).columns Index(['oof', 'RAB'], dtype='object') >>> func(df_pl).columns ['oof', 'RAB'] csˆj |¡j ˆ¡Sr)rÁrr/Úmapr&©r2r!rrr)]r*z'ExprNameNamespace.map..rÄ)r!r2rr rr ;s"zExprNameNamespace.mapr.rÓcsˆj ‡‡fdd„¡S)aÐ Add a prefix to the root column name of the expression. Arguments: prefix: Prefix to add to the root column name. 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 >>> 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: >>> @nw.narwhalify ... def add_colname_prefix(df, prefix): ... return df.select(nw.col("foo", "BAR").name.prefix(prefix)) 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'] csˆj |¡j ˆ¡Sr)rÁrr/rÔr&rÖrrr)r*z*ExprNameNamespace.prefix..rÄr×rrÖrrÔ_s"zExprNameNamespace.prefixrØcsˆj ‡‡fdd„¡S)aÏ Add a suffix to the root column name of the expression. Arguments: suffix: Suffix to add to the root column name. 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 >>> 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: >>> @nw.narwhalify ... def add_colname_suffix(df, suffix): ... return df.select(nw.col("foo", "BAR").name.suffix(suffix)) 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'] csˆj |¡j ˆ¡Sr)rÁrr/rÙr&rÛrrr)¤r*z*ExprNameNamespace.suffix..rÄrÛrrÛrrÙƒs!zExprNameNamespace.suffixcsˆj ‡fdd„¡S)a÷ Make the root column name lowercase. 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 >>> 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: >>> @nw.narwhalify ... def to_lower(df): ... return df.select(nw.col("foo", "BAR").name.to_lowercase()) 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'] csˆj |¡j ¡Sr)rÁrr/rér&r(rrr)Är*z0ExprNameNamespace.to_lowercase..rÄr(rr(rré¦szExprNameNamespace.to_lowercasecsˆj ‡fdd„¡S)aö Make the root column name uppercase. 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 >>> 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: >>> @nw.narwhalify ... def to_upper(df): ... return df.select(nw.col("foo", "BAR").name.to_uppercase()) 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'] csˆj |¡j ¡Sr)rÁrr/rèr&r(rrr)ãr*z0ExprNameNamespace.to_uppercase..rÄr(rr(rrèÆszExprNameNamespace.to_uppercaseN) r¹rºr»r"rr rÔrÙrérèrrrrr¸s $$# r¸r˜)Únamesrcsdddœ‡fdd„ }t|ƒS)u| Creates 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.col("a") * nw.col("b")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 3 1 8 >>> func(df_pl) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 3 │ │ 8 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[3,8]] r©r'rcs|jtˆƒŽSr)Úcolr r&©r rrÚfuncszcol..func©r)r rrrrr æs-r zint | Sequence[int])Úindicesrcsdddœ‡fdd„ }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. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.nth(0) * 2) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 2 1 4 >>> func(df_pl) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 4 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[2,4]] rr cs|jtˆƒŽSr)Únthr r&©rrrrJsznth..funcr)rrrrrrs1rr#cCs tdd„ƒS)uÓ Instantiate an expression representing all columns. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.all() * 2) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 2 8 1 4 10 2 6 12 >>> func(df_pl) shape: (3, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 2 ┆ 8 │ │ 4 ┆ 10 │ │ 6 ┆ 12 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[2,4,6]] b: [[8,10,12]] cSs| ¡Sr)rVr&rrrr)~r*zall_..rrrrrÚall_Qs-rcCsdddœdd„}t|ƒS)uË Return the number of rows. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.len()) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) len 0 2 >>> func(df_pl) shape: (1, 1) ┌─────┠│ len │ │ --- │ │ u32 │ â•žâ•â•â•â•â•â•¡ │ 2 │ └─────┘ >>> func(df_pa) pyarrow.Table len: int64 ---- len: [[2]] rr cSs| ¡Sr)r«r&rrrrªszlen_..funcr)rrrrÚlen_‚s(rr.)Úcolumnsrcst‡fdd„ƒ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 Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.sum("a")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 3 >>> func(df_pl) shape: (1, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 3 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[3]] cs |jˆŽSr)r%r&©rrrr)Þr*zsum..rrrrrr%°s.r%cst‡fdd„ƒS)u> Get the mean value. Note: Syntactic sugar for ``nw.col(columns).mean()`` Arguments: columns: Name(s) of the columns to use in the aggregation function Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> df_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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.mean("a")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 4.0 >>> func(df_pl) shape: (1, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 4.0 │ └─────┘ >>> func(df_pa) pyarrow.Table a: double ---- a: [[4]] cs |jˆŽSr)rWr&rrrr)r*zmean..rrrrrrWás.rWcst‡fdd„ƒS)ub Return the minimum value. Note: Syntactic sugar for ``nw.col(columns).min()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.min("b")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) b 0 5 >>> func(df_pl) shape: (1, 1) ┌─────┠│ b │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 5 │ └─────┘ >>> func(df_pa) pyarrow.Table b: int64 ---- b: [[5]] cs |jˆŽSr)r^r&rrrr)?r*zmin..rrrrrr^s-r^cst‡fdd„ƒS)ub Return the maximum value. Note: Syntactic sugar for ``nw.col(columns).max()``. Arguments: columns: Name(s) of the columns to use in the aggregation function. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.max("a")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 2 >>> func(df_pl) shape: (1, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[2]] cs |jˆŽSr)r_r&rrrr)or*zmax..rrrrrr_Bs-r_úIntoExpr | Iterable[IntoExpr])Úexprsrcs ˆsd}t|ƒ‚t‡fdd„ƒ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. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.sum_horizontal("a", "b")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 6.0 1 12.0 2 3.0 >>> func(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 6 │ │ 12 │ │ 3 │ └─────┘ >>> func(df_pa) pyarrow.Table a: int64 ---- a: [[6,12,3]] z:At least one expression must be passed to `sum_horizontal`csˆj‡fdd„tˆƒDƒŽS)Ncsg|]}tˆ|ƒ‘qSrrƒ©r„Úvr&rrr†ªsz4sum_horizontal....)Úsum_horizontalr r&©rr&rr)©sÿz sum_horizontal..©rr©rr€rrrrrs 3 ÿrcs ˆsd}t|ƒ‚t‡fdd„ƒS)u= Get 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. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.min_horizontal("a", "b")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(pd.DataFrame(data)) a 0 1.0 1 5.0 2 3.0 >>> func(pl.DataFrame(data)) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 1 │ │ 5 │ │ 3 │ └─────┘ >>> func(pa.table(data)) pyarrow.Table a: int64 ---- a: [[1,5,3]] z:At least one expression must be passed to `min_horizontal`csˆj‡fdd„tˆƒDƒŽS)Ncsg|]}tˆ|ƒ‘qSrrƒrr&rrr†ész4min_horizontal....)Úmin_horizontalr r&rr&rr)èsÿz min_horizontal..rrrrrr ¯s 5 ÿr cs ˆsd}t|ƒ‚t‡fdd„ƒS)u= Get 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. Examples: >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.max_horizontal("a", "b")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(pd.DataFrame(data)) a 0 4.0 1 8.0 2 3.0 >>> func(pl.DataFrame(data)) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 4 │ │ 8 │ │ 3 │ └─────┘ >>> func(pa.table(data)) pyarrow.Table a: int64 ---- a: [[4,8,3]] z:At least one expression must be passed to `max_horizontal`csˆj‡fdd„tˆƒDƒŽS)Ncsg|]}tˆ|ƒ‘qSrrƒrr&rrr†(sz4max_horizontal....)Úmax_horizontalr r&rr&rr)'sÿz max_horizontal..rrrrrr!îs 5 ÿr!c@s<eZdZdddœdd„Zdddœdd „Zdd d œd d „ZdS)ÚWhenrrrcGst|gƒ|_dSr)r Ú _predicatesr‰rrrr".sz When.__init__rr cs‡fdd„|jDƒS)Ncsg|]}tˆ|ƒ‘qSrrƒrr&rrr†2sz,When._extract_predicates..)r#)r!r'rr&rÚ_extract_predicates1szWhen._extract_predicatesÚThenrŒcst‡‡fdd„ƒS)Ncs|jˆ |¡Ž t|ˆƒ¡Sr)Úwhenr$Úthenrr&rrrr)6sÿzWhen.then..)r%rrrrr'4s ÿz When.thenN)r¹rºr»r"r$r'rrrrr"-sr"c@s,eZdZdddœdd„Zdddœd d „Zd S) r%rrrcCs ||_dSrrr rrrr"=sz Then.__init__rrrŒcst‡‡fdd„ƒS)Ncsˆ |¡ t|ˆƒ¡Sr)rÚ otherwiserr&rrrr)Ar*z Then.otherwise..rrrrrr(@szThen.otherwiseN)r¹rºr»r"r(rrrrr%<sr%rcGst|ŽS)ui 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df_any): ... return df_any.with_columns( ... nw.when(nw.col("a") < 3).then(5).otherwise(6).alias("a_when") ... ) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b a_when 0 1 5 5 1 2 10 5 2 3 15 6 >>> func(df_pl) shape: (3, 3) ┌─────┬─────┬────────┠│ a ┆ b ┆ a_when │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•¡ │ 1 ┆ 5 ┆ 5 │ │ 2 ┆ 10 ┆ 5 │ │ 3 ┆ 15 ┆ 6 │ └─────┴─────┴────────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 a_when: int64 ---- a: [[1,2,3]] b: [[5,10,15]] a_when: [[5,5,6]] )r")r‚rrrr&Ds8r&cs ˆsd}t|ƒ‚t‡fdd„ƒ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. Notes: pandas and Polars handle null values differently. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.select("a", "b", all=nw.all_horizontal("a", "b")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b all 0 False False False 1 False True False 2 True True True 3 True None False 4 False None False 5 None None False >>> func(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 │ └───────┴───────┴───────┘ >>> func(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`csˆj‡fdd„tˆƒDƒŽS)Ncsg|]}tˆ|ƒ‘qSrrƒrr&rrr†Åsz4all_horizontal....)Úall_horizontalr r&rr&rr)Äsÿz all_horizontal..rrrrrr)s A ÿr)Nz DType | None)rr6rcsFtˆƒrd}t|ƒ‚tˆttfƒr4dˆ›}t|ƒ‚t‡‡fdd„ƒS)u Return 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. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.with_columns(nw.lit(3).alias("b")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b 0 1 3 1 2 3 >>> func(df_pl) shape: (2, 2) ┌─────┬─────┠│ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i32 │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ 1 ┆ 3 │ │ 2 ┆ 3 │ └─────┴─────┘ >>> func(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[1,2]] b: [[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 cs | ˆˆ¡Sr)Úlitr&©r6rrrr)r*zlit..)r rrÚlistÚtuplerr)rr6r€rr+rr*Ês/ÿ r*cs ˆsd}t|ƒ‚t‡fdd„ƒS)u7 Compute the bitwise OR horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Notes: pandas and Polars handle null values differently. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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) >>> df_pa = pa.table(data) We define a dataframe-agnostic function: >>> @nw.narwhalify ... def func(df): ... return df.select("a", "b", any=nw.any_horizontal("a", "b")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a b any 0 False False False 1 False True True 2 True True True 3 True None True 4 False None False 5 None None False >>> func(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 │ └───────┴───────┴───────┘ >>> func(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`csˆj‡fdd„tˆƒDƒŽS)Ncsg|]}tˆ|ƒ‘qSrrƒrr&rrr†Msz4any_horizontal....)Úany_horizontalr r&rr&rr)Lsÿz any_horizontal..rrrrrr.s A ÿr.cs ˆsd}t|ƒ‚t‡fdd„ƒS)uR Compute the mean of all values horizontally across columns. Arguments: exprs: Name(s) of the columns to use in the aggregation function. Accepts expression input. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> 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: >>> @nw.narwhalify ... def func(df): ... return df.select(nw.mean_horizontal("a", "b")) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(df_pd) a 0 2.5 1 6.5 2 3.0 >>> func(df_pl) shape: (3, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 2.5 │ │ 6.5 │ │ 3.0 │ └─────┘ >>> func(df_pa) pyarrow.Table a: double ---- a: [[2.5,6.5,3]] z;At least one expression must be passed to `mean_horizontal`csˆj‡fdd„tˆƒDƒŽS)Ncsg|]}tˆ|ƒ‘qSrrƒrr&rrr†Žsz5mean_horizontal....)Úmean_horizontalr r&rr&rr)sÿz!mean_horizontal..rrrrrr/Rs 7 ÿr/ÚF©Ú separatorÚ ignore_nullsrrd)rÚ more_exprsr2r3rcst‡‡‡‡fdd„ƒS)uS 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. Examples: >>> import narwhals as nw >>> 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 >>> @nw.narwhalify ... def func(df): ... return df.select( ... nw.concat_str( ... [ ... nw.col("a") * 2, ... nw.col("b"), ... nw.col("c"), ... ], ... separator=" ", ... ).alias("full_sentence") ... ) We can pass any supported library such as Pandas, Polars, or PyArrow to `func`: >>> func(pd.DataFrame(data)) full_sentence 0 2 dogs play 1 4 cats swim 2 None >>> func(pl.DataFrame(data)) shape: (3, 1) ┌───────────────┠│ full_sentence │ │ --- │ │ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 2 dogs play │ │ 4 cats swim │ │ null │ └───────────────┘ >>> func(pa.table(data)) pyarrow.Table full_sentence: string ---- full_sentence: [["2 dogs play","4 cats swim",null]] cs:ˆj‡fdd„tˆgƒDƒf‡fdd„ˆDƒžˆˆdœŽS)Ncsg|]}tˆ|ƒ‘qSrrƒrr&rrr†Þsz0concat_str....csg|]}tˆ|ƒ‘qSrrƒrr&rrr†ßsr1)Ú concat_strr r&©rr3r4r2r&rr)Ýsÿþüzconcat_str..r)rr2r3r4rr6rr5“sIÿr5)N)0Ú __future__rÚtypingrrrrrrr r Znarwhals.dependenciesr Znarwhals.utilsr Ztyping_extensionsr Znarwhals.dtypesrZnarwhals.typingrrrr½r¶r³r´r¸r rrrr%rWr^r_rr r!r"r%r&r)r*r.r/r5Ú__all__rrrrÚs–               W /wP381.1100=??;K=KDüTÿ