Ë Ôªg™ãó4—ddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlm Z dd lm Z dd lm Z dd lm Z dd lm Z dd lmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZerTddlmZddlm Z ddl!m"Z"ddl#Z$ddl%Z&ddl'Z(ddl)m*Z*ddl+m,Z,ddl+m-Z-ddl.m/Z/ddl0m1Z1dd l0m2Z2dd!l0m3Z3dd"l0m4Z4dd#lm5Z5e d$d%¬&«Z6e d'd(¬&«Z7Gd)„d*ee6«Z8Gd+„d,e8e7«Z9Gd-„d.e8e6«Z:y)/é)Ú annotations)Ú TYPE_CHECKING)ÚAny)ÚCallable)ÚGeneric)ÚIterable)ÚIterator)ÚLiteral)ÚNoReturn)ÚSequence)ÚTypeVar)Úoverload)Úwarn)Ú get_polars)Úis_numpy_array)ÚSchema©Ú to_native)Úfind_stacklevel)Úflatten)Ú generate_repr)Úis_sequence_but_not_str)Ú parse_version)ÚBytesIO)ÚPath)Ú ModuleTypeN)ÚSelf©ÚGroupBy©Ú LazyGroupBy©ÚSeries)Ú IntoDataFrame)ÚIntoExpr)Ú IntoFrame)ÚSizeUnit)ÚImplementationÚFrameTr&)ÚboundÚ DataFrameTr$cóÈ—eZdZUded<ded<d'd„Zd(d„Zd)d„Zd*d„Zd+d „Ze d,d „«Z d,d „Z d-d „Z d.d/d „Z d0d1d„Ze d2d„«Z d3d„Z d3d„Zd4d„Zd5d„Zd5d„Zd6d„Z d7d„Zdddœ d8d„Z d9ddddœ d:d„Zd;d„Zdd"„Z d?d#„Zd@d$„ZdAd%„ZdBd&„Zy)CÚ BaseFramerÚ_compliant_frameú&Literal['full', 'lazy', 'interchange']Ú_levelcó6—|jj«S©N)r.Ú__native_namespace__©Úselfs úG/var/www/openai/venv/lib/python3.12/site-packages/narwhals/dataframe.pyr3zBaseFrame.__native_namespace__5s€Ø×$Ñ$×9Ñ9Ó;Ð;ócó6—|jj«Sr2)r.Ú__narwhals_namespace__r4s r6r9z BaseFrame.__narwhals_namespace__8s€Ø×$Ñ$×;Ñ;Ó=Ð=r7có<—|j||j¬«S)N©Úlevel)Ú __class__r0)r5Údfs r6Ú_from_compliant_dataframez#BaseFrame._from_compliant_dataframe;s"€à~‰~Ø Ø—+‘+ðó ð r7cóҗt|«Dcgc]}|j|«‘Œ}}|j«Dcic]\}}||j|«“Œ}}}||fScc}wcc}}w)zDProcess `args` and `kwargs`, extracting underlying objects as we go.)rÚ_extract_compliantÚitems)r5ÚargsÚkwargsÚvÚks r6Ú_flatten_and_extractzBaseFrame._flatten_and_extractBsf€ä4;žDŽMÓB±Mšq×'Ñ'šÕ*°MˆÐBØó ð r7cóî—t|«dk(r(t|dt«rtd„|dD««s|j|i|€Ž\}}|j |j j|i|€Ž«S)Nérc3ó<K—|]}t|t«–—Œy­wr2©rNÚbool©Ú.0Úxs r6Ú z#BaseFrame.filter..œóèø€Ð?±šA”J˜q€$×'±ùó‚)ÚlenrNÚlistÚallrGr?r.Úfilter)r5Ú predicatesÚ constraintss r6rzBaseFrame.filter–s‚€ô  ‹O˜qÒ Ü˜: a™=¬$Ô/ÜÑ?°žA²Ó?Ô?à&? d×&?Ñ&?Øð'Ø*ñ'Ñ #ˆJ˜ ð×-Ñ-Ø (ˆD× !Ñ !× (Ñ (š*Ð Dž Ñ Dó ð r7F©Ú descendingÚ nulls_lastcób—|j|jj|g|¢­||dœŽ«S)Nr)r?r.Úsort)r5Úbyr‘r’Úmore_bys r6r”zBaseFrame.sort¥sB€ð×-Ñ-Ø &ˆD× !Ñ !× &Ñ &Øð Øñ Ø)3À ò ó ð r7Ú_right©Úleft_onÚright_onÚsuffixc ó^—d}||vrd|›d|›d}t|«‚|dk(r|€|€| d}t|«‚|dk7r|€||€d|›d}t|«‚|dk7r||€|d |›d}t|«‚||x}}|j|jj |j |«||||¬ ««S) N)ÚinnerÚleftÚcrossÚantiÚsemiz2Only the following join strategies are supported: ú ; found 'ú'.rŸz>Can not pass `left_on`, `right_on` or `on` keys for cross joinzGEither (`left_on` and `right_on`) or `on` keys should be specified for Ú.zBIf `on` is specified, `left_on` and `right_on` should be None for )Úhowr™ršr›)ÚNotImplementedErrorÚ ValueErrorr?r.ÚjoinrA) r5ÚotherÚonr¥r™ršr›Ú_supported_joinsrUs r6ršzBaseFrame.join²s€ðFÐà Ð&Ñ &ØFÐGWÐFXÐXaÐbeÐafÐfhÐiˆCÜ% cÓ*Ð *à 'Š>Ø Ð  8Ð#7ž2ž>àRˆCܘS“/Ð !à 'Š>˜r˜zšwšÀ(ÐBRØ[Ð\_Ð[`Ð`aÐbˆCܘS“/Ð !à 'Š>Ø ˆN Ð 3°xÐ7KàVÐWZÐV[Ð[\Ð]ˆCܘS“/Ð !à ˆ>Ø!#Ð #ˆGhà×-Ñ-Ø × !Ñ !× &Ñ &Ø×'Ñ'šÓ.ØØØ!Øð 'ó ó ð r7cóT—|j|jj««Sr2)r?r.Úcloner4s r6r­zBaseFrame.cloneßs"€Ø×-Ñ-šd×.CÑ.C×.IÑ.IÓ.KÓLÐLr7cóZ—|j|jj||¬««S)N©rwÚoffset)r?r.Ú gather_every)r5rwr°s r6r±zBaseFrame.gather_everyâs.€Ø×-Ñ-Ø × !Ñ !× .Ñ .°ž6Ð .Ó Bó ð r7Úbackward©r™ršrªÚby_leftÚby_rightr•Ústrategyc óØ—d} || vrd| ›d|›d} t| «‚|€||€ d} t| «‚||€| d} t| «‚|€|€|€||€ d} t| «‚||€| d} t| «‚|?|j|jj |j |«|||||¬ ««S|j|jj |j |«||||||¬ ««S) N)r²ÚforwardÚnearestz-Only the following strategies are supported: r¢r£zCEither (`left_on` and `right_on`) or `on` keys should be specified.z>If `on` is specified, `left_on` and `right_on` should be None.zGCan not specify only `by_left` or `by_right`, you need to specify both.z>If `by` is specified, `by_left` and `by_right` should be None.)rªrŽrµr•r¶)r™ršrŽrµr•r¶)rŠr§r?r.Ú join_asofrA) r5r©r™ršrªrŽrµr•r¶Ú_supported_strategiesrUs r6rºzBaseFrame.join_asofçs_€ð!CÐà Ð0Ñ 0ØAÐBWÐAXÐXaÐbjÐakÐkmÐnˆCÜ% cÓ*Ð *à ˆJ˜W˜_°Ð0@ØWˆCܘS“/Ð !Ø ˆN Ð!4žÐ8LØRˆCܘS“/Ð !Ø ˆJØ ˆ_ Ð!5ØÐ#šÐ(8ðZð ô˜S“/Ð !Ø ˆN Ð!4žÐ8LØRˆCܘS“/Ð !Ø ˆ>Ø×1Ñ1Ø×%Ñ%×/Ñ/Ø×+Ñ+šEÓ2ØØ#Ø%ØØ%ð 0óó ð ð×-Ñ-Ø × !Ñ !× +Ñ +Ø×'Ñ'šÓ.ØØ!ØØ!ØØ!ð ,ó ó  ð r7có^—|j|jj||||¬««S)N©rªÚindexÚ variable_nameÚ value_name)r?r.Úunpivot)r5rªrŸr¿rÀs r6rÁzBaseFrame.unpivot!s<€ð×-Ñ-Ø × !Ñ !× )Ñ )ØØØ+Ø%ð *ó ó ð r7có—d}t|«‚)Nz«DataFrame.__neq__ and LazyFrame.__neq__ are not implemented, please use expressions instead. Hint: instead of df != 0 you may want to use df.select(nw.all() != 0)©rŠ©r5r©rUs r6Ú__neq__zBaseFrame.__neq__2ó€ð +ð ô" #Ó&Ð&r7có—d}t|«‚)Nz©DataFrame.__eq__ and LazyFrame.__eq__ are not implemented, please use expressions instead. Hint: instead of df == 0 you may want to use df.select(nw.all() == 0)rÃrÄs r6Ú__eq__zBaseFrame.__eq__=rÆr7cóZ—|j|jj|g|¢­Ž«Sr2)r?r.Úexplode)r5riÚ more_columnss r6rÊzBaseFrame.explodeHs6€Ø×-Ñ-Ø )ˆD× !Ñ !× )Ñ )Øð àò ó ð r7)r5rÚreturnr)rÌr)r>rrÌr)rCrrDrrÌr)rTrrÌr©rÌr©r^zCallable[[Any], Self]rCrrDrrÌr©rŸ©rcrQrÌrr2©r5rrfústr | list[str] | NonerÌr©rÌz list[str]©rmzIntoExpr | Iterable[IntoExpr]rnr%rÌr©rszdict[str, str]rÌr©rwÚintrÌr)riz Iterable[str]r}rƒrÌr©rŽz*IntoExpr | Iterable[IntoExpr] | list[bool]rrrÌr© r•ústr | Iterable[str]r–rQr‘zbool | Sequence[bool]r’rƒrÌr©Nr©r©rrªrÒr¥z1Literal['inner', 'left', 'cross', 'semi', 'anti']r™rÒršrÒr›rQrÌr©rÌr©r©r5rrwr×r°r×rÌr©r©rr™ú str | NoneršrárªrárŽrÒrµrÒr•rÒr¶z)Literal['backward', 'forward', 'nearest']rÌr© r5rrªrÒrŸrÒr¿rárÀrárÌr)r©rrÌr )r©ÚobjectrÌr ©r5rrizstr | Sequence[str]rËrQrÌr) Ú__name__Ú __module__Ú __qualname__Ú__annotations__r3r9r?rGrAÚpropertyrWrZr_rargrirkrprrrurzr~rr”ršr­r±rºrÁrÅrÈrÊr]r7r6r-r-1s@…ØÓØ 2Ó2ó<ó>ó óó ð(ò<óð<ó%ó /ô ô  ð ò-óð-ð Ø3ð ØDLð à ó ð à-ð ð ð ð ó  óUóMóMó ð  ØEð  ØVYð  à ó  ð&-2Ø ñ  à ð  ðð  ð*ð  ð ð  ð ó  ð &*ØAHð + ð +/Ø+/Øñ+ àð+ ð #ð+ ð?ð + ð (ð + ð)ð+ ðð+ ð ó+ óZMô ð#Ø#ØØ*.Ø+/Ø%)Ø>Hñ8 àð8 ðð 8 ð ð 8 ð ð 8 ð(ð8 ð)ð8 ð #ð8 ð<ð8 ð ó8 ðt Øð à "ð ð&ð  ð "ð  ð ð  ð ó ó" 'ó 'ô r7r-có쇗eZdZdZedfd„«Zedgd„«Z dhd„Zedid„«Zdjd„Z dkdld„Z dmd „Z dndod „Z dpd „Z dqd „Zdrd „Zedndsd„«Zedtd„«Zdndud„Zdtd„Zdvd„Zedwd„«Zdxd„Zdydzd„Zed{d„«Zed|d„«Zed}d„«Zed~d„«Zedd„«Zed€d„«Zedd„«Zed‚d„«Zedƒd„«Zed„d„«Zed…d „«Zed†d!„«Zed‡d"„«Zedˆd#„«Z d‰d$„ZdŠd%„Zed&d'œd‹d(„«ZedŒd)„«Ze dd*„«Zd+d'œ dd,„ZdŽd-„Zdˆfd.„ Zdndˆfd/„ Zd‘d’ˆfd0„ Zed“ˆfd1„ «Zd”ˆfd2„ Zed•ˆfd3„ «Z ed4d5œd–d6„«Z!ed—d7„«Z!ed˜d8„«Z!d4d5œ d˜d9„Z!ed&d:œ d™d;„«Z"ed&d:œ dšd<„«Z"ed&d:œ d›d=„«Z"d4d>d?œ d›d@„Z" dœˆfdA„ Z# dœˆfdB„ Z$dˆfdC„ Z%dždŸˆfdD„ Z&dždŸˆfdE„ Z'd+dFœd ˆfdG„Z( dndHd4dIœ d¡dJ„Z) d¢ˆfdK„ Z*d4dLœ d£dM„Z+d4d4dNœ d€ˆfdO„Z, d¥dddPdQœ dŠˆfdR„Z-dddddddSdTœ d§ˆfdU„Z.dšdV„Z/d©dW„Z0dšdX„Z1dªdY„Z2dkd«dZ„Z3d¬ˆfd[„ Z4d­d®ˆfd\„ Z5ddddd4d]d^œ d¯d_„Z6d°d`„Z7 dndd4ddaœ d±db„Z8 dnddddcœ d²ˆfdd„Z9d³ˆfde„ Z:ˆxZ;S)ŽÚ DataFramea‡Narwhals DataFrame, backed by a native eager dataframe. !!! warning This class is not meant to be instantiated directly - instead: - If the native object is a eager dataframe from one of the supported backend (e.g. pandas.DataFrame, polars.DataFrame, pyarrow.Table), you can use [`narwhals.from_native`][]: ```py narwhals.from_native(native_dataframe) narwhals.from_native(native_dataframe, eager_only=True) ``` - If the object is a dictionary of column names and generic sequences mapping (e.g. `dict[str, list]`), you can create a DataFrame via [`narwhals.from_dict`][]: ```py narwhals.from_dict( data={"a": [1, 2, 3]}, native_namespace=narwhals.get_native_namespace(another_object), ) ``` có—ddlm}|S)Nrr")rMr#)r5r#s r6Ú_serieszDataFrame._seriesjs €å*àˆ r7có—tSr2)Ú LazyFramer4s r6Ú _lazyframezDataFrame._lazyframepó€äÐr7có†—||_t|d«r|j«|_ydt |«›}t |«‚)NÚ__narwhals_dataframe__zCExpected an object which implements `__narwhals_dataframe__`, got: )r0Úhasattrrór.rRÚAssertionError©r5r>r<rUs r6Ú__init__zDataFrame.__init__tsG€ð ?DˆŒ Ü 2Ð/Ô 0Ø)+×)BÑ)BÓ)DˆDÕ !àWÔX\Ð]_ÓX`ÐWaÐbˆCÜ  Ó%Ð %r7có.—|jjS)a×Return implementation of native frame. This can be useful when you need to use special-casing for features outside of Narwhals' scope - for example, when dealing with pandas' Period Dtype. Returns: Implementation. Examples: >>> import narwhals as nw >>> import pandas as pd >>> df_native = pd.DataFrame({"a": [1, 2, 3]}) >>> df = nw.from_native(df_native) >>> df.implementation >>> df.implementation.is_pandas() True >>> df.implementation.is_pandas_like() True >>> df.implementation.is_polars() False ©r.Ú_implementationr4s r6ÚimplementationzDataFrame.implementations€ð0×$Ñ$×4Ñ4Ð4r7có6—|jj«Sr2)r.Ú__len__r4s r6rýzDataFrame.__len__›s€Ø×$Ñ$×,Ñ,Ó.Ð.r7Ncó<—|jj||¬«S)N)Úcopy)r.Ú __array__)r5Údtyperÿs r6rzDataFrame.__array__žs€Ø×$Ñ$×.Ñ.šuž4Ð.Ó@Ð@r7cóR—td|j«j««S)NzNarwhals DataFrame©rrÚ__repr__r4s r6rzDataFrame.__repr__¡ó €ÜÐ1°4·>±>Ó3C×3LÑ3LÓ3NÓOÐOr7cór—|jj}t|d«r|j|¬«S ddl}t|j«dkrdt |«›}t |«d‚|j«}|j|¬«S#t $r}dt |«›}t |«|‚d}~wwxYw)ahExport a DataFrame via the Arrow PyCapsule Interface. - if the underlying dataframe implements the interface, it'll return that - else, it'll call `to_arrow` and then defer to PyArrow's implementation See [PyCapsule Interface](https://arrow.apache.org/docs/dev/format/CDataInterface/PyCapsuleInterface.html) for more. Ú__arrow_c_stream__)Úrequested_schemarNzRPyArrow>=14.0.0 is required for `DataFrame.__arrow_c_stream__` for object of type )ér) r.Ú _native_framerôrÚpyarrowÚModuleNotFoundErrorrRrÚ __version__Úto_arrow)r5rÚ native_frameÚpaÚexcrUÚpa_tables r6rzDataFrame.__arrow_c_stream__€sĀð×,Ñ,×:Ñ:ˆ Ü <Ð!5Ô 6Ø×2Ñ2ÐDTÐ2ÓUÐ Uð 4Û ô ˜Ÿ™Ó (š7Ò 2ØfÔgkÐlxÓgyÐfzÐ{ˆCÜ% cÓ*°Ð 4Ø—=‘=“?ˆØ×*Ñ*Ð>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_lazy(df_native: IntoFrame) -> IntoFrame: ... df = nw.from_native(df_native) ... return df.lazy().to_native() Note that then, pandas and pyarrow dataframe stay eager, but Polars DataFrame becomes a Polars LazyFrame: >>> agnostic_lazy(df_pd) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> agnostic_lazy(df_pl) >>> agnostic_lazy(df_pa) pyarrow.Table foo: int64 bar: double ham: string ---- foo: [[1,2,3]] bar: [[6,7,8]] ham: [["a","b","c"]] Úlazyr;)rðr.rr4s r6rzDataFrame.lazy»s'€ð^‰˜t×4Ñ4×9Ñ9Ó;À6ˆÓJÐJr7có.—|jjS)uõConvert Narwhals DataFrame to native one. Returns: Object of class that user started with. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Calling `to_native` on a Narwhals DataFrame returns the native object: >>> nw.from_native(df_pd).to_native() foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> nw.from_native(df_pl).to_native() shape: (3, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6.0 ┆ a │ │ 2 ┆ 7.0 ┆ b │ │ 3 ┆ 8.0 ┆ c │ └─────┮─────┮─────┘ >>> nw.from_native(df_pa).to_native() pyarrow.Table foo: int64 bar: double ham: string ---- foo: [[1,2,3]] bar: [[6,7,8]] ham: [["a","b","c"]] )r.r r4s r6rzDataFrame.to_nativeìs€ðX×$Ñ$×2Ñ2Ð2r7có6—|jj«S)aœConvert this DataFrame to a pandas DataFrame. Returns: A pandas DataFrame. Examples: Construct pandas, Polars (eager) and PyArrow DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_to_pandas(df_native: IntoDataFrame) -> pd.DataFrame: ... df = nw.from_native(df_native) ... return df.to_pandas() We can then pass any supported library such as pandas, Polars (eager), or PyArrow to `agnostic_to_pandas`: >>> agnostic_to_pandas(df_pd) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> agnostic_to_pandas(df_pl) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> agnostic_to_pandas(df_pa) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c )r.Ú to_pandasr4s r6rzDataFrame.to_pandass€ðX×$Ñ$×.Ñ.Ó0Ð0r7có—yr2r]©r5Úfiles r6Ú write_csvzDataFrame.write_csvHs€Ø36r7có—yr2r]rs r6rzDataFrame.write_csvKs€Ø=@r7có8—|jj|«S)aWrite dataframe to comma-separated values (CSV) file. Arguments: file: String, path object or file-like object to which the dataframe will be written. If None, the resulting csv format is returned as a string. Returns: String or None. Examples: Construct pandas, Polars (eager) and PyArrow DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_write_csv(df_native: IntoDataFrame) -> str: ... df = nw.from_native(df_native) ... return df.write_csv() We can pass any supported library such as pandas, Polars or PyArrow to `agnostic_write_csv`: >>> agnostic_write_csv(df_pd) 'foo,bar,ham\n1,6.0,a\n2,7.0,b\n3,8.0,c\n' >>> agnostic_write_csv(df_pl) 'foo,bar,ham\n1,6.0,a\n2,7.0,b\n3,8.0,c\n' >>> agnostic_write_csv(df_pa) '"foo","bar","ham"\n1,6,"a"\n2,7,"b"\n3,8,"c"\n' If we had passed a file name to `write_csv`, it would have been written to that file. )r.rrs r6rzDataFrame.write_csvNs€ðR×$Ñ$×.Ñ.štÓ4Ð4r7có:—|jj|«y)aÄWrite dataframe to parquet file. Arguments: file: String, path object or file-like object to which the dataframe will be written. Returns: None. Examples: Construct pandas, Polars and PyArrow DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_write_parquet(df_native: IntoDataFrame): ... df = nw.from_native(df_native) ... df.write_parquet("foo.parquet") We can then pass either pandas, Polars or PyArrow to `agnostic_write_parquet`: >>> agnostic_write_parquet(df_pd) # doctest:+SKIP >>> agnostic_write_parquet(df_pl) # doctest:+SKIP >>> agnostic_write_parquet(df_pa) # doctest:+SKIP N)r.Ú write_parquetrs r6rzDataFrame.write_parquetys€ðF ×Ñ×+Ñ+šDÕ1r7có6—|jj«S)a‰Convert this DataFrame to a NumPy ndarray. Returns: A NumPy ndarray array. Examples: Construct pandas and polars DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> import numpy as np >>> from narwhals.typing import IntoDataFrame >>> data = {"foo": [1, 2, 3], "bar": [6.5, 7.0, 8.5], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_to_numpy(df_native: IntoDataFrame) -> np.ndarray: ... df = nw.from_native(df_native) ... return df.to_numpy() We can then pass either pandas, Polars or PyArrow to `agnostic_to_numpy`: >>> agnostic_to_numpy(df_pd) array([[1, 6.5, 'a'], [2, 7.0, 'b'], [3, 8.5, 'c']], dtype=object) >>> agnostic_to_numpy(df_pl) array([[1, 6.5, 'a'], [2, 7.0, 'b'], [3, 8.5, 'c']], dtype=object) >>> agnostic_to_numpy(df_pa) array([[1, 6.5, 'a'], [2, 7.0, 'b'], [3, 8.5, 'c']], dtype=object) )r.Úto_numpyr4s r6r!zDataFrame.to_numpyžs€ðR×$Ñ$×-Ñ-Ó/Ð/r7có.—|jjS)a Get the shape of the DataFrame. Returns: The shape of the dataframe as a tuple. Examples: Construct pandas and polars DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = {"foo": [1, 2, 3, 4, 5]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_shape(df_native: IntoDataFrame) -> tuple[int, int]: ... df = nw.from_native(df_native) ... return df.shape We can then pass either pandas, Polars or PyArrow to `agnostic_shape`: >>> agnostic_shape(df_pd) (5, 1) >>> agnostic_shape(df_pl) (5, 1) >>> agnostic_shape(df_pa) (5, 1) )r.Úshaper4s r6r#zDataFrame.shapeÉs€ðF×$Ñ$×*Ñ*Ð*r7cón—|j|jj|«|j¬«S)ayGet a single column by name. Arguments: name: The column name as a string. Returns: A Narwhals Series, backed by a native series. Notes: Although `name` is typed as `str`, pandas does allow non-string column names, and they will work when passed to this function if the `narwhals.DataFrame` is backed by a pandas dataframe with non-string columns. This function can only be used to extract a column by name, so there is no risk of ambiguity. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_get_column(df_native: IntoDataFrame) -> IntoSeries: ... df = nw.from_native(df_native) ... name = df.columns[0] ... return df.get_column(name).to_native() We can then pass either pandas, Polars or PyArrow to `agnostic_get_column`: >>> agnostic_get_column(df_pd) 0 1 1 2 Name: a, dtype: int64 >>> agnostic_get_column(df_pl) # doctest:+NORMALIZE_WHITESPACE shape: (2,) Series: 'a' [i64] [ 1 2 ] >>> agnostic_get_column(df_pa) # doctest:+ELLIPSIS [ [ 1, 2 ] ] r;)rír.Ú get_columnr0rbs r6r%zDataFrame.get_columnîs6€ðr|‰|Ø × !Ñ !× ,Ñ ,šTÓ 2Ø—+‘+ðó ð r7có:—|jj|¬«S)aReturn an estimation of the total (heap) allocated size of the `DataFrame`. Estimated size is given in the specified unit (bytes by default). Arguments: unit: 'b', 'kb', 'mb', 'gb', 'tb', 'bytes', 'kilobytes', 'megabytes', 'gigabytes', or 'terabytes'. Returns: Integer or Float. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrameT >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_estimated_size(df_native: IntoDataFrameT) -> int | float: ... df = nw.from_native(df_native) ... return df.estimated_size() We can then pass either pandas, Polars or PyArrow to `agnostic_estimated_size`: >>> agnostic_estimated_size(df_pd) np.int64(330) >>> agnostic_estimated_size(df_pl) 51 >>> agnostic_estimated_size(df_pa) 63 )Úunit)r.Úestimated_size)r5r's r6r(zDataFrame.estimated_size,s€ðT×$Ñ$×3Ñ3žÐ3Ó>Ð>r7có—yr2r]©r5Úitems r6Ú __getitem__zDataFrame.__getitem__Xó€ØFIr7có—yr2r]r*s r6r,zDataFrame.__getitem__Zó€ØNQr7có—yr2r]r*s r6r,zDataFrame.__getitem__\r-r7có—yr2r]r*s r6r,zDataFrame.__getitem__^ó€ØKNr7có—yr2r]r*s r6r,zDataFrame.__getitem__`ó€ØCFr7có—yr2r]r*s r6r,zDataFrame.__getitem__br/r7có—yr2r]r*s r6r,zDataFrame.__getitem__dr-r7có—yr2r]r*s r6r,zDataFrame.__getitem__fr2r7có—yr2r]r*s r6r,zDataFrame.__getitem__hr4r7có—yr2r]r*s r6r,zDataFrame.__getitem__kó€Ø8;r7có—yr2r]r*s r6r,zDataFrame.__getitem__ns€Ø58r7có—yr2r]r*s r6r,zDataFrame.__getitem__qr:r7có—yr2r]r*s r6r,zDataFrame.__getitem__ts€Ø03r7có—yr2r]r*s r6r,zDataFrame.__getitem__ws€Ø>Ar7cóT—t|t«r|g}t|t«rAt|«dk(r3t|dttf«rdt |«›d}t |«‚t|t«rqt|«dk(rct|d«st|dt«rB|dtd«k(r|dtd«k(r|S|j|j|«St|t«st|t«r8t|«dk(r*|j|j||j¬«St|«s*t|t«st|«r-|jdk(r|j|j|«Sdt |«›}t |«‚)a— Extract column or slice of DataFrame. Arguments: item: How to slice dataframe. What happens depends on what is passed. It's easiest to explain by example. Suppose we have a Dataframe `df`: - `df['a']` extracts column `'a'` and returns a `Series`. - `df[0:2]` extracts the first two rows and returns a `DataFrame`. - `df[0:2, 'a']` extracts the first two rows from column `'a'` and returns a `Series`. - `df[0:2, 0]` extracts the first two rows from the first column and returns a `Series`. - `df[[0, 1], [0, 1, 2]]` extracts the first two rows and the first three columns and returns a `DataFrame` - `df[:, [0, 1, 2]]` extracts all rows from the first three columns and returns a `DataFrame`. - `df[:, ['a', 'c']]` extracts all rows and columns `'a'` and `'c'` and returns a `DataFrame`. - `df[['a', 'c']]` extracts all rows and columns `'a'` and `'c'` and returns a `DataFrame`. - `df[0: 2, ['a', 'c']]` extracts the first two rows and columns `'a'` and `'c'` and returns a `DataFrame` - `df[:, 0: 2]` extracts all rows from the first two columns and returns a `DataFrame` - `df[:, 'a': 'c']` extracts all rows and all columns positioned between `'a'` and `'c'` _inclusive_ and returns a `DataFrame`. For example, if the columns are `'a', 'd', 'c', 'b'`, then that would extract columns `'a'`, `'d'`, and `'c'`. Returns: A Narwhals Series, backed by a native series. Notes: - Integers are always interpreted as positions - Strings are always interpreted as column names. In contrast with Polars, pandas allows non-string column names. If you don't know whether the column name you're trying to extract is definitely a string (e.g. `df[df.columns[0]]`) then you should use `DataFrame.get_column` instead. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_slice(df_native: IntoDataFrame) -> IntoSeries: ... df = nw.from_native(df_native) ... return df["a"].to_native() We can then pass either pandas, Polars or PyArrow to `agnostic_slice`: >>> agnostic_slice(df_pd) 0 1 1 2 Name: a, dtype: int64 >>> agnostic_slice(df_pl) # doctest:+NORMALIZE_WHITESPACE shape: (2,) Series: 'a' [i64] [ 1 2 ] >>> agnostic_slice(df_pa) # doctest:+ELLIPSIS [ [ 1, 2 ] ] érzExpected str or slice, got: z]. Hint: if you were trying to get a single element out of a dataframe, use `DataFrame.item`.r€Nr;)rNr×ÚtuplerŠrQrRrSrÚslicer?r.rír0rÚndim©r5r+rUs r6r,zDataFrame.__getitem__zsy€ôz dœCÔ Ø6ˆDä tœUÔ #ܐD“ ˜Q’ܘD ™G€c¬3 ZÔ0ð/¬t°D«zšlð;3ð3ð ô ˜C“.Ð ä tœUÔ #ܐD“ ˜Q’Ü(šša©Ô1ŽZÀÀQÁÌÔ5OàA‰wœ% ›+Ò%š$šq©'ŽUž4³[Ò*@ؐ Ø×1Ñ1°$×2GÑ2GÈÑ2MÓNÐ NÜ dœCÔ €Z°ŽeÔ%<ÄÀTÃÈaÂØ—<‘<Ø×%Ñ% dÑ+Ø—k‘kð óð ô $ DÔ )ܘ$€Ô&ܘtÔ$š¯©°aªà×1Ñ1°$×2GÑ2GÈÑ2MÓNÐ Nð1Ž°d³° Ð=ˆCܘC“.Ð r7có—||jvSr2)ri)r5Úkeys r6Ú __contains__zDataFrame.__contains__ýs€Ød—l‘lÐ"Ð"r7.©Ú as_seriescó—yr2r]©r5rIs r6Úto_dictzDataFrame.to_dictó€ØTWr7có—yr2r]rKs r6rLzDataFrame.to_dicts€ØMPr7có—yr2r]rKs r6rLzDataFrame.to_dicts€ð9>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = { ... "A": [1, 2, 3, 4, 5], ... "fruits": ["banana", "banana", "apple", "apple", "banana"], ... "B": [5, 4, 3, 2, 1], ... "animals": ["beetle", "fly", "beetle", "beetle", "beetle"], ... "optional": [28, 300, None, 2, -30], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_to_dict( ... df_native: IntoDataFrame, ... ) -> dict[str, list[int | str | float | None]]: ... df = nw.from_native(df_native) ... return df.to_dict(as_series=False) We can then pass either pandas, Polars or PyArrow to `agnostic_to_dict`: >>> agnostic_to_dict(df_pd) {'A': [1, 2, 3, 4, 5], 'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'], 'B': [5, 4, 3, 2, 1], 'animals': ['beetle', 'fly', 'beetle', 'beetle', 'beetle'], 'optional': [28.0, 300.0, nan, 2.0, -30.0]} >>> agnostic_to_dict(df_pl) {'A': [1, 2, 3, 4, 5], 'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'], 'B': [5, 4, 3, 2, 1], 'animals': ['beetle', 'fly', 'beetle', 'beetle', 'beetle'], 'optional': [28, 300, None, 2, -30]} >>> agnostic_to_dict(df_pa) {'A': [1, 2, 3, 4, 5], 'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'], 'B': [5, 4, 3, 2, 1], 'animals': ['beetle', 'fly', 'beetle', 'beetle', 'beetle'], 'optional': [28, 300, None, 2, -30]} rHr;)r.rLrBrír0)r5rIrFÚvalues r6rLzDataFrame.to_dicts˜€ñ\ ð #'×"7Ñ"7×"?Ñ"?Ø'ð#@ó#ç‘%“'ð#ô ñ #‘JC˜ð T—\‘\ØØŸ+™+ð"óñð#ò ð ð×$Ñ$×,Ñ,°yÐ,ÓAÐAùós°(A8có8—|jj|«S)aaGet values at given row. !!! warning You should NEVER use this method to iterate over a DataFrame; if you require row-iteration you should strongly prefer use of iter_rows() instead. Arguments: index: Row number. Returns: A tuple of the values in the selected row. Notes: cuDF doesn't support this method. Examples: >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> from narwhals.typing import IntoDataFrame >>> from typing import Any >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a library-agnostic function to get the second row. >>> def agnostic_row(df_native: IntoDataFrame) -> tuple[Any, ...]: ... return nw.from_native(df_native).row(1) We can then pass either pandas, Polars or PyArrow to `agnostic_row`: >>> agnostic_row(df_pd) (2, 5) >>> agnostic_row(df_pl) (2, 5) >>> agnostic_row(df_pa) (, ) )r.Úrow)r5rŸs r6rSz DataFrame.rowBs€ðV×$Ñ$×(Ñ(šÓ/Ð/r7có*•—t‰||g|¢­i|€ŽS)u©Pipe function call. Arguments: function: Function to apply. args: Positional arguments to pass to function. kwargs: Keyword arguments to pass to function. Returns: The original object with the function applied. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "ba": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_pipe(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.pipe( ... lambda _df: _df.select( ... [x for x in _df.columns if len(x) == 1] ... ).to_native() ... ) We can then pass either pandas, Polars or PyArrow to `agnostic_pipe`: >>> agnostic_pipe(df_pd) a 0 1 1 2 2 3 >>> agnostic_pipe(df_pl) shape: (3, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ >>> agnostic_pipe(df_pa) pyarrow.Table a: int64 ---- a: [[1,2,3]] ©Úsuperr_©r5r^rCrDr=s €r6r_zDataFrame.pipepsø€ôp‰w‰|˜HÐ6 tÒ6švÑ6Ð6r7có$•—t‰||¬«S)uhDrop rows that contain null values. Arguments: subset: Column name(s) for which null values are considered. If set to None (default), use all columns. Returns: The original object with the rows removed that contained the null values. Notes: pandas handles null values differently from Polars and PyArrow. See [null_handling](../pandas_like_concepts/null_handling.md) for reference. Examples: >>> import polars as pl >>> import pandas as pd >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1.0, 2.0, None], "ba": [1.0, None, 2.0]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_drop_nulls(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.drop_nulls().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_drop_nulls`: >>> agnostic_drop_nulls(df_pd) a ba 0 1.0 1.0 >>> agnostic_drop_nulls(df_pl) shape: (1, 2) ┌─────┬─────┐ │ a ┆ ba │ │ --- ┆ --- │ │ f64 ┆ f64 │ ╞═════╪═════╡ │ 1.0 ┆ 1.0 │ └─────┮─────┘ >>> agnostic_drop_nulls(df_pa) pyarrow.Table a: double ba: double ---- a: [[1]] ba: [[1]] re©rVrg©r5rfr=s €r6rgzDataFrame.drop_nullsªsø€ôn‰wÑ!šÐ!Ó0Ð0r7có"•—t‰||«S)uÊInsert column which enumerates rows. Arguments: name: The name of the column as a string. The default is "index". Returns: The original object with the column added. Examples: Construct pandas as polars DataFrames: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_with_row_index(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_row_index().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_with_row_index`: >>> agnostic_with_row_index(df_pd) index a b 0 0 1 4 1 1 2 5 2 2 3 6 >>> agnostic_with_row_index(df_pl) shape: (3, 3) ┌───────┬─────┬─────┐ │ index ┆ a ┆ b │ │ --- ┆ --- ┆ --- │ │ u32 ┆ i64 ┆ i64 │ ╞═══════╪═════╪═════╡ │ 0 ┆ 1 ┆ 4 │ │ 1 ┆ 2 ┆ 5 │ │ 2 ┆ 3 ┆ 6 │ └───────┮─────┮─────┘ >>> agnostic_with_row_index(df_pa) pyarrow.Table index: int64 a: int64 b: int64 ---- index: [[0,1,2]] a: [[1,2,3]] b: [[4,5,6]] ©rVra©r5rcr=s €r6razDataFrame.with_row_indexãsø€ôr‰wÑ% dÓ+Ð+r7có•—t‰|S)aaGet an ordered mapping of column names to their data type. Returns: A Narwhals Schema object that displays the mapping of column names. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.schema import Schema >>> from narwhals.typing import IntoFrame >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_schema(df_native: IntoFrame) -> Schema: ... df = nw.from_native(df_native) ... return df.schema We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_schema`: >>> agnostic_schema(df_pd) Schema({'foo': Int64, 'bar': Float64, 'ham': String}) >>> agnostic_schema(df_pl) Schema({'foo': Int64, 'bar': Float64, 'ham': String}) >>> agnostic_schema(df_pa) Schema({'foo': Int64, 'bar': Float64, 'ham': String}) ©rVrW©r5r=s €r6rWzDataFrame.schemasø€ôN‰w‰~Ðr7có •—t‰|«S)a“Get an ordered mapping of column names to their data type. Returns: A Narwhals Schema object that displays the mapping of column names. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.schema import Schema >>> from narwhals.typing import IntoFrame >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_collect_schema(df_native: IntoFrame) -> Schema: ... df = nw.from_native(df_native) ... return df.collect_schema() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_collect_schema`: >>> agnostic_collect_schema(df_pd) Schema({'foo': Int64, 'bar': Float64, 'ham': String}) >>> agnostic_collect_schema(df_pl) Schema({'foo': Int64, 'bar': Float64, 'ham': String}) >>> agnostic_collect_schema(df_pa) Schema({'foo': Int64, 'bar': Float64, 'ham': String}) ©rVrZr`s €r6rZzDataFrame.collect_schemaGsø€ôL‰wÑ%Ó'Ð'r7có•—t‰|S)a>Get column names. Returns: The column names stored in a list. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_columns(df_native: IntoFrame) -> list[str]: ... df = nw.from_native(df_native) ... return df.columns We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_columns`: >>> agnostic_columns(df_pd) ['foo', 'bar', 'ham'] >>> agnostic_columns(df_pl) ['foo', 'bar', 'ham'] >>> agnostic_columns(df_pa) ['foo', 'bar', 'ham'] ©rVrir`s €r6rizDataFrame.columnsosø€ôD‰w‰Ðr7F©Únamedcó—yr2r]©r5rfs r6ÚrowszDataFrame.rows“s€ØORr7có—yr2r]rhs r6rizDataFrame.rows–s€ØEHr7có—yr2r]rhs r6rizDataFrame.rows™rMr7có:—|jj|¬«S)aÂReturns all data in the DataFrame as a list of rows of python-native values. Arguments: named: By default, each row is returned as a tuple of values given in the same order as the frame columns. Setting named=True will return rows of dictionaries instead. Returns: The data as a list of rows. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_rows(df_native: IntoDataFrame, *, named: bool): ... return nw.from_native(df_native, eager_only=True).rows(named=named) We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_rows`: >>> agnostic_rows(df_pd, named=False) [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> agnostic_rows(df_pd, named=True) [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] >>> agnostic_rows(df_pl, named=False) [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> agnostic_rows(df_pl, named=True) [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] >>> agnostic_rows(df_pa, named=False) [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> agnostic_rows(df_pa, named=True) [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] re)r.rirhs r6rizDataFrame.rowsœs€ðZ×$Ñ$×)Ñ)°Ð)Ó6Ð6r7)Ú buffer_sizecó—yr2r]©r5rfrms r6Ú iter_rowszDataFrame.iter_rowsËs€ð%(r7có—yr2r]ros r6rpzDataFrame.iter_rowsÐs€ð$'r7có—yr2r]ros r6rpzDataFrame.iter_rowsÕs €ð@Cr7i©rfrmcó<—|jj||¬«S)a Returns an iterator over the DataFrame of rows of python-native values. Arguments: named: By default, each row is returned as a tuple of values given in the same order as the frame columns. Setting named=True will return rows of dictionaries instead. buffer_size: Determines the number of rows that are buffered internally while iterating over the data. See https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.iter_rows.html Returns: An iterator over the DataFrame of rows. Notes: cuDF doesn't support this method. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_iter_rows(df_native: IntoDataFrame, *, named: bool): ... return nw.from_native(df_native, eager_only=True).iter_rows(named=named) We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_iter_rows`: >>> [row for row in agnostic_iter_rows(df_pd, named=False)] [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> [row for row in agnostic_iter_rows(df_pd, named=True)] [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] >>> [row for row in agnostic_iter_rows(df_pl, named=False)] [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> [row for row in agnostic_iter_rows(df_pl, named=True)] [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] >>> [row for row in agnostic_iter_rows(df_pa, named=False)] [(1, 6.0, 'a'), (2, 7.0, 'b'), (3, 8.0, 'c')] >>> [row for row in agnostic_iter_rows(df_pa, named=True)] [{'foo': 1, 'bar': 6.0, 'ham': 'a'}, {'foo': 2, 'bar': 7.0, 'ham': 'b'}, {'foo': 3, 'bar': 8.0, 'ham': 'c'}] rs)r.rpros r6rpzDataFrame.iter_rowsÚs!€ðf×$Ñ$×.Ñ.°UÈ Ð.ÓTÐTr7có"•—t‰||i|€ŽS)uß Add columns to this DataFrame. Added columns will replace existing columns with the same name. Arguments: *exprs: Column(s) to add, specified as positional arguments. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. **named_exprs: Additional columns to add, specified as keyword arguments. The columns will be renamed to the keyword used. Returns: DataFrame: A new DataFrame with the columns added. Note: Creating a new DataFrame using this method does not create a new copy of existing data. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": [1, 2, 3, 4], ... "b": [0.5, 4, 10, 13], ... "c": [True, True, False, True], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function in which we pass an expression to add it as a new column: >>> def agnostic_with_columns(df_native: IntoFrameT) -> IntoFrameT: ... return ( ... nw.from_native(df_native) ... .with_columns((nw.col("a") * 2).alias("a*2")) ... .to_native() ... ) We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_with_columns`: >>> agnostic_with_columns(df_pd) a b c a*2 0 1 0.5 True 2 1 2 4.0 True 4 2 3 10.0 False 6 3 4 13.0 True 8 >>> agnostic_with_columns(df_pl) shape: (4, 4) ┌─────┬──────┬───────┬─────┐ │ a ┆ b ┆ c ┆ a*2 │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ bool ┆ i64 │ ╞═════╪══════╪═══════╪═════╡ │ 1 ┆ 0.5 ┆ true ┆ 2 │ │ 2 ┆ 4.0 ┆ true ┆ 4 │ │ 3 ┆ 10.0 ┆ false ┆ 6 │ │ 4 ┆ 13.0 ┆ true ┆ 8 │ └─────┮──────┮───────┮─────┘ >>> agnostic_with_columns(df_pa) pyarrow.Table a: int64 b: double c: bool a*2: int64 ---- a: [[1,2,3,4]] b: [[0.5,4,10,13]] c: [[true,true,false,true]] a*2: [[2,4,6,8]] ©rVrk©r5rmrnr=s €r6rkzDataFrame.with_columnssø€ô`‰wÑ# UÐ:škÑ:Ð:r7có"•—t‰||i|€ŽS)u–Select columns from this DataFrame. Arguments: *exprs: Column(s) to select, specified as positional arguments. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. **named_exprs: Additional columns to select, specified as keyword arguments. The columns will be renamed to the keyword used. Returns: The dataframe containing only the selected columns. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "foo": [1, 2, 3], ... "bar": [6, 7, 8], ... "ham": ["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 in which we pass the name of a column to select that column. >>> def agnostic_single_select(df_native: IntoFrameT) -> IntoFrameT: ... return nw.from_native(df_native).select("foo").to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_single_select`: >>> agnostic_single_select(df_pd) foo 0 1 1 2 2 3 >>> agnostic_single_select(df_pl) shape: (3, 1) ┌─────┐ │ foo │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ >>> agnostic_single_select(df_pa) pyarrow.Table foo: int64 ---- foo: [[1,2,3]] Multiple columns can be selected by passing a list of column names. >>> def agnostic_multi_select(df_native: IntoFrameT) -> IntoFrameT: ... return nw.from_native(df_native).select(["foo", "bar"]).to_native() >>> agnostic_multi_select(df_pd) foo bar 0 1 6 1 2 7 2 3 8 >>> agnostic_multi_select(df_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 6 │ │ 2 ┆ 7 │ │ 3 ┆ 8 │ └─────┮─────┘ >>> agnostic_multi_select(df_pa) pyarrow.Table foo: int64 bar: int64 ---- foo: [[1,2,3]] bar: [[6,7,8]] Multiple columns can also be selected using positional arguments instead of a list. Expressions are also accepted. >>> def agnostic_select(df_native: IntoFrameT) -> IntoFrameT: ... return ( ... nw.from_native(df_native) ... .select(nw.col("foo"), nw.col("bar") + 1) ... .to_native() ... ) >>> agnostic_select(df_pd) foo bar 0 1 7 1 2 8 2 3 9 >>> agnostic_select(df_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 7 │ │ 2 ┆ 8 │ │ 3 ┆ 9 │ └─────┮─────┘ >>> agnostic_select(df_pa) pyarrow.Table foo: int64 bar: int64 ---- foo: [[1,2,3]] bar: [[7,8,9]] Use keyword arguments to easily name your expression inputs. >>> def agnostic_select_w_kwargs(df_native: IntoFrameT) -> IntoFrameT: ... return ( ... nw.from_native(df_native) ... .select(threshold=nw.col("foo") * 2) ... .to_native() ... ) >>> agnostic_select_w_kwargs(df_pd) threshold 0 2 1 4 2 6 >>> agnostic_select_w_kwargs(df_pl) shape: (3, 1) ┌───────────┐ │ threshold │ │ --- │ │ i64 │ ╞═══════════╡ │ 2 │ │ 4 │ │ 6 │ └───────────┘ >>> agnostic_select_w_kwargs(df_pa) pyarrow.Table threshold: int64 ---- threshold: [[2,4,6]] ©rVrprws €r6rpzDataFrame.selectasø€ô|‰w‰~˜uÐ4š Ñ4Ð4r7có"•—t‰||«S)u~Rename column names. Arguments: mapping: Key value pairs that map from old name to new name. Returns: The dataframe with the specified columns renamed. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"foo": [1, 2, 3], "bar": [6, 7, 8], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_rename(df_native: IntoFrameT) -> IntoFrameT: ... return nw.from_native(df_native).rename({"foo": "apple"}).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_rename`: >>> agnostic_rename(df_pd) apple bar ham 0 1 6 a 1 2 7 b 2 3 8 c >>> agnostic_rename(df_pl) shape: (3, 3) ┌───────┬─────┬─────┐ │ apple ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═══════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └───────┮─────┮─────┘ >>> agnostic_rename(df_pa) pyarrow.Table apple: int64 bar: int64 ham: string ---- apple: [[1,2,3]] bar: [[6,7,8]] ham: [["a","b","c"]] ©rVrr©r5rsr=s €r6rrzDataFrame.renamesø€ôl‰w‰~˜gÓ&Ð&r7có"•—t‰||«S)uüGet the first `n` rows. Arguments: n: Number of rows to return. If a negative value is passed, return all rows except the last `abs(n)`. Returns: A subset of the dataframe of shape (n, n_columns). Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "foo": [1, 2, 3, 4, 5], ... "bar": [6, 7, 8, 9, 10], ... "ham": ["a", "b", "c", "d", "e"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function that gets the first 3 rows. >>> def agnostic_head(df_native: IntoFrameT) -> IntoFrameT: ... return nw.from_native(df_native).head(3).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_head`: >>> agnostic_head(df_pd) foo bar ham 0 1 6 a 1 2 7 b 2 3 8 c >>> agnostic_head(df_pl) shape: (3, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ >>> agnostic_head(df_pa) pyarrow.Table foo: int64 bar: int64 ham: string ---- foo: [[1,2,3]] bar: [[6,7,8]] ham: [["a","b","c"]] ©rVru©r5rwr=s €r6ruzDataFrame.head9óø€ôv‰w‰|˜A‹Ðr7có"•—t‰||«S)uüGet the last `n` rows. Arguments: n: Number of rows to return. If a negative value is passed, return all rows except the first `abs(n)`. Returns: A subset of the dataframe of shape (n, n_columns). Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "foo": [1, 2, 3, 4, 5], ... "bar": [6, 7, 8, 9, 10], ... "ham": ["a", "b", "c", "d", "e"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function that gets the last 3 rows. >>> def agnostic_tail(df_native: IntoFrameT) -> IntoFrameT: ... return nw.from_native(df_native).tail(3).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_tail`: >>> agnostic_tail(df_pd) foo bar ham 2 3 8 c 3 4 9 d 4 5 10 e >>> agnostic_tail(df_pl) shape: (3, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 3 ┆ 8 ┆ c │ │ 4 ┆ 9 ┆ d │ │ 5 ┆ 10 ┆ e │ └─────┮─────┮─────┘ >>> agnostic_tail(df_pa) pyarrow.Table foo: int64 bar: int64 ham: string ---- foo: [[3,4,5]] bar: [[8,9,10]] ham: [["c","d","e"]] ©rVrzrs €r6rzzDataFrame.tailvr€r7r|có4•—t‰|t|«d|iŽS)um Remove columns from the dataframe. Returns: The dataframe with the specified columns removed. Arguments: *columns: Names of the columns that should be removed from the dataframe. strict: Validate that all column names exist in the schema and throw an exception if a column name does not exist in the schema. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_drop(df_native: IntoFrameT) -> IntoFrameT: ... return nw.from_native(df_native).drop("ham").to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_drop`: >>> agnostic_drop(df_pd) foo bar 0 1 6.0 1 2 7.0 2 3 8.0 >>> agnostic_drop(df_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ f64 │ ╞═════╪═════╡ │ 1 ┆ 6.0 │ │ 2 ┆ 7.0 │ │ 3 ┆ 8.0 │ └─────┮─────┘ >>> agnostic_drop(df_pa) pyarrow.Table foo: int64 bar: double ---- foo: [[1,2,3]] bar: [[6,7,8]] Use positional arguments to drop multiple columns. >>> def agnostic_drop_multi(df_native: IntoFrameT) -> IntoFrameT: ... return nw.from_native(df_native).drop("foo", "ham").to_native() >>> agnostic_drop_multi(df_pd) bar 0 6.0 1 7.0 2 8.0 >>> agnostic_drop_multi(df_pl) shape: (3, 1) ┌─────┐ │ bar │ │ --- │ │ f64 │ ╞═════╡ │ 6.0 │ │ 7.0 │ │ 8.0 │ └─────┘ >>> agnostic_drop_multi(df_pa) pyarrow.Table bar: double ---- bar: [[6,7,8]] r}©rVr~r©r5r}rir=s €r6r~zDataFrame.drop³sø€ôd‰w‰|œW WÓ-Ð=°fÑ=Ð=r7Úany©ÚkeepÚmaintain_ordercó°—|dvrdd›d|›}t|«‚t|t«r|g}|j|jj |||¬««S)u: Drop duplicate rows from this dataframe. Arguments: subset: Column name(s) to consider when identifying duplicate rows. keep: {'first', 'last', 'any', 'none'} Which of the duplicate rows to keep. * 'any': Does not give any guarantee of which row is kept. This allows more optimizations. * 'none': Don't keep duplicate rows. * 'first': Keep first unique row. * 'last': Keep last unique row. maintain_order: Keep the same order as the original DataFrame. This may be more expensive to compute. Returns: The dataframe with the duplicate rows removed. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "foo": [1, 2, 3, 1], ... "bar": ["a", "a", "a", "a"], ... "ham": ["b", "b", "b", "b"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_unique(df_native: IntoFrameT) -> IntoFrameT: ... return nw.from_native(df_native).unique(["bar", "ham"]).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_unique`: >>> agnostic_unique(df_pd) foo bar ham 0 1 a b >>> agnostic_unique(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ str ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ a ┆ b │ └─────┮─────┮─────┘ >>> agnostic_unique(df_pa) pyarrow.Table foo: int64 bar: string ham: string ---- foo: [[1]] bar: [["a"]] ham: [["b"]] >r†ÚlastÚnoneÚfirstz Expected )r†rŒrr‹z, got: )rfrˆr‰)r§rNrQr?r.Úunique©r5rfrˆr‰rUs r6rŽzDataFrame.uniquesp€ðL Ð7Ñ 7ØÐ<Ð=žWÀTÀFÐKˆCܘS“/Ð !Ü fœcÔ "ؐXˆFØ×-Ñ-Ø × !Ñ !× (Ñ (Ø Džð )ó ó ð r7có"•—t‰||i|€ŽS)uCFilter the rows in the DataFrame based on one or more predicate expressions. The original order of the remaining rows is preserved. Arguments: *predicates: Expression(s) that evaluates to a boolean Series. Can also be a (single!) boolean list. **constraints: Column filters; use `name = value` to filter columns by the supplied value. Each constraint will behave the same as `nw.col(name).eq(value)`, and will be implicitly joined with the other filter conditions using &. Returns: The filtered dataframe. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "foo": [1, 2, 3], ... "bar": [6, 7, 8], ... "ham": ["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 in which we filter on one condition. >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter(nw.col("foo") > 1).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_filter`: >>> agnostic_filter(df_pd) foo bar ham 1 2 7 b 2 3 8 c >>> agnostic_filter(df_pl) shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ >>> agnostic_filter(df_pa) pyarrow.Table foo: int64 bar: int64 ham: string ---- foo: [[2,3]] bar: [[7,8]] ham: [["b","c"]] Filter on multiple conditions, combined with and/or operators: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter((nw.col("foo") < 3) & (nw.col("ham") == "a")).to_native() >>> agnostic_filter(df_pd) foo bar ham 0 1 6 a >>> agnostic_filter(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ >>> agnostic_filter(df_pa) pyarrow.Table foo: int64 bar: int64 ham: string ---- foo: [[1]] bar: [[6]] ham: [["a"]] >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... dframe = df.filter( ... (nw.col("foo") == 1) | (nw.col("ham") == "c") ... ).to_native() ... return dframe >>> agnostic_filter(df_pd) foo bar ham 0 1 6 a 2 3 8 c >>> agnostic_filter(df_pl) shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ >>> agnostic_filter(df_pa) pyarrow.Table foo: int64 bar: int64 ham: string ---- foo: [[1,3]] bar: [[6,8]] ham: [["a","c"]] Provide multiple filters using `*args` syntax: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... dframe = df.filter( ... nw.col("foo") <= 2, ... ~nw.col("ham").is_in(["b", "c"]), ... ).to_native() ... return dframe >>> agnostic_filter(df_pd) foo bar ham 0 1 6 a >>> agnostic_filter(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ >>> agnostic_filter(df_pa) pyarrow.Table foo: int64 bar: int64 ham: string ---- foo: [[1]] bar: [[6]] ham: [["a"]] Provide multiple filters using `**kwargs` syntax: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter(foo=2, ham="b").to_native() >>> agnostic_filter(df_pd) foo bar ham 1 2 7 b >>> agnostic_filter(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ └─────┮─────┮─────┘ >>> agnostic_filter(df_pa) pyarrow.Table foo: int64 bar: int64 ham: string ---- foo: [[2]] bar: [[7]] ham: [["b"]] )rVr)r5rŽrr=s €r6rzDataFrame.filterXsø€ôj‰w‰~˜zÐ9š[Ñ9Ð9r7©Údrop_null_keysc󜇇—ddlmŠddlm}ddlmŠt |«}tˆˆfd„|D««r d}t|«‚||g|¢­d|iŽS)ui Start a group by operation. Arguments: *keys: Column(s) to group by. Accepts multiple columns names as a list. drop_null_keys: if True, then groups where any key is null won't be included in the result. Returns: GroupBy: Object which can be used to perform aggregations. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrameT >>> data = { ... "a": ["a", "b", "a", "b", "c"], ... "b": [1, 2, 1, 3, 3], ... "c": [5, 4, 3, 2, 1], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function in which we group by one column and call `agg` to compute the grouped sum of another column. >>> def agnostic_group_by_agg(df_native: IntoDataFrameT) -> IntoDataFrameT: ... df = nw.from_native(df_native, eager_only=True) ... return df.group_by("a").agg(nw.col("b").sum()).sort("a").to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_group_by_agg`: >>> agnostic_group_by_agg(df_pd) a b 0 a 2 1 b 5 2 c 3 >>> agnostic_group_by_agg(df_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ str ┆ i64 │ ╞═════╪═════╡ │ a ┆ 2 │ │ b ┆ 5 │ │ c ┆ 3 │ └─────┮─────┘ >>> agnostic_group_by_agg(df_pa) pyarrow.Table a: string b: int64 ---- a: [["a","b","c"]] b: [[2,5,3]] Group by multiple columns by passing a list of column names. >>> def agnostic_group_by_agg(df_native: IntoDataFrameT) -> IntoDataFrameT: ... df = nw.from_native(df_native, eager_only=True) ... return df.group_by(["a", "b"]).agg(nw.max("c")).sort("a", "b").to_native() >>> agnostic_group_by_agg(df_pd) a b c 0 a 1 5 1 b 2 4 2 b 3 2 3 c 3 1 >>> agnostic_group_by_agg(df_pl) shape: (4, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ a ┆ 1 ┆ 5 │ │ b ┆ 2 ┆ 4 │ │ b ┆ 3 ┆ 2 │ │ c ┆ 3 ┆ 1 │ └─────┮─────┮─────┘ >>> agnostic_group_by_agg(df_pa) pyarrow.Table a: string b: int64 c: int64 ---- a: [["a","b","b","c"]] b: [[1,2,3,3]] c: [[5,4,2,1]] rrIrr"c3ó:•K—|]}t|‰‰f«–—Œy­wr2©rN©r…r†rJr#s €€r6r‡z%DataFrame.group_by..t óøèø€Ð@±i°Œz˜!˜d F˜^×,±iùóƒúˆ`group_by` with expression or Series keys is not (yet?) supported. Hint: instead of `df.group_by(nw.col('a'))`, use `df.group_by('a')`.r’) rLrJÚnarwhals.group_byrrMr#rr†rŠ)r5r’ÚkeysrÚ flat_keysrUrJr#s @@r6Úgroup_byzDataFrame.group_by sSù€õ@ 'Ý-Ý*ä˜D“Mˆ Ü Ô@±iÓ@Ô @ðWð ô& cÓ*Ð *ِtÐG˜iÒGžÑGÐGr7rcó,•—t‰||g|¢­||dœŽS)u Sort the dataframe by the given columns. Arguments: by: Column(s) names to sort by. *more_by: Additional columns to sort by, specified as positional arguments. descending: Sort in descending order. When sorting by multiple columns, can be specified per column by passing a sequence of booleans. nulls_last: Place null values last. Returns: The sorted dataframe. Warning: Unlike Polars, it is not possible to specify a sequence of booleans for `nulls_last` in order to control per-column behaviour. Instead a single boolean is applied for all `by` columns. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": [1, 2, None], ... "b": [6.0, 5.0, 4.0], ... "c": ["a", "c", "b"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function in which we sort by multiple columns in different orders >>> def agnostic_sort(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.sort("c", "a", descending=[False, True]).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_sort`: >>> agnostic_sort(df_pd) a b c 0 1.0 6.0 a 2 NaN 4.0 b 1 2.0 5.0 c >>> agnostic_sort(df_pl) shape: (3, 3) ┌──────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str │ ╞══════╪═════╪═════╡ │ 1 ┆ 6.0 ┆ a │ │ null ┆ 4.0 ┆ b │ │ 2 ┆ 5.0 ┆ c │ └──────┮─────┮─────┘ >>> agnostic_sort(df_pa) pyarrow.Table a: int64 b: double c: string ---- a: [[1,null,2]] b: [[6,4,5]] c: [["a","b","c"]] r©rVr”©r5r•r‘r’r–r=s €r6r”zDataFrame.sort| s!ø€ôV‰w‰|˜BÐW ÑW°ZÈJÒWÐWr7r—r˜có.•—t‰|||||||¬«S)u0 Join in SQL-like fashion. Arguments: other: DataFrame to join with. on: Name(s) of the join columns in both DataFrames. If set, `left_on` and `right_on` should be None. how: Join strategy. * *inner*: Returns rows that have matching values in both tables. * *left*: Returns all rows from the left table, and the matched rows from the right table. * *cross*: Returns the Cartesian product of rows from both tables. * *semi*: Filter rows that have a match in the right table. * *anti*: Filter rows that do not have a match in the right table. left_on: Join column of the left DataFrame. right_on: Join column of the right DataFrame. suffix: Suffix to append to columns with a duplicate name. Returns: A new joined DataFrame Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> data_other = { ... "apple": ["x", "y", "z"], ... "ham": ["a", "b", "d"], ... } >>> df_pd = pd.DataFrame(data) >>> other_pd = pd.DataFrame(data_other) >>> df_pl = pl.DataFrame(data) >>> other_pl = pl.DataFrame(data_other) >>> df_pa = pa.table(data) >>> other_pa = pa.table(data_other) Let's define a dataframe-agnostic function in which we join over "ham" column: >>> def agnostic_join_on_ham( ... df_native: IntoFrameT, other_native: IntoFrameT ... ) -> IntoFrameT: ... df = nw.from_native(df_native) ... other = nw.from_native(other_native) ... return df.join(other, left_on="ham", right_on="ham").to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_join_on_ham`: >>> agnostic_join_on_ham(df_pd, other_pd) foo bar ham apple 0 1 6.0 a x 1 2 7.0 b y >>> agnostic_join_on_ham(df_pl, other_pl) shape: (2, 4) ┌─────┬─────┬─────┬───────┐ │ foo ┆ bar ┆ ham ┆ apple │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str ┆ str │ ╞═════╪═════╪═════╪═══════╡ │ 1 ┆ 6.0 ┆ a ┆ x │ │ 2 ┆ 7.0 ┆ b ┆ y │ └─────┮─────┮─────┮───────┘ >>> agnostic_join_on_ham(df_pa, other_pa) pyarrow.Table foo: int64 bar: double ham: string apple: string ---- foo: [[1,2]] bar: [[6,7]] ham: [["a","b"]] apple: [["x","y"]] ©r¥r™ršrªr›©rVrš©r5r©rªr¥r™ršr›r=s €r6ršzDataFrame.joinÉ s)ø€ô|‰w‰|Ø s G°hÀ2Èfðó ð r7r²r³c ó2•—t‰ |||||||||¬«S)uñ#Perform an asof join. This is similar to a left-join except that we match on nearest key rather than equal keys. Both DataFrames must be sorted by the asof_join key. Arguments: other: DataFrame to join with. left_on: Name(s) of the left join column(s). right_on: Name(s) of the right join column(s). on: Join column of both DataFrames. If set, left_on and right_on should be None. by_left: join on these columns before doing asof join. by_right: join on these columns before doing asof join. by: join on these columns before doing asof join. strategy: Join strategy. The default is "backward". * *backward*: selects the last row in the right DataFrame whose "on" key is less than or equal to the left's key. * *forward*: selects the first row in the right DataFrame whose "on" key is greater than or equal to the left's key. * *nearest*: search selects the last row in the right DataFrame whose value is nearest to the left's key. Returns: A new joined DataFrame Examples: >>> from datetime import datetime >>> from typing import Literal >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data_gdp = { ... "datetime": [ ... datetime(2016, 1, 1), ... datetime(2017, 1, 1), ... datetime(2018, 1, 1), ... datetime(2019, 1, 1), ... datetime(2020, 1, 1), ... ], ... "gdp": [4164, 4411, 4566, 4696, 4827], ... } >>> data_population = { ... "datetime": [ ... datetime(2016, 3, 1), ... datetime(2018, 8, 1), ... datetime(2019, 1, 1), ... ], ... "population": [82.19, 82.66, 83.12], ... } >>> gdp_pd = pd.DataFrame(data_gdp) >>> population_pd = pd.DataFrame(data_population) >>> gdp_pl = pl.DataFrame(data_gdp).sort("datetime") >>> population_pl = pl.DataFrame(data_population).sort("datetime") Let's define a dataframe-agnostic function in which we join over "datetime" column: >>> def agnostic_join_asof_datetime( ... df_native: IntoFrameT, ... other_native: IntoFrameT, ... strategy: Literal["backward", "forward", "nearest"], ... ) -> IntoFrameT: ... df = nw.from_native(df_native) ... other = nw.from_native(other_native) ... return df.join_asof(other, on="datetime", strategy=strategy).to_native() We can then pass any supported library such as Pandas or Polars to `agnostic_join_asof_datetime`: >>> agnostic_join_asof_datetime(population_pd, gdp_pd, strategy="backward") datetime population gdp 0 2016-03-01 82.19 4164 1 2018-08-01 82.66 4566 2 2019-01-01 83.12 4696 >>> agnostic_join_asof_datetime(population_pl, gdp_pl, strategy="backward") shape: (3, 3) ┌─────────────────────┬────────────┬──────┐ │ datetime ┆ population ┆ gdp │ │ --- ┆ --- ┆ --- │ │ datetime[ÎŒs] ┆ f64 ┆ i64 │ ╞═════════════════════╪════════════╪══════╡ │ 2016-03-01 00:00:00 ┆ 82.19 ┆ 4164 │ │ 2018-08-01 00:00:00 ┆ 82.66 ┆ 4566 │ │ 2019-01-01 00:00:00 ┆ 83.12 ┆ 4696 │ └─────────────────────┮────────────┮──────┘ Here is a real-world times-series example that uses `by` argument. >>> from datetime import datetime >>> import narwhals as nw >>> import pandas as pd >>> import polars as pl >>> data_quotes = { ... "datetime": [ ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 30), ... datetime(2016, 5, 25, 13, 30, 0, 41), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 49), ... datetime(2016, 5, 25, 13, 30, 0, 72), ... datetime(2016, 5, 25, 13, 30, 0, 75), ... ], ... "ticker": [ ... "GOOG", ... "MSFT", ... "MSFT", ... "MSFT", ... "GOOG", ... "AAPL", ... "GOOG", ... "MSFT", ... ], ... "bid": [720.50, 51.95, 51.97, 51.99, 720.50, 97.99, 720.50, 52.01], ... "ask": [720.93, 51.96, 51.98, 52.00, 720.93, 98.01, 720.88, 52.03], ... } >>> data_trades = { ... "datetime": [ ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 38), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... ], ... "ticker": ["MSFT", "MSFT", "GOOG", "GOOG", "AAPL"], ... "price": [51.95, 51.95, 720.77, 720.92, 98.0], ... "quantity": [75, 155, 100, 100, 100], ... } >>> quotes_pd = pd.DataFrame(data_quotes) >>> trades_pd = pd.DataFrame(data_trades) >>> quotes_pl = pl.DataFrame(data_quotes).sort("datetime") >>> trades_pl = pl.DataFrame(data_trades).sort("datetime") Let's define a dataframe-agnostic function in which we join over "datetime" and by "ticker" columns: >>> def agnostic_join_asof_datetime_by_ticker( ... df_native: IntoFrameT, other_native: IntoFrameT ... ) -> IntoFrameT: ... df = nw.from_native(df_native) ... other = nw.from_native(other_native) ... return df.join_asof(other, on="datetime", by="ticker").to_native() We can now pass either pandas or Polars to the function: >>> agnostic_join_asof_datetime_by_ticker(trades_pd, quotes_pd) datetime ticker price quantity bid ask 0 2016-05-25 13:30:00.000023 MSFT 51.95 75 51.95 51.96 1 2016-05-25 13:30:00.000038 MSFT 51.95 155 51.97 51.98 2 2016-05-25 13:30:00.000048 GOOG 720.77 100 720.50 720.93 3 2016-05-25 13:30:00.000048 GOOG 720.92 100 720.50 720.93 4 2016-05-25 13:30:00.000048 AAPL 98.00 100 NaN NaN >>> agnostic_join_asof_datetime_by_ticker(trades_pl, quotes_pl) shape: (5, 6) ┌────────────────────────────┬────────┬────────┬──────────┬───────┬────────┐ │ datetime ┆ ticker ┆ price ┆ quantity ┆ bid ┆ ask │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ datetime[ÎŒs] ┆ str ┆ f64 ┆ i64 ┆ f64 ┆ f64 │ ╞════════════════════════════╪════════╪════════╪══════════╪═══════╪════════╡ │ 2016-05-25 13:30:00.000023 ┆ MSFT ┆ 51.95 ┆ 75 ┆ 51.95 ┆ 51.96 │ │ 2016-05-25 13:30:00.000038 ┆ MSFT ┆ 51.95 ┆ 155 ┆ 51.97 ┆ 51.98 │ │ 2016-05-25 13:30:00.000048 ┆ GOOG ┆ 720.77 ┆ 100 ┆ 720.5 ┆ 720.93 │ │ 2016-05-25 13:30:00.000048 ┆ GOOG ┆ 720.92 ┆ 100 ┆ 720.5 ┆ 720.93 │ │ 2016-05-25 13:30:00.000048 ┆ AAPL ┆ 98.0 ┆ 100 ┆ null ┆ null │ └────────────────────────────┮────────┮────────┮──────────┮───────┮────────┘ r³©rVrº© r5r©r™ršrªrŽrµr•r¶r=s €r6rºzDataFrame.join_asof+ s5ø€ôd‰wÑ Ø ØØØØØØØð!ó  ð r7cól—|j|jj«|j¬«S)aŽGet a mask of all duplicated rows in this DataFrame. Returns: A new Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> data = { ... "a": [1, 2, 3, 1], ... "b": ["x", "y", "z", "x"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_is_duplicated(df_native: IntoDataFrame) -> IntoSeries: ... df = nw.from_native(df_native, eager_only=True) ... return df.is_duplicated().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_is_duplicated`: >>> agnostic_is_duplicated(df_pd) 0 True 1 False 2 False 3 True dtype: bool >>> agnostic_is_duplicated(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [bool] [ true false false true ] >>> agnostic_is_duplicated(df_pa) # doctest: +ELLIPSIS [ [ true, false, false, true ] ] r;)rír.Ú is_duplicatedr0r4s r6r©zDataFrame.is_duplicatedé s4€ðr|‰|Ø × !Ñ !× /Ñ /Ó 1Ø—+‘+ðó ð r7có6—|jj«S)aàCheck if the dataframe is empty. Returns: A boolean indicating whether the dataframe is empty (True) or not (False). Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame Let's define a dataframe-agnostic function that filters rows in which "foo" values are greater than 10, and then checks if the result is empty or not: >>> def agnostic_is_empty(df_native: IntoDataFrame) -> bool: ... df = nw.from_native(df_native, eager_only=True) ... return df.filter(nw.col("foo") > 10).is_empty() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_is_empty`: >>> data = {"foo": [1, 2, 3], "bar": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) >>> agnostic_is_empty(df_pd), agnostic_is_empty(df_pl), agnostic_is_empty(df_pa) (True, True, True) >>> data = {"foo": [100, 2, 3], "bar": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) >>> agnostic_is_empty(df_pd), agnostic_is_empty(df_pl), agnostic_is_empty(df_pa) (False, False, False) )r.Úis_emptyr4s r6r«zDataFrame.is_empty' s€ðJ×$Ñ$×-Ñ-Ó/Ð/r7cól—|j|jj«|j¬«S)ašGet a mask of all unique rows in this DataFrame. Returns: A new Series. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> from narwhals.typing import IntoSeries >>> data = { ... "a": [1, 2, 3, 1], ... "b": ["x", "y", "z", "x"], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_is_unique(df_native: IntoDataFrame) -> IntoSeries: ... df = nw.from_native(df_native, eager_only=True) ... return df.is_unique().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_is_unique`: >>> agnostic_is_unique(df_pd) 0 False 1 True 2 True 3 False dtype: bool >>> agnostic_is_unique(df_pl) # doctest: +NORMALIZE_WHITESPACE shape: (4,) Series: '' [bool] [ false true true false ] >>> agnostic_is_unique(df_pa) # doctest: +ELLIPSIS [ [ false, true, true, false ] ] r;)rír.Ú is_uniquer0r4s r6r­zDataFrame.is_uniqueN s4€ðr|‰|Ø × !Ñ !× +Ñ +Ó -Ø—+‘+ðó ð r7cóT—|j|jj««S)uôCreate a new DataFrame that shows the null counts per column. Returns: A dataframe of shape (1, n_columns). Notes: pandas handles null values differently from Polars and PyArrow. See [null_handling](../pandas_like_concepts/null_handling.md/) for reference. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "foo": [1, None, 3], ... "bar": [6, 7, None], ... "ham": ["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 that returns the null count of each columns: >>> def agnostic_null_count(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.null_count().to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_null_count`: >>> agnostic_null_count(df_pd) foo bar ham 0 1 1 0 >>> agnostic_null_count(df_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ u32 ┆ u32 ┆ u32 │ ╞═════╪═════╪═════╡ │ 1 ┆ 1 ┆ 0 │ └─────┮─────┮─────┘ >>> agnostic_null_count(df_pa) pyarrow.Table foo: int64 bar: int64 ham: int64 ---- foo: [[1]] bar: [[1]] ham: [[0]] )r?r.Ú null_countr4s r6r¯zDataFrame.null_countŒ s%€ðx×-Ñ-šd×.CÑ.C×.NÑ.NÓ.PÓQÐQr7có<—|jj||¬«S)aReturn the DataFrame as a scalar, or return the element at the given row/column. Arguments: row: The *n*-th row. column: The column selected via an integer or a string (column name). Returns: A scalar or the specified element in the dataframe. Notes: If row/col not provided, this is equivalent to df[0,0], with a check that the shape is (1,1). With row/col, this is equivalent to df[row,col]. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function that returns item at given row/column >>> def agnostic_item( ... df_native: IntoDataFrame, row: int | None, column: int | str | None ... ): ... df = nw.from_native(df_native, eager_only=True) ... return df.item(row, column) We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_item`: >>> agnostic_item(df_pd, 1, 1), agnostic_item(df_pd, 2, "b") (np.int64(5), np.int64(6)) >>> agnostic_item(df_pl, 1, 1), agnostic_item(df_pl, 2, "b") (5, 6) >>> agnostic_item(df_pa, 1, 1), agnostic_item(df_pa, 2, "b") (5, 6) )rSÚcolumn)r.r+)r5rSr±s r6r+zDataFrame.itemÊ s!€ðV×$Ñ$×)Ñ)šcž&Ð)ÓAÐAr7có •—t‰|«S)u/Create a copy of this DataFrame. Returns: An identical copy of the original dataframe. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2], "b": [3, 4]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) Let's define a dataframe-agnostic function in which we clone the DataFrame: >>> def agnostic_clone(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.clone().to_native() We can then pass any supported library such as Pandas or Polars to `agnostic_clone`: >>> agnostic_clone(df_pd) a b 0 1 3 1 2 4 >>> agnostic_clone(df_pl) shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 3 │ │ 2 ┆ 4 │ └─────┮─────┘ ©rVr­r`s €r6r­zDataFrame.clone÷ sø€ôR‰w‰}‹Ðr7có&•—t‰|||¬«S)uøTake every nth row in the DataFrame and return as a new DataFrame. Arguments: n: Gather every *n*-th row. offset: Starting index. Returns: The dataframe containing only the selected rows. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = {"a": [1, 2, 3, 4], "b": [5, 6, 7, 8]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function in which gather every 2 rows, starting from a offset of 1: >>> def agnostic_gather_every(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.gather_every(n=2, offset=1).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_gather_every`: >>> agnostic_gather_every(df_pd) a b 1 2 6 3 4 8 >>> agnostic_gather_every(df_pl) shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 2 ┆ 6 │ │ 4 ┆ 8 │ └─────┮─────┘ >>> agnostic_gather_every(df_pa) pyarrow.Table a: int64 b: int64 ---- a: [[2,4]] b: [[6,8]] r¯©rVr±©r5rwr°r=s €r6r±zDataFrame.gather_every" sø€ôl‰wÑ# a°Ð#Ó7Ð7r7Ú_)rŸÚvaluesÚaggregate_functionr‰Ú sort_columnsÚ separatorc óÀ—|€|€ d}t|«‚|d}t|tt«¬«|j |j j ||||||¬««S)uä Create a spreadsheet-style pivot table as a DataFrame. Arguments: on: Name of the column(s) whose values will be used as the header of the output DataFrame. index: One or multiple keys to group by. If None, all remaining columns not specified on `on` and `values` will be used. At least one of `index` and `values` must be specified. values: One or multiple keys to group by. If None, all remaining columns not specified on `on` and `index` will be used. At least one of `index` and `values` must be specified. aggregate_function: Choose from: - None: no aggregation takes place, will raise error if multiple values are in group. - A predefined aggregate function string, one of {'min', 'max', 'first', 'last', 'sum', 'mean', 'median', 'len'} maintain_order: Has no effect and is kept around only for backwards-compatibility. sort_columns: Sort the transposed columns by name. Default is by order of discovery. separator: Used as separator/delimiter in generated column names in case of multiple `values` columns. Returns: A new dataframe. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrameT >>> data = { ... "ix": [1, 1, 2, 2, 1, 2], ... "col": ["a", "a", "a", "a", "b", "b"], ... "foo": [0, 1, 2, 2, 7, 1], ... "bar": [0, 2, 0, 0, 9, 4], ... } >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) Let's define a dataframe-agnostic function: >>> def agnostic_pivot(df_native: IntoDataFrameT) -> IntoDataFrameT: ... df = nw.from_native(df_native, eager_only=True) ... return df.pivot("col", index="ix", aggregate_function="sum").to_native() We can then pass any supported library such as Pandas or Polars to `agnostic_pivot`: >>> agnostic_pivot(df_pd) ix foo_a foo_b bar_a bar_b 0 1 1 7 2 9 1 2 4 1 0 4 >>> agnostic_pivot(df_pl) shape: (2, 5) ┌─────┬───────┬───────┬───────┬───────┐ │ ix ┆ foo_a ┆ foo_b ┆ bar_a ┆ bar_b │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 ┆ i64 ┆ i64 │ ╞═════╪═══════╪═══════╪═══════╪═══════╡ │ 1 ┆ 1 ┆ 7 ┆ 2 ┆ 9 │ │ 2 ┆ 4 ┆ 1 ┆ 0 ┆ 4 │ └─────┮───────┮───────┮───────┮───────┘ z3At least one of `values` and `index` must be passedúx`maintain_order` has no effect and is only kept around for backwards-compatibility. You can safely remove this argument.©ÚmessageÚcategoryÚ stacklevel)rªrŸržr¹rºr»)r§rÚ UserWarningrr?r.Úpivot) r5rªrŸržr¹r‰rºr»rUs r6rÃzDataFrame.pivotZ s|€ð` ˆ>˜e˜mØGˆCܘS“/Ð !Ø Ð %ð7ð ô ˜€{ŒÓ?PÕ Qà×-Ñ-Ø × !Ñ !× 'Ñ 'ØØØØ#5Ø)Ø#ð (ó ó  ð r7có6—|jj«S)aÄConvert to arrow table. Returns: A new PyArrow table. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrame >>> data = {"foo": [1, 2, 3], "bar": ["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 that converts to arrow table: >>> def agnostic_to_arrow(df_native: IntoDataFrame) -> pa.Table: ... df = nw.from_native(df_native, eager_only=True) ... return df.to_arrow() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_to_arrow`: >>> agnostic_to_arrow(df_pd) pyarrow.Table foo: int64 bar: string ---- foo: [[1,2,3]] bar: [["a","b","c"]] >>> agnostic_to_arrow(df_pl) pyarrow.Table foo: int64 bar: large_string ---- foo: [[1,2,3]] bar: [["a","b","c"]] >>> agnostic_to_arrow(df_pa) pyarrow.Table foo: int64 bar: string ---- foo: [[1,2,3]] bar: [["a","b","c"]] )r.rr4s r6rzDataFrame.to_arrow¿ s€ðd×$Ñ$×-Ñ-Ó/Ð/r7)ÚfractionÚwith_replacementÚseedcó^—|j|jj||||¬««S)u‰Sample from this DataFrame. Arguments: n: Number of items to return. Cannot be used with fraction. fraction: Fraction of items to return. Cannot be used with n. with_replacement: Allow values to be sampled more than once. seed: Seed for the random number generator. If set to None (default), a random seed is generated for each sample operation. Returns: A new dataframe. Notes: The results may not be consistent across libraries. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoDataFrameT >>> data = {"a": [1, 2, 3, 4], "b": ["x", "y", "x", "y"]} >>> df_pd = pd.DataFrame(data) >>> df_pl = pl.DataFrame(data) >>> df_pa = pa.table(data) We define a library agnostic function: >>> def agnostic_sample(df_native: IntoDataFrameT) -> IntoDataFrameT: ... df = nw.from_native(df_native, eager_only=True) ... return df.sample(n=2, seed=123).to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_sample`: >>> agnostic_sample(df_pd) a b 3 4 y 0 1 x >>> agnostic_sample(df_pl) shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ str │ ╞═════╪═════╡ │ 2 ┆ y │ │ 3 ┆ x │ └─────┮─────┘ >>> agnostic_sample(df_pa) pyarrow.Table a: int64 b: string ---- a: [[1,3]] b: [["x","x"]] As you can see, by using the same seed, the result will be consistent within the same backend, but not necessarely across different backends. )rwrÅrÆrÇ)r?r.Úsample)r5rwrÅrÆrÇs r6rÉzDataFrame.sampleó s<€ðH×-Ñ-Ø × !Ñ !× (Ñ (ؘhÐ9IÐPTð )ó ó ð r7©rŸr¿rÀcó*•—t‰|||||¬«S)uŠ Unpivot a DataFrame from wide to long format. Optionally leaves identifiers set. This function is useful to massage a DataFrame into a format where one or more columns are identifier variables (index) while all other columns, considered measured variables (on), are "unpivoted" to the row axis leaving just two non-identifier columns, 'variable' and 'value'. Arguments: on: Column(s) to use as values variables; if `on` is empty all columns that are not in `index` will be used. index: Column(s) to use as identifier variables. variable_name: Name to give to the `variable` column. Defaults to "variable". value_name: Name to give to the `value` column. Defaults to "value". Returns: The unpivoted dataframe. Notes: If you're coming from pandas, this is similar to `pandas.DataFrame.melt`, but with `index` replacing `id_vars` and `on` replacing `value_vars`. In other frameworks, you might know this operation as `pivot_longer`. Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": ["x", "y", "z"], ... "b": [1, 3, 5], ... "c": [2, 4, 6], ... } We define a library agnostic function: >>> def agnostic_unpivot(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.unpivot(on=["b", "c"], index="a").to_native() We can then pass any supported library such as Pandas, Polars, or PyArrow to `agnostic_unpivot`: >>> agnostic_unpivot(pl.DataFrame(data)) shape: (6, 3) ┌─────┬──────────┬───────┐ │ a ┆ variable ┆ value │ │ --- ┆ --- ┆ --- │ │ str ┆ str ┆ i64 │ ╞═════╪══════════╪═══════╡ │ x ┆ b ┆ 1 │ │ y ┆ b ┆ 3 │ │ z ┆ b ┆ 5 │ │ x ┆ c ┆ 2 │ │ y ┆ c ┆ 4 │ │ z ┆ c ┆ 6 │ └─────┮──────────┮───────┘ >>> agnostic_unpivot(pd.DataFrame(data)) a variable value 0 x b 1 1 y b 3 2 z b 5 3 x c 2 4 y c 4 5 z c 6 >>> agnostic_unpivot(pa.table(data)) pyarrow.Table a: string variable: string value: int64 ---- a: [["x","y","z"],["x","y","z"]] variable: [["b","b","b"],["c","c","c"]] value: [[1,3,5],[2,4,6]] rœ©rVrÁ©r5rªrŸr¿rÀr=s €r6rÁzDataFrame.unpivot= s%ø€ôn‰w‰Ø˜šmÈ ðó ð r7có$•—t‰||g|¢­ŽS)u Explode the dataframe to long format by exploding the given columns. Notes: It is possible to explode multiple columns only if these columns must have matching element counts. Arguments: columns: Column names. The underlying columns being exploded must be of the `List` data type. *more_columns: Additional names of columns to explode, specified as positional arguments. Returns: New DataFrame Examples: >>> import pandas as pd >>> import polars as pl >>> import pyarrow as pa >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> data = { ... "a": ["x", "y", "z", "w"], ... "lst1": [[1, 2], None, [None], []], ... "lst2": [[3, None], None, [42], []], ... } We define a library agnostic function: >>> def agnostic_explode(df_native: IntoFrameT) -> IntoFrameT: ... return ( ... nw.from_native(df_native) ... .with_columns(nw.col("lst1", "lst2").cast(nw.List(nw.Int32()))) ... .explode("lst1", "lst2") ... .to_native() ... ) We can then pass any supported library such as pandas, Polars (eager), or PyArrow to `agnostic_explode`: >>> agnostic_explode(pd.DataFrame(data)) a lst1 lst2 0 x 1 3 0 x 2 1 y 2 z 42 3 w >>> agnostic_explode(pl.DataFrame(data)) shape: (5, 3) ┌─────┬──────┬──────┐ │ a ┆ lst1 ┆ lst2 │ │ --- ┆ --- ┆ --- │ │ str ┆ i32 ┆ i32 │ ╞═════╪══════╪══════╡ │ x ┆ 1 ┆ 3 │ │ x ┆ 2 ┆ null │ │ y ┆ null ┆ null │ │ z ┆ null ┆ 42 │ │ w ┆ null ┆ null │ └─────┮──────┮──────┘ ©rVrÊ©r5rirËr=s €r6rÊzDataFrame.explode˜ sø€ôx‰w‰˜wÐ6šÒ6Ð6r7)rÌztype[Series[Any]])rÌztype[LazyFrame[Any]]©r>rr<r/rÌÚNone©rÌr()rÌr×)NN)rrrÿú bool | NonerÌú np.ndarray©rÌrQr2)rz object | NonerÌrã)rÌzLazyFrame[Any])rÌr+)rÌz pd.DataFrame)rrÒrÌrQ)rzstr | Path | BytesIOrÌrÒ)rzstr | Path | BytesIO | NonerÌrá)rÌrÕ)rÌztuple[int, int])rcrQrÌú Series[Any])Úb)r'r'rÌz int | float)r+ztuple[Sequence[int], slice]rÌr)r+z#tuple[Sequence[int], Sequence[int]]rÌr)r+ztuple[slice, Sequence[int]]rÌr)r+ztuple[Sequence[int], str]rÌr×)r+ztuple[slice, str]rÌr×)r+z#tuple[Sequence[int], Sequence[str]]rÌr)r+ztuple[slice, Sequence[str]]rÌr)r+ztuple[Sequence[int], int]rÌr×)r+ztuple[slice, int]rÌr×)r+z Sequence[int]rÌr)r+rQrÌr×)r+z Sequence[str]rÌr)r+rBrÌr)r+ztuple[slice, slice]rÌr)r+zÃstr | slice | Sequence[int] | Sequence[str] | tuple[Sequence[int], str | int] | tuple[slice, str | int] | tuple[slice | Sequence[int], Sequence[int] | Sequence[str] | slice] | tuple[slice, slice]rÌzSeries[Any] | Self)rFrQrÌrƒ)rIú Literal[True]rÌzdict[str, Series[Any]])rIúLiteral[False]rÌzdict[str, list[Any]])rIrƒrÌz-dict[str, Series[Any]] | dict[str, list[Any]])rŸr×rÌztuple[Any, ...]rÎrÑrÏrÐrÍ©r5rrÌrrÓ)rfrÚrÌzlist[tuple[Any, ...]])rfrÙrÌzlist[dict[str, Any]])rfrƒrÌz,list[tuple[Any, ...]] | list[dict[str, Any]])rfrÚrmr×rÌzIterator[tuple[Any, ...]])rfrÙrmr×rÌzIterator[dict[str, Any]])rfrƒrmr×rÌz4Iterator[tuple[Any, ...]] | Iterator[dict[str, Any]]rÔrÕ©érÖ©rirÚr}rƒrÌr)rfrÒrˆz'Literal['any', 'first', 'last', 'none']r‰rƒrÌrrØ)r›rÚr’rƒrÌz GroupBy[Self]rÙrÛrÜrà)r5rrÌr×)r5rrÌrƒ)r5rrÌr)r5rrSú int | Noner±zint | str | NonerÌrrÝrÞrß)r5rrªzstr | list[str]rŸrÒržrÒr¹zMLiteral['min', 'max', 'first', 'last', 'sum', 'mean', 'median', 'len'] | Noner‰rÔrºrƒr»rQrÌr)r5rrÌzpa.Table) r5rrwrßrÅz float | NonerÆrƒrÇrßrÌrrârä)ñ(Ø&ð(Ø58ð(à "ò(óð(ðà:=ñ'Ø%ð'Ø47ð'à !ò'óð'ðà14ñCØðCØ+.ðCà =òCóðCð %žñ3UØð3UØ36ð3Uà =ó3UðjP;Ø3ðP;ØDLðP;à õP;ðd^5à-ð^5ð ð^5ð õ ^5õ@6'öp;öz;ðzBF÷R>ðl*.ðO ð9>Ø$ñ O à&ðO ð6ð O ð ð O ð ó O ðbu:ØEðu:ØVYðu:à õu:ðpBGñkHØ(ðkHØ:>ðkHà ókHðb-2Ø ñ KXà ðKXððKXð*ð KXð ð KXð õ KXð`&*ØAHð ` ð +/Ø+/Øñ` àð` ð #ð` ð?ð ` ð (ð ` ð)ð` ðð` ð õ` ðL#Ø#ØØ*.Ø+/Ø%)Ø>Hñ{ àð{ ðð { ð ð { ð ð { ð(ð{ ð)ð{ ð #ð{ ð<ð{ ð õ{ ó|< ó|%0óN< ó|<Rô|+BõZ)öV68ðx)-Ø)-ðØ&*Ø"Øñc Øðc à ðc ð&ð c ð 'ð c ð ð c ð$ðc ððc ððc ð óc óJ20ðlðH ð"&Ø!&Øñ H ØðH à ðH ðð H ð ð H ð ð H ð óH ðX&*ðY ð)-Ø$(Ø!%ñ Y ØðY à "ðY ð&ð Y ð "ð Y ð ð Y ð õY ÷v<7ñ<7r7rëc󆇗eZdZdZed-d„«Z d.d„Zd/d„Zed0d„«Zd1d„Z d2d„Z d3d„Z d4ˆfd „ Z d5d6ˆfd „ Z d7d8ˆfd „ Zed9ˆfd „ «Zd:ˆfd„ Zed;ˆfd„ «Z d<ˆfd„ Z d<ˆfd„ Zd=ˆfd„ Zd>d?ˆfd„ Zd>d?ˆfd„ Zddœd@ˆfd„Z d5dd dœ dAd„Z dBˆfd„ Zddœ dCd„Zdddœ dDˆfd „Z dEd d d!d"œ dFˆfd#„Zd d d d d d d$d%œ dGˆfd&„ZdHˆfd'„ ZdHd(„ZdIdJˆfd)„ Z d5d d d d*œ dKˆfd+„Z!dLˆfd,„ Z"ˆxZ#S)Mrïa—Narwhals LazyFrame, backed by a native lazyframe. !!! warning This class is not meant to be instantiated directly - instead use [`narwhals.from_native`][] with a native object that is a lazy dataframe from one of the supported backend (e.g. polars.LazyFrame, dask_expr._collection.DataFrame): ```py narwhals.from_native(native_lazyframe) ``` có—tSr2)rër4s r6Ú _dataframezLazyFrame._dataframeä rñr7có†—||_t|d«r|j«|_ydt |«›}t |«‚)NÚ__narwhals_lazyframe__zVExpected Polars LazyFrame or an object that implements `__narwhals_lazyframe__`, got: )r0rôrçr.rRrõrös r6r÷zLazyFrame.__init__è sF€ð ˆŒ Ü 2Ð/Ô 0Ø)+×)BÑ)BÓ)DˆDÕ !àjÔkoÐprÓksÐjtÐuˆCÜ  Ó%Ð %r7cóR—td|j«j««S)NzNarwhals LazyFramerr4s r6rzLazyFrame.__repr__õ rr7có.—|jjS)a²Return implementation of native frame. This can be useful when you need to use special-casing for features outside of Narwhals' scope - for example, when dealing with pandas' Period Dtype. Returns: Implementation. Examples: >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> lf_pl = pl.LazyFrame({"a": [1, 2, 3]}) >>> lf_dask = dd.from_dict({"a": [1, 2, 3]}, npartitions=2) >>> lf = nw.from_native(lf_pl) >>> lf.implementation >>> lf.implementation.is_pandas() False >>> lf.implementation.is_polars() True >>> lf = nw.from_native(lf_dask) >>> lf.implementation >>> lf.implementation.is_dask() True rùr4s r6rûzLazyFrame.implementationø s€ð>×$Ñ$×4Ñ4Ð4r7có—d}t|«‚)Nz%Slicing is not supported on LazyFrame)rSrDs r6r,zLazyFrame.__getitem__s€Ø5ˆÜ˜‹nÐr7cóX—|j|jj«d¬«S)uï Materialize this LazyFrame into a DataFrame. Returns: DataFrame Examples: >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> data = { ... "a": ["a", "b", "a", "b", "b", "c"], ... "b": [1, 2, 3, 4, 5, 6], ... "c": [6, 5, 4, 3, 2, 1], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) >>> lf = nw.from_native(lf_pl) >>> lf # doctest:+ELLIPSIS ┌─────────────────────────────┐ | Narwhals LazyFrame | |-----------------------------| |>> df = lf.group_by("a").agg(nw.all().sum()).collect() >>> df.to_native().sort("a") shape: (3, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ a ┆ 4 ┆ 10 │ │ b ┆ 11 ┆ 10 │ │ c ┆ 6 ┆ 1 │ └─────┮─────┮─────┘ >>> lf = nw.from_native(lf_dask) >>> lf ┌───────────────────────────────────┐ | Narwhals LazyFrame | |-----------------------------------| |Dask DataFrame Structure: | | a b c| |npartitions=2 | |0 string int64 int64| |3 ... ... ...| |5 ... ... ...| |Dask Name: frompandas, 1 expression| |Expr=df | └───────────────────────────────────┘ >>> df = lf.group_by("a").agg(nw.col("b", "c").sum()).collect() >>> df.to_native() a b c 0 a 4 10 1 b 11 10 2 c 6 1 Úfullr;)rår.Úcollectr4s r6rízLazyFrame.collects0€ðv‰Ø × !Ñ !× )Ñ )Ó +Øðó ð r7có—t|d¬«S)uíConvert Narwhals LazyFrame to native one. Returns: Object of class that user started with. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Calling `to_native` on a Narwhals LazyFrame returns the native object: >>> nw.from_native(lf_pl).to_native().collect() shape: (3, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6.0 ┆ a │ │ 2 ┆ 7.0 ┆ b │ │ 3 ┆ 8.0 ┆ c │ └─────┮─────┮─────┘ >>> nw.from_native(lf_dask).to_native().compute() foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c F)Únarwhals_objectÚ pass_throughrr4s r6rzLazyFrame.to_native]s€ôDšžEÔBÐBr7có*•—t‰||g|¢­i|€ŽS)u˜Pipe function call. Arguments: function: Function to apply. args: Positional arguments to pass to function. kwargs: Keyword arguments to pass to function. Returns: The original object with the function applied. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3], "ba": [4, 5, 6]} >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function: >>> def agnostic_pipe(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.pipe(lambda _df: _df.select("a")).collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_pipe`: >>> agnostic_pipe(lf_pl) shape: (3, 1) ┌─────┐ │ a │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ >>> agnostic_pipe(lf_dask) a 0 1 1 2 2 3 rUrWs €r6r_zLazyFrame.pipe‚sø€ô\‰w‰|˜HÐ6 tÒ6švÑ6Ð6r7Ncó$•—t‰||¬«S)uŒDrop rows that contain null values. Arguments: subset: Column name(s) for which null values are considered. If set to None (default), use all columns. Returns: The original object with the rows removed that contained the null values. Notes: pandas handles null values differently from Polars and PyArrow. See [null_handling](../pandas_like_concepts/null_handling.md/) for reference. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1.0, 2.0, None], "ba": [1.0, None, 2.0]} >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function: >>> def agnostic_drop_nulls(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.drop_nulls().collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_drop_nulls`: >>> agnostic_drop_nulls(lf_pl) shape: (1, 2) ┌─────┬─────┐ │ a ┆ ba │ │ --- ┆ --- │ │ f64 ┆ f64 │ ╞═════╪═════╡ │ 1.0 ┆ 1.0 │ └─────┮─────┘ >>> agnostic_drop_nulls(lf_dask) a ba 0 1.0 1.0 rerYrZs €r6rgzLazyFrame.drop_nulls²sø€ô\‰wÑ!šÐ!Ó0Ð0r7có"•—t‰||«S)u{Insert column which enumerates rows. Arguments: name: The name of the column as a string. The default is "index". Returns: The original object with the column added. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3], "b": [4, 5, 6]} >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function: >>> def agnostic_with_row_index(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.with_row_index().collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_with_row_index`: >>> agnostic_with_row_index(lf_pl) shape: (3, 3) ┌───────┬─────┬─────┐ │ index ┆ a ┆ b │ │ --- ┆ --- ┆ --- │ │ u32 ┆ i64 ┆ i64 │ ╞═══════╪═════╪═════╡ │ 0 ┆ 1 ┆ 4 │ │ 1 ┆ 2 ┆ 5 │ │ 2 ┆ 3 ┆ 6 │ └───────┮─────┮─────┘ >>> agnostic_with_row_index(lf_dask) index a b 0 0 1 4 1 1 2 5 2 2 3 6 r\r]s €r6razLazyFrame.with_row_indexâsø€ôX‰wÑ% dÓ+Ð+r7có•—t‰|S)atGet an ordered mapping of column names to their data type. Returns: A Narwhals Schema object that displays the mapping of column names. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) >>> lf = nw.from_native(lf_pl) >>> lf.schema # doctest: +SKIP Schema({'foo': Int64, 'bar': Float64, 'ham': String}) >>> lf = nw.from_native(lf_dask) >>> lf.schema # doctest: +SKIP Schema({'foo': Int64, 'bar': Float64, 'ham': String}) r_r`s €r6rWzLazyFrame.schemasø€ô6‰w‰~Ðr7có •—t‰|«S)adGet an ordered mapping of column names to their data type. Returns: A Narwhals Schema object that displays the mapping of column names. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) >>> lf = nw.from_native(lf_pl) >>> lf.collect_schema() Schema({'foo': Int64, 'bar': Float64, 'ham': String}) >>> lf = nw.from_native(lf_dask) >>> lf.collect_schema() Schema({'foo': Int64, 'bar': Float64, 'ham': String}) rbr`s €r6rZzLazyFrame.collect_schema-sø€ô4‰wÑ%Ó'Ð'r7có•—t‰|S)aÍGet column names. Returns: The column names stored in a list. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrame >>> >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) We define a library agnostic function: >>> def agnostic_columns(df_native: IntoFrame) -> list[str]: ... df = nw.from_native(df_native) ... return df.columns We can then pass any supported library such as Polars or Dask to `agnostic_columns`: >>> agnostic_columns(lf_pl) # doctest: +SKIP ['foo', 'bar', 'ham'] >>> agnostic_columns(lf_dask) ['foo', 'bar', 'ham'] rdr`s €r6rizLazyFrame.columnsIsø€ô<‰w‰Ðr7có"•—t‰||i|€ŽS)ug Add columns to this LazyFrame. Added columns will replace existing columns with the same name. Arguments: *exprs: Column(s) to add, specified as positional arguments. Accepts expression input. Strings are parsed as column names, other non-expression inputs are parsed as literals. **named_exprs: Additional columns to add, specified as keyword arguments. The columns will be renamed to the keyword used. Returns: LazyFrame: A new LazyFrame with the columns added. Note: Creating a new LazyFrame using this method does not create a new copy of existing data. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 2, 3, 4], ... "b": [0.5, 4, 10, 13], ... "c": [True, True, False, True], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function in which we pass an expression to add it as a new column: >>> def agnostic_with_columns(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return ( ... df.with_columns((nw.col("a") * 2).alias("2a")).collect().to_native() ... ) We can then pass any supported library such as Polars or Dask to `agnostic_with_columns`: >>> agnostic_with_columns(lf_pl) shape: (4, 4) ┌─────┬──────┬───────┬─────┐ │ a ┆ b ┆ c ┆ 2a │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ bool ┆ i64 │ ╞═════╪══════╪═══════╪═════╡ │ 1 ┆ 0.5 ┆ true ┆ 2 │ │ 2 ┆ 4.0 ┆ true ┆ 4 │ │ 3 ┆ 10.0 ┆ false ┆ 6 │ │ 4 ┆ 13.0 ┆ true ┆ 8 │ └─────┮──────┮───────┮─────┘ >>> agnostic_with_columns(lf_dask) a b c 2a 0 1 0.5 True 2 1 2 4.0 True 4 2 3 10.0 False 6 3 4 13.0 True 8 rvrws €r6rkzLazyFrame.with_columnsisø€ôD‰wÑ# UÐ:škÑ:Ð:r7có"•—t‰||i|€ŽS)uPSelect columns from this LazyFrame. Arguments: *exprs: Column(s) to select, specified as positional arguments. Accepts expression input. Strings are parsed as column names. **named_exprs: Additional columns to select, specified as keyword arguments. The columns will be renamed to the keyword used. Returns: The LazyFrame containing only the selected columns. Notes: If you'd like to select a column whose name isn't a string (for example, if you're working with pandas) then you should explicitly use `nw.col` instead of just passing the column name. For example, to select a column named `0` use `df.select(nw.col(0))`, not `df.select(0)`. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "foo": [1, 2, 3], ... "bar": [6, 7, 8], ... "ham": ["a", "b", "c"], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function in which we pass the name of a column to select that column. >>> def agnostic_select(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select("foo").collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_select`: >>> agnostic_select(lf_pl) shape: (3, 1) ┌─────┐ │ foo │ │ --- │ │ i64 │ ╞═════╡ │ 1 │ │ 2 │ │ 3 │ └─────┘ >>> agnostic_select(lf_dask) foo 0 1 1 2 2 3 Multiple columns can be selected by passing a list of column names. >>> def agnostic_select(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(["foo", "bar"]).collect().to_native() >>> agnostic_select(lf_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 6 │ │ 2 ┆ 7 │ │ 3 ┆ 8 │ └─────┮─────┘ >>> agnostic_select(lf_dask) foo bar 0 1 6 1 2 7 2 3 8 Multiple columns can also be selected using positional arguments instead of a list. Expressions are also accepted. >>> def agnostic_select(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(nw.col("foo"), nw.col("bar") + 1).collect().to_native() >>> agnostic_select(lf_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 7 │ │ 2 ┆ 8 │ │ 3 ┆ 9 │ └─────┮─────┘ >>> agnostic_select(lf_dask) foo bar 0 1 7 1 2 8 2 3 9 Use keyword arguments to easily name your expression inputs. >>> def agnostic_select(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.select(threshold=nw.col("foo") * 2).collect().to_native() >>> agnostic_select(lf_pl) shape: (3, 1) ┌───────────┐ │ threshold │ │ --- │ │ i64 │ ╞═══════════╡ │ 2 │ │ 4 │ │ 6 │ └───────────┘ >>> agnostic_select(lf_dask) threshold 0 2 1 4 2 6 ryrws €r6rpzLazyFrame.select­sø€ôH‰w‰~˜uÐ4š Ñ4Ð4r7có"•—t‰||«S)uíRename column names. Arguments: mapping: Key value pairs that map from old name to new name, or a function that takes the old name as input and returns the new name. Returns: The LazyFrame with the specified columns renamed. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"foo": [1, 2, 3], "bar": [6, 7, 8], "ham": ["a", "b", "c"]} >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) We define a library agnostic function: >>> def agnostic_rename(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.rename({"foo": "apple"}).collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_rename`: >>> agnostic_rename(lf_pl) shape: (3, 3) ┌───────┬─────┬─────┐ │ apple ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═══════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └───────┮─────┮─────┘ >>> agnostic_rename(lf_dask) apple bar ham 0 1 6 a 1 2 7 b 2 3 8 c r{r|s €r6rrzLazyFrame.rename3sø€ô\‰w‰~˜gÓ&Ð&r7có"•—t‰||«S)uëGet the first `n` rows. Arguments: n: Number of rows to return. Returns: A subset of the LazyFrame of shape (n, n_columns). Examples: >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 2, 3, 4, 5, 6], ... "b": [7, 8, 9, 10, 11, 12], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function that gets the first 3 rows. >>> def agnostic_head(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.head(3).collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_head`: >>> agnostic_head(lf_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 7 │ │ 2 ┆ 8 │ │ 3 ┆ 9 │ └─────┮─────┘ >>> agnostic_head(lf_dask) a b 0 1 7 1 2 8 2 3 9 r~rs €r6ruzLazyFrame.headcsø€ô^‰w‰|˜A‹Ðr7có"•—t‰||«S)ufGet the last `n` rows. Arguments: n: Number of rows to return. Returns: A subset of the LazyFrame of shape (n, n_columns). Notes: `LazyFrame.tail` is not supported for the Dask backend with multiple partitions. Examples: >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 2, 3, 4, 5, 6], ... "b": [7, 8, 9, 10, 11, 12], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=1) Let's define a dataframe-agnostic function that gets the last 3 rows. >>> def agnostic_tail(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.tail(3).collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_tail`: >>> agnostic_tail(lf_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 4 ┆ 10 │ │ 5 ┆ 11 │ │ 6 ┆ 12 │ └─────┮─────┘ >>> agnostic_tail(lf_dask) a b 3 4 10 4 5 11 5 6 12 r‚rs €r6rzzLazyFrame.tail”sø€ôf‰w‰|˜A‹Ðr7Tr|có4•—t‰|t|«d|iŽS)uÑ Remove columns from the LazyFrame. Arguments: *columns: Names of the columns that should be removed from the dataframe. strict: Validate that all column names exist in the schema and throw an exception if a column name does not exist in the schema. Returns: The LazyFrame with the specified columns removed. Warning: `strict` argument is ignored for `polars<1.0.0`. Please consider upgrading to a newer version or pass to eager mode. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) We define a library agnostic function: >>> def agnostic_drop(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.drop("ham").collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_drop`: >>> agnostic_drop(lf_pl) shape: (3, 2) ┌─────┬─────┐ │ foo ┆ bar │ │ --- ┆ --- │ │ i64 ┆ f64 │ ╞═════╪═════╡ │ 1 ┆ 6.0 │ │ 2 ┆ 7.0 │ │ 3 ┆ 8.0 │ └─────┮─────┘ >>> agnostic_drop(lf_dask) foo bar 0 1 6.0 1 2 7.0 2 3 8.0 Use positional arguments to drop multiple columns. >>> def agnostic_drop(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.drop("foo", "ham").collect().to_native() >>> agnostic_drop(lf_pl) shape: (3, 1) ┌─────┐ │ bar │ │ --- │ │ f64 │ ╞═════╡ │ 6.0 │ │ 7.0 │ │ 8.0 │ └─────┘ >>> agnostic_drop(lf_dask) bar 0 6.0 1 7.0 2 8.0 r}r„r…s €r6r~zLazyFrame.dropÉsø€ôT‰w‰|œW WÓ-Ð=°fÑ=Ð=r7r†r‡có—|dvrd|›d}t|«‚|r d}t|«‚|d}t|tt«¬«t |t «r|g}|j |jj||¬««S)uÚDrop duplicate rows from this LazyFrame. Arguments: subset: Column name(s) to consider when identifying duplicate rows. If set to `None`, use all columns. keep: {'first', 'none'} Which of the duplicate rows to keep. * 'any': Does not give any guarantee of which row is kept. This allows more optimizations. * 'none': Don't keep duplicate rows. maintain_order: Has no effect and is kept around only for backwards-compatibility. Returns: The LazyFrame with unique rows. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "foo": [1, 2, 3, 1], ... "bar": ["a", "a", "a", "a"], ... "ham": ["b", "b", "b", "b"], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) We define a library agnostic function: >>> def agnostic_unique(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.unique(["bar", "ham"]).collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_unique`: >>> agnostic_unique(lf_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ str ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ a ┆ b │ └─────┮─────┮─────┘ >>> agnostic_unique(lf_dask) foo bar ham 0 1 a b >r†rŒz}narwhals.LazyFrame makes no assumptions about row order, so only 'any' and 'none' are supported for `keep` in `unique`. Got: r€z<`maintain_order=True` is not supported for LazyFrame.unique.rœrŸ)rfrˆ) r§rrÂrrNrQr?r.rŽrs r6rŽzLazyFrame.uniques¢€ðt Ñ &ðOØOSÈfÐTUðWð ô˜S“/Ð !Ù ØPˆCܘS“/Ð !Ø Ð %ð7ð ô ˜€{ŒÓ?PÕ QÜ fœcÔ "ؐXˆFØ×-Ñ-Ø × !Ñ !× (Ñ (°žTÐ (Ó Bó ð r7c󬕗t|«dk(r7t|dt«r$td„|dD««r|s d}t |«‚t ‰||i|€ŽS)u‡Filter the rows in the LazyFrame based on a predicate expression. The original order of the remaining rows is preserved. Arguments: *predicates: Expression that evaluates to a boolean Series. Can also be a (single!) boolean list. **constraints: Column filters; use `name = value` to filter columns by the supplied value. Each constraint will behave the same as `nw.col(name).eq(value)`, and will be implicitly joined with the other filter conditions using &. Returns: The filtered LazyFrame. Examples: >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "foo": [1, 2, 3], ... "bar": [6, 7, 8], ... "ham": ["a", "b", "c"], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function in which we filter on one condition. >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter(nw.col("foo") > 1).collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_filter`: >>> agnostic_filter(lf_pl) shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_dask) foo bar ham 1 2 7 b 2 3 8 c Filter on multiple conditions: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return ( ... df.filter((nw.col("foo") < 3) & (nw.col("ham") == "a")) ... .collect() ... .to_native() ... ) >>> agnostic_filter(lf_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_dask) foo bar ham 0 1 6 a Provide multiple filters using `*args` syntax: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return ( ... df.filter( ... nw.col("foo") == 1, ... nw.col("ham") == "a", ... ) ... .collect() ... .to_native() ... ) >>> agnostic_filter(lf_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_dask) foo bar ham 0 1 6 a Filter on an OR condition: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return ( ... df.filter((nw.col("foo") == 1) | (nw.col("ham") == "c")) ... .collect() ... .to_native() ... ) >>> agnostic_filter(lf_pl) shape: (2, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 1 ┆ 6 ┆ a │ │ 3 ┆ 8 ┆ c │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_dask) foo bar ham 0 1 6 a 2 3 8 c Provide multiple filters using `**kwargs` syntax: >>> def agnostic_filter(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.filter(foo=2, ham="b").collect().to_native() >>> agnostic_filter(lf_pl) shape: (1, 3) ┌─────┬─────┬─────┐ │ foo ┆ bar ┆ ham │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ str │ ╞═════╪═════╪═════╡ │ 2 ┆ 7 ┆ b │ └─────┮─────┮─────┘ >>> agnostic_filter(lf_dask) foo bar ham 1 2 7 b r€rc3ó<K—|]}t|t«–—Œy­wr2r‚r„s r6r‡z#LazyFrame.filter..ûrˆr‰zX`LazyFrame.filter` is not supported with Python boolean masks - use expressions instead.)rŠrNr‹rŒrSrVr)r5rŽrrUr=s €r6rzLazyFrame.filterdsXø€ôj  ‹O˜qÒ Ü˜: a™=¬$Ô/ÜÑ?°žA²Ó?Ô?ÙàlˆCܘC“.Ð ä‰w‰~˜zÐ9š[Ñ9Ð9r7Fr‘c󜇇—ddlmŠddlm}ddlmŠt |«}tˆˆfd„|D««r d}t|«‚||g|¢­d|iŽS)u# Start a group by operation. Arguments: *keys: Column(s) to group by. Accepts expression input. Strings are parsed as column names. drop_null_keys: if True, then groups where any key is null won't be included in the result. Returns: Object which can be used to perform aggregations. Examples: Group by one column and call `agg` to compute the grouped sum of another column. >>> import polars as pl >>> import dask.dataframe as dd >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": ["a", "b", "a", "b", "c"], ... "b": [1, 2, 1, 3, 3], ... "c": [5, 4, 3, 2, 1], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function in which we group by one column and call `agg` to compute the grouped sum of another column. >>> def agnostic_group_by_agg(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return ( ... df.group_by("a") ... .agg(nw.col("b").sum()) ... .sort("a") ... .collect() ... .to_native() ... ) We can then pass any supported library such as Polars or Dask to `agnostic_group_by_agg`: >>> agnostic_group_by_agg(lf_pl) shape: (3, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ str ┆ i64 │ ╞═════╪═════╡ │ a ┆ 2 │ │ b ┆ 5 │ │ c ┆ 3 │ └─────┮─────┘ >>> agnostic_group_by_agg(lf_dask) a b 0 a 2 1 b 5 2 c 3 Group by multiple columns by passing a list of column names. >>> def agnostic_group_by_agg(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return ( ... df.group_by(["a", "b"]) ... .agg(nw.max("c")) ... .sort(["a", "b"]) ... .collect() ... .to_native() ... ) >>> agnostic_group_by_agg(lf_pl) shape: (4, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ a ┆ 1 ┆ 5 │ │ b ┆ 2 ┆ 4 │ │ b ┆ 3 ┆ 2 │ │ c ┆ 3 ┆ 1 │ └─────┮─────┮─────┘ >>> agnostic_group_by_agg(lf_dask) a b c 0 a 1 5 1 b 2 4 2 b 3 2 3 c 3 1 rrIr r"c3ó:•K—|]}t|‰‰f«–—Œy­wr2r•r–s €€r6r‡z%LazyFrame.group_by..gr—r˜r™r’) rLrJršr!rMr#rr†rŠ)r5r’r›r!rœrUrJr#s @@r6rzLazyFrame.group_bysSù€õ~ 'Ý1Ý*ä˜D“Mˆ Ü Ô@±iÓ@Ô @ðWð ô& cÓ*Ð *Ù˜4ÐK )ÒKžNÑKÐKr7rcó,•—t‰||g|¢­||dœŽS)ul Sort the LazyFrame by the given columns. Arguments: by: Column(s) names to sort by. *more_by: Additional columns to sort by, specified as positional arguments. descending: Sort in descending order. When sorting by multiple columns, can be specified per column by passing a sequence of booleans. nulls_last: Place null values last; can specify a single boolean applying to all columns or a sequence of booleans for per-column control. Returns: The sorted LazyFrame. Warning: Unlike Polars, it is not possible to specify a sequence of booleans for `nulls_last` in order to control per-column behaviour. Instead a single boolean is applied for all `by` columns. Examples: >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": [1, 2, None], ... "b": [6.0, 5.0, 4.0], ... "c": ["a", "c", "b"], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function in which we sort by multiple columns in different orders >>> def agnostic_sort(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.sort("c", "a", descending=[False, True]).collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_sort`: >>> agnostic_sort(lf_pl) shape: (3, 3) ┌──────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str │ ╞══════╪═════╪═════╡ │ 1 ┆ 6.0 ┆ a │ │ null ┆ 4.0 ┆ b │ │ 2 ┆ 5.0 ┆ c │ └──────┮─────┮─────┘ >>> agnostic_sort(lf_dask) a b c 0 1.0 6.0 a 2 NaN 4.0 b 1 2.0 5.0 c rrŸr s €r6r”zLazyFrame.sortos!ø€ôB‰w‰|˜BÐW ÑW°ZÈJÒWÐWr7r—r˜có.•—t‰|||||||¬«S)uc Add a join operation to the Logical Plan. Arguments: other: Lazy DataFrame to join with. on: Name(s) of the join columns in both DataFrames. If set, `left_on` and `right_on` should be None. how: Join strategy. * *inner*: Returns rows that have matching values in both tables. * *left*: Returns all rows from the left table, and the matched rows from the right table. * *cross*: Returns the Cartesian product of rows from both tables. * *semi*: Filter rows that have a match in the right table. * *anti*: Filter rows that do not have a match in the right table. left_on: Join column of the left DataFrame. right_on: Join column of the right DataFrame. suffix: Suffix to append to columns with a duplicate name. Returns: A new joined LazyFrame. Examples: >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "foo": [1, 2, 3], ... "bar": [6.0, 7.0, 8.0], ... "ham": ["a", "b", "c"], ... } >>> data_other = { ... "apple": ["x", "y", "z"], ... "ham": ["a", "b", "d"], ... } >>> lf_pl = pl.LazyFrame(data) >>> other_pl = pl.LazyFrame(data_other) >>> lf_dask = dd.from_dict(data, npartitions=2) >>> other_dask = dd.from_dict(data_other, npartitions=2) Let's define a dataframe-agnostic function in which we join over "ham" column: >>> def agnostic_join_on_ham( ... df_native: IntoFrameT, ... other_native: IntoFrameT, ... ) -> IntoFrameT: ... df = nw.from_native(df_native) ... other = nw.from_native(other_native) ... return ( ... df.join(other, left_on="ham", right_on="ham") ... .sort("ham") ... .collect() ... .to_native() ... ) We can then pass any supported library such as Polars or Dask to `agnostic_join_on_ham`: >>> agnostic_join_on_ham(lf_pl, other_pl) shape: (2, 4) ┌─────┬─────┬─────┬───────┐ │ foo ┆ bar ┆ ham ┆ apple │ │ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ f64 ┆ str ┆ str │ ╞═════╪═════╪═════╪═══════╡ │ 1 ┆ 6.0 ┆ a ┆ x │ │ 2 ┆ 7.0 ┆ b ┆ y │ └─────┮─────┮─────┮───────┘ >>> agnostic_join_on_ham(lf_dask, other_dask) foo bar ham apple 0 1 6.0 a x 0 2 7.0 b y r¢r£r€s €r6ršzLazyFrame.join²s)ø€ôf‰w‰|Ø s G°hÀ2Èfðó ð r7r²r³c ó2•—t‰ |||||||||¬«S)u&Perform an asof join. This is similar to a left-join except that we match on nearest key rather than equal keys. Both DataFrames must be sorted by the asof_join key. Arguments: other: DataFrame to join with. left_on: Name(s) of the left join column(s). right_on: Name(s) of the right join column(s). on: Join column of both DataFrames. If set, left_on and right_on should be None. by_left: join on these columns before doing asof join by_right: join on these columns before doing asof join by: join on these columns before doing asof join strategy: Join strategy. The default is "backward". * *backward*: selects the last row in the right DataFrame whose "on" key is less than or equal to the left's key. * *forward*: selects the first row in the right DataFrame whose "on" key is greater than or equal to the left's key. * *nearest*: search selects the last row in the right DataFrame whose value is nearest to the left's key. Returns: A new joined LazyFrame. Examples: >>> from datetime import datetime >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> from typing import Literal >>> from narwhals.typing import IntoFrameT >>> >>> data_gdp = { ... "datetime": [ ... datetime(2016, 1, 1), ... datetime(2017, 1, 1), ... datetime(2018, 1, 1), ... datetime(2019, 1, 1), ... datetime(2020, 1, 1), ... ], ... "gdp": [4164, 4411, 4566, 4696, 4827], ... } >>> data_population = { ... "datetime": [ ... datetime(2016, 3, 1), ... datetime(2018, 8, 1), ... datetime(2019, 1, 1), ... ], ... "population": [82.19, 82.66, 83.12], ... } >>> gdp_pl = pl.LazyFrame(data_gdp) >>> population_pl = pl.LazyFrame(data_population) >>> gdp_dask = dd.from_dict(data_gdp, npartitions=2) >>> population_dask = dd.from_dict(data_population, npartitions=2) Let's define a dataframe-agnostic function in which we join over "datetime" column: >>> def agnostic_join_asof_datetime( ... df_native: IntoFrameT, ... other_native: IntoFrameT, ... strategy: Literal["backward", "forward", "nearest"], ... ) -> IntoFrameT: ... df = nw.from_native(df_native) ... other = nw.from_native(other_native) ... return ( ... df.sort("datetime") ... .join_asof(other, on="datetime", strategy=strategy) ... .collect() ... .to_native() ... ) We can then pass any supported library such as Polars or Dask to `agnostic_join_asof_datetime`: >>> agnostic_join_asof_datetime(population_pl, gdp_pl, strategy="backward") shape: (3, 3) ┌─────────────────────┬────────────┬──────┐ │ datetime ┆ population ┆ gdp │ │ --- ┆ --- ┆ --- │ │ datetime[ÎŒs] ┆ f64 ┆ i64 │ ╞═════════════════════╪════════════╪══════╡ │ 2016-03-01 00:00:00 ┆ 82.19 ┆ 4164 │ │ 2018-08-01 00:00:00 ┆ 82.66 ┆ 4566 │ │ 2019-01-01 00:00:00 ┆ 83.12 ┆ 4696 │ └─────────────────────┮────────────┮──────┘ >>> agnostic_join_asof_datetime(population_dask, gdp_dask, strategy="backward") datetime population gdp 0 2016-03-01 82.19 4164 1 2018-08-01 82.66 4566 0 2019-01-01 83.12 4696 Here is a real-world times-series example that uses `by` argument. >>> from datetime import datetime >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> from narwhals.typing import IntoFrameT >>> >>> data_quotes = { ... "datetime": [ ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 30), ... datetime(2016, 5, 25, 13, 30, 0, 41), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 49), ... datetime(2016, 5, 25, 13, 30, 0, 72), ... datetime(2016, 5, 25, 13, 30, 0, 75), ... ], ... "ticker": [ ... "GOOG", ... "MSFT", ... "MSFT", ... "MSFT", ... "GOOG", ... "AAPL", ... "GOOG", ... "MSFT", ... ], ... "bid": [720.50, 51.95, 51.97, 51.99, 720.50, 97.99, 720.50, 52.01], ... "ask": [720.93, 51.96, 51.98, 52.00, 720.93, 98.01, 720.88, 52.03], ... } >>> data_trades = { ... "datetime": [ ... datetime(2016, 5, 25, 13, 30, 0, 23), ... datetime(2016, 5, 25, 13, 30, 0, 38), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... datetime(2016, 5, 25, 13, 30, 0, 49), ... datetime(2016, 5, 25, 13, 30, 0, 48), ... ], ... "ticker": ["MSFT", "MSFT", "GOOG", "GOOG", "AAPL"], ... "price": [51.95, 51.95, 720.77, 720.92, 98.0], ... "quantity": [75, 155, 100, 100, 100], ... } >>> quotes_pl = pl.LazyFrame(data_quotes) >>> trades_pl = pl.LazyFrame(data_trades) >>> quotes_dask = dd.from_dict(data_quotes, npartitions=2) >>> trades_dask = dd.from_dict(data_trades, npartitions=2) Let's define a dataframe-agnostic function in which we join over "datetime" and by "ticker" columns: >>> def agnostic_join_asof_datetime_by_ticker( ... df_native: IntoFrameT, ... other_native: IntoFrameT, ... ) -> IntoFrameT: ... df = nw.from_native(df_native) ... other = nw.from_native(other_native) ... return ( ... df.sort("datetime", "ticker") ... .join_asof(other, on="datetime", by="ticker") ... .sort("datetime", "ticker") ... .collect() ... .to_native() ... ) We can then pass any supported library such as Polars or Dask to `agnostic_join_asof_datetime_by_ticker`: >>> agnostic_join_asof_datetime_by_ticker(trades_pl, quotes_pl) shape: (5, 6) ┌────────────────────────────┬────────┬────────┬──────────┬───────┬────────┐ │ datetime ┆ ticker ┆ price ┆ quantity ┆ bid ┆ ask │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ datetime[ÎŒs] ┆ str ┆ f64 ┆ i64 ┆ f64 ┆ f64 │ ╞════════════════════════════╪════════╪════════╪══════════╪═══════╪════════╡ │ 2016-05-25 13:30:00.000023 ┆ MSFT ┆ 51.95 ┆ 75 ┆ 51.95 ┆ 51.96 │ │ 2016-05-25 13:30:00.000038 ┆ MSFT ┆ 51.95 ┆ 155 ┆ 51.97 ┆ 51.98 │ │ 2016-05-25 13:30:00.000048 ┆ AAPL ┆ 98.0 ┆ 100 ┆ null ┆ null │ │ 2016-05-25 13:30:00.000048 ┆ GOOG ┆ 720.77 ┆ 100 ┆ 720.5 ┆ 720.93 │ │ 2016-05-25 13:30:00.000049 ┆ GOOG ┆ 720.92 ┆ 100 ┆ 720.5 ┆ 720.93 │ └────────────────────────────┮────────┮────────┮──────────┮───────┮────────┘ >>> agnostic_join_asof_datetime_by_ticker(trades_dask, quotes_dask) datetime ticker price quantity bid ask 0 2016-05-25 13:30:00.000023 MSFT 51.95 75 51.95 51.96 0 2016-05-25 13:30:00.000038 MSFT 51.95 155 51.97 51.98 1 2016-05-25 13:30:00.000048 AAPL 98.00 100 NaN NaN 2 2016-05-25 13:30:00.000048 GOOG 720.77 100 720.50 720.93 3 2016-05-25 13:30:00.000049 GOOG 720.92 100 720.50 720.93 r³rŠr§s €r6rºzLazyFrame.join_asof s5ø€ôH‰wÑ Ø ØØØØØØØð!ó  ð r7có •—t‰|«S)u[Create a copy of this DataFrame. Returns: An identical copy of the original LazyFrame. Examples: >>> import narwhals as nw >>> import polars as pl >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2], "b": [3, 4]} >>> lf_pl = pl.LazyFrame(data) Let's define a dataframe-agnostic function in which we copy the DataFrame: >>> def agnostic_clone(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.clone().collect().to_native() We can then pass any supported library such as Polars to `agnostic_clone`: >>> agnostic_clone(lf_pl) shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 1 ┆ 3 │ │ 2 ┆ 4 │ └─────┮─────┘ r³r`s €r6r­zLazyFrame.cloneØsø€ôB‰w‰}‹Ðr7có—|S)a_Lazify the DataFrame (if possible). If a library does not support lazy execution, then this is a no-op. Returns: A LazyFrame. Examples: Construct pandas and Polars objects: >>> import pandas as pd >>> import polars as pl >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> >>> df = {"foo": [1, 2, 3], "bar": [6.0, 7.0, 8.0], "ham": ["a", "b", "c"]} >>> df_pd = pd.DataFrame(df) >>> lf_pl = pl.LazyFrame(df) We define a library agnostic function: >>> def agnostic_lazy(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.lazy().to_native() Note that then, pandas dataframe stay eager, and the Polars LazyFrame stays lazy: >>> agnostic_lazy(df_pd) foo bar ham 0 1 6.0 a 1 2 7.0 b 2 3 8.0 c >>> agnostic_lazy(lf_pl) r]r4s r6rzLazyFrame.lazyûs €ðHˆ r7có&•—t‰|||¬«S)uTake every nth row in the DataFrame and return as a new DataFrame. Arguments: n: Gather every *n*-th row. offset: Starting index. Returns: The LazyFrame containing only the selected rows. Examples: >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> from narwhals.typing import IntoFrameT >>> >>> data = {"a": [1, 2, 3, 4], "b": [5, 6, 7, 8]} >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) Let's define a dataframe-agnostic function in which we gather every 2 rows, starting from a offset of 1: >>> def agnostic_gather_every(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return df.gather_every(n=2, offset=1).collect().to_native() We can then pass any supported library such as Polars or Dask to `agnostic_gather_every`: >>> agnostic_gather_every(lf_pl) shape: (2, 2) ┌─────┬─────┐ │ a ┆ b │ │ --- ┆ --- │ │ i64 ┆ i64 │ ╞═════╪═════╡ │ 2 ┆ 6 │ │ 4 ┆ 8 │ └─────┮─────┘ >>> agnostic_gather_every(lf_dask) a b 1 2 6 3 4 8 r¯rµr¶s €r6r±zLazyFrame.gather_every!sø€ôX‰wÑ# a°Ð#Ó7Ð7r7rÊcó*•—t‰|||||¬«S)u& Unpivot a DataFrame from wide to long format. Optionally leaves identifiers set. This function is useful to massage a DataFrame into a format where one or more columns are identifier variables (index) while all other columns, considered measured variables (on), are "unpivoted" to the row axis leaving just two non-identifier columns, 'variable' and 'value'. Arguments: on: Column(s) to use as values variables; if `on` is empty all columns that are not in `index` will be used. index: Column(s) to use as identifier variables. variable_name: Name to give to the `variable` column. Defaults to "variable". value_name: Name to give to the `value` column. Defaults to "value". Returns: The unpivoted LazyFrame. Notes: If you're coming from pandas, this is similar to `pandas.DataFrame.melt`, but with `index` replacing `id_vars` and `on` replacing `value_vars`. In other frameworks, you might know this operation as `pivot_longer`. Examples: >>> import narwhals as nw >>> import polars as pl >>> import dask.dataframe as dd >>> from narwhals.typing import IntoFrameT >>> >>> data = { ... "a": ["x", "y", "z"], ... "b": [1, 3, 5], ... "c": [2, 4, 6], ... } >>> lf_pl = pl.LazyFrame(data) >>> lf_dask = dd.from_dict(data, npartitions=2) We define a library agnostic function: >>> def agnostic_unpivot(df_native: IntoFrameT) -> IntoFrameT: ... df = nw.from_native(df_native) ... return ( ... (df.unpivot(on=["b", "c"], index="a").sort(["variable", "a"])) ... .collect() ... .to_native() ... ) We can then pass any supported library such as Polars or Dask to `agnostic_unpivot`: >>> agnostic_unpivot(lf_pl) shape: (6, 3) ┌─────┬──────────┬───────┐ │ a ┆ variable ┆ value │ │ --- ┆ --- ┆ --- │ │ str ┆ str ┆ i64 │ ╞═════╪══════════╪═══════╡ │ x ┆ b ┆ 1 │ │ y ┆ b ┆ 3 │ │ z ┆ b ┆ 5 │ │ x ┆ c ┆ 2 │ │ y ┆ c ┆ 4 │ │ z ┆ c ┆ 6 │ └─────┮──────────┮───────┘ >>> agnostic_unpivot(lf_dask) a variable value 0 x b 1 1 y b 3 0 z b 5 2 x c 2 3 y c 4 1 z c 6 rœrÌrÍs €r6rÁzLazyFrame.unpivotOs%ø€ôb‰w‰Ø˜šmÈ ðó ð r7có$•—t‰||g|¢­ŽS)u×Explode the dataframe to long format by exploding the given columns. Notes: It is possible to explode multiple columns only if these columns have matching element counts. Arguments: columns: Column names. The underlying columns being exploded must be of the `List` data type. *more_columns: Additional names of columns to explode, specified as positional arguments. Returns: New LazyFrame Examples: >>> import narwhals as nw >>> from narwhals.typing import IntoFrameT >>> import polars as pl >>> data = { ... "a": ["x", "y", "z", "w"], ... "lst1": [[1, 2], None, [None], []], ... "lst2": [[3, None], None, [42], []], ... } We define a library agnostic function: >>> def agnostic_explode(df_native: IntoFrameT) -> IntoFrameT: ... return ( ... nw.from_native(df_native) ... .with_columns(nw.col("lst1", "lst2").cast(nw.List(nw.Int32()))) ... .explode("lst1", "lst2") ... .collect() ... .to_native() ... ) We can then pass any supported library such as Polars to `agnostic_explode`: >>> agnostic_explode(pl.LazyFrame(data)) shape: (5, 3) ┌─────┬──────┬──────┐ │ a ┆ lst1 ┆ lst2 │ │ --- ┆ --- ┆ --- │ │ str ┆ i32 ┆ i32 │ ╞═════╪══════╪══════╡ │ x ┆ 1 ┆ 3 │ │ x ┆ 2 ┆ null │ │ y ┆ null ┆ null │ │ z ┆ null ┆ 42 │ │ w ┆ null ┆ null │ └─────┮──────┮──────┘ rÏrÐs €r6rÊzLazyFrame.explode€sø€ôf‰w‰˜wÐ6šÒ6Ð6r7)rÌztype[DataFrame[Any]]rÑrÖrÓ)r+z str | slicerÌr )rÌzDataFrame[Any])rÌr)rÎr2rÑrÏrÐrÍrÛrÓrÔrÕrÜrÖrÞ)rfrÒrˆzLiteral['any', 'none']r‰rÔrÌrrØ)r›rÚr’rƒrÌzLazyGroupBy[Self]rÙrÛrÜràrÝrÞrßrârä)$rårærçràrérår÷rrûr,rírr_rgrarWrZrirkrprrrurzr~rŽrrr”ršrºr­rr±rÁrÊrárâs@r6rïrï× sOø„ñ ðòóðð &à ð &ð6ð &ð ó &óPðò5óð5ó@ó> ó@"CõJ.7ö`.1ö`,,ð\ôóðõ8(ð8ôóðð>B;Ø3ðB;ØDLðB;à õB;ðHD5à-ðD5ð ðD5ð õ D5õL.'ö`/öb3ðjBF÷J>ð\*.ðM ð(-Ø&*ñ M à&ðM ð%ð M ð $ð M ð ó M ð^]:ØEð]:ØVYð]:à õ]:ð@BGñjLØ(ðjLØ:>ðjLà ójLð`-2Ø ñ AXà ðAXððAXð*ð AXð ð AXð õ AXðL&*ØAHð U ð +/Ø+/ØñU àðU ð #ðU ð?ð U ð (ð U ð)ðU ððU ð õU ðv#Ø#ØØ*.Ø+/Ø%)Ø>HñM àðM ðð M ð ð M ð ð M ð(ðM ð)ðM ð #ðM ð<ðM ð õM õ^!óF$öL,8ð`&*ðS ð)-Ø$(Ø!%ñ S ØðS à "ðS ð&ð S ð "ð S ð ð S ð õS ÷j37ñ37r7rï);Ú __future__rÚtypingrrrrrr r r r r rÚwarningsrÚnarwhals.dependenciesrrÚnarwhals.schemarÚnarwhals.translaterÚnarwhals.utilsrrrrrÚiorÚpathlibrÚtypesrÚnumpyÚnpÚpandasÚpdr rÚtyping_extensionsrršrr!rMr#Únarwhals.typingr$r%r&r'r(r)r+r-rërïr]r7r6ÚrsÊðÝ"å ÝÝÝÝÝÝÝÝÝÝÝå,Ý0Ý"Ý(Ý*Ý"Ý(Ý2Ý(áÝÝÝ ãÛÛÝ&å)Ý-Ý&Ý-Ý(Ý)Ý(Ý-á  Ô -€Ù \šÔ 9€ ô] ˜‘ô] ô@ C27 ˜*Ñ%ôC27ôLd@7 ˜&Ñ!õ@7r7