Ë êñiu˜ãóŒ—ddlmZddlmZddlmZddlmZddl m Z ddl m Z erddlm Z ddlmZdd lmZmZGd „d «Zy ) é)Ú annotations)ÚSequence)Ú TYPE_CHECKING)Ú functions)Úparse_into_expression)Ú wrap_expr)ÚCallable)ÚExpr)ÚIntoExprÚIntoExprColumncó†—eZdZdZdZd.d„Zd/d„Z d0ddœ d1d„Zd2ddœd3d „Zd2ddœd3d „Z d/d „Z d/d „Z d/d „Z d4d5d„Z d4d5d„Zd/d„Zd/d„Zddœd6d„Zd/d„Zd/d„Zddœd7d„Zddœd7d„Zdddœd8d„Zd/d„Zd/d„Zd/d„Zddœd9d „Zd/d!„Zd/d"„Zddœd:d#„Zddd$œd;d%„Zdd&œdd)„Z!d4d?d*„Z"dd+œd@d,„Z#dAd-„Z$y)BÚExprArrayNameSpacez(Namespace for array related expressions.Úarrcó&—|j|_y©N)Ú_pyexpr©ÚselfÚexprs úS/var/www/pod-logistic/pod-ai/venv/lib/python3.12/site-packages/polars/expr/array.pyÚ__init__zExprArrayNameSpace.__init__s €Ø—|‘|ˆ ócóH—t|jj««S)uò Return the number of elements in each array. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.len()) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ u32 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 2 │ └─────┘ )rrÚarr_len©rs rÚlenzExprArrayNameSpace.lenó€ô*˜Ÿ™×-Ñ-Ó/Ó0Ð0rNF©Úas_arraycó‚—t|«}| t|«nd}t|jj|||««S)uù Slice every subarray. Parameters ---------- offset Start index. Negative indexing is supported. length Length of the slice. If set to `None` (default), the slice is taken to the end of the list. as_array Return result as a fixed-length `Array`, otherwise as a `List`. If true `length` and `offset` must be constant values. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.slice(0, 1)) shape: (2, 1) ┌───────────┠│ a │ │ --- │ │ list[i64] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1] │ │ [4] │ └───────────┘ >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.slice(0, 1, as_array=True)) shape: (2, 1) ┌───────────────┠│ a │ │ --- │ │ array[i64, 1] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1] │ │ [4] │ └───────────────┘ N)rrrÚ arr_slice)rÚoffsetÚlengthrÚ offset_pyexprÚ length_pyexprs rÚslicezExprArrayNameSpace.slice0s@€ôh.¨fÓ5ˆ Ø9?Ð9KÔ-¨fÔ5ÐQUˆ ܘŸ™×/Ñ/° ¸}ÈhÓWÓXÐXrcó*—|jd||¬«S)up Get the first `n` elements of the sub-arrays. Parameters ---------- n Number of values to return for each sublist. as_array Return result as a fixed-length `Array`, otherwise as a `List`. If true `n` must be a constant value. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.head(1)) shape: (2, 1) ┌───────────┠│ a │ │ --- │ │ list[i64] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1] │ │ [4] │ └───────────┘ >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.head(1, as_array=True)) shape: (2, 1) ┌───────────────┠│ a │ │ --- │ │ array[i64, 1] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1] │ │ [4] │ └───────────────┘ rr)r&)rÚnrs rÚheadzExprArrayNameSpace.headhs€ðVz‰z˜!˜Q¨ˆzÓ2Ð2rcób—t|«}t|jj||««S)un Slice the last `n` values of every sublist. Parameters ---------- n Number of values to return for each sublist. as_array Return result as a fixed-length `Array`, otherwise as a `List`. If true `n` must be a constant value. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.tail(1)) shape: (2, 1) ┌───────────┠│ a │ │ --- │ │ list[i64] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ [2] │ │ [3] │ └───────────┘ >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.tail(1, as_array=True)) shape: (2, 1) ┌───────────────┠│ a │ │ --- │ │ array[i64, 1] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [2] │ │ [3] │ └───────────────┘ )rrrÚarr_tail)rr(rÚn_pyexprs rÚtailzExprArrayNameSpace.tail•s+€ôV)¨Ó+ˆÜ˜Ÿ™×.Ñ.¨x¸ÓBÓCÐCrcóH—t|jj««S)uï Compute the min values of the sub-arrays. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.min()) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 1 │ │ 3 │ └─────┘ )rrÚarr_minrs rÚminzExprArrayNameSpace.minÃrrcóH—t|jj««S)uï Compute the max values of the sub-arrays. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.max()) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 2 │ │ 4 │ └─────┘ )rrÚarr_maxrs rÚmaxzExprArrayNameSpace.maxÚrrcóH—t|jj««S)uï Compute the sum values of the sub-arrays. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.sum()) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 3 │ │ 7 │ └─────┘ )rrÚarr_sumrs rÚsumzExprArrayNameSpace.sumñrrcóJ—t|jj|««S)u< Compute the std of the values of the sub-arrays. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.std()) shape: (2, 1) ┌──────────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•¡ │ 0.707107 │ │ 0.707107 │ └──────────┘ )rrÚarr_std©rÚddofs rÚstdzExprArrayNameSpace.stdó€ô*˜Ÿ™×-Ñ-¨dÓ3Ó4Ð4rcóJ—t|jj|««S)uö Compute the var of the values of the sub-arrays. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.var()) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 0.5 │ │ 0.5 │ └─────┘ )rrÚarr_varr9s rÚvarzExprArrayNameSpace.varr<rcóH—t|jj««S)uÿ Compute the mean of the values of the sub-arrays. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2, 3], [1, 1, 16]]}, ... schema={"a": pl.Array(pl.Int64, 3)}, ... ) >>> df.select(pl.col("a").arr.mean()) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 2.0 │ │ 6.0 │ └─────┘ )rrÚarr_meanrs rÚmeanzExprArrayNameSpace.mean6s€ô*˜Ÿ™×.Ñ.Ó0Ó1Ð1rcóH—t|jj««S)uü Compute the median of the values of the sub-arrays. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [4, 3]]}, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.select(pl.col("a").arr.median()) shape: (2, 1) ┌─────┠│ a │ │ --- │ │ f64 │ â•žâ•â•â•â•â•â•¡ │ 1.5 │ │ 3.5 │ └─────┘ )rrÚ arr_medianrs rÚmedianzExprArrayNameSpace.medianMs€ô*˜Ÿ™×0Ñ0Ó2Ó3Ð3r)Úmaintain_ordercóJ—t|jj|««S)uÇ Get the unique/distinct values in the array. Parameters ---------- maintain_order Maintain order of data. This requires more work. Examples -------- >>> df = pl.DataFrame( ... { ... "a": [[1, 1, 2]], ... }, ... schema={"a": pl.Array(pl.Int64, 3)}, ... ) >>> df.select(pl.col("a").arr.unique()) shape: (1, 1) ┌───────────┠│ a │ │ --- │ │ list[i64] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1, 2] │ └───────────┘ )rrÚ arr_unique)rrFs rÚuniquezExprArrayNameSpace.uniqueds€ô6˜Ÿ™×0Ñ0°Ó@ÓAÐArcóH—t|jj««S)uh Count the number of unique values in every sub-arrays. Examples -------- >>> df = pl.DataFrame( ... { ... "a": [[1, 1, 2], [2, 3, 4]], ... }, ... schema={"a": pl.Array(pl.Int64, 3)}, ... ) >>> df.with_columns(n_unique=pl.col("a").arr.n_unique()) shape: (2, 2) ┌───────────────┬──────────┠│ a ┆ n_unique │ │ --- ┆ --- │ │ array[i64, 3] ┆ u32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ [1, 1, 2] ┆ 2 │ │ [2, 3, 4] ┆ 3 │ └───────────────┴──────────┘ )rrÚ arr_n_uniquers rÚn_uniquezExprArrayNameSpace.n_uniques€ô.˜Ÿ™×2Ñ2Ó4Ó5Ð5rcóH—t|jj««S)u¹ Convert an Array column into a List column with the same inner data type. Returns ------- Expr Expression of data type :class:`List`. Examples -------- >>> df = pl.DataFrame( ... data={"a": [[1, 2], [3, 4]]}, ... schema={"a": pl.Array(pl.Int8, 2)}, ... ) >>> df.select(pl.col("a").arr.to_list()) shape: (2, 1) ┌──────────┠│ a │ │ --- │ │ list[i8] │ â•žâ•â•â•â•â•â•â•â•â•â•â•¡ │ [1, 2] │ │ [3, 4] │ └──────────┘ )rrÚ arr_to_listrs rÚto_listzExprArrayNameSpace.to_listšs€ô4˜Ÿ™×1Ñ1Ó3Ó4Ð4rT©Ú ignore_nullscóh—|jtj«j|¬««S)uT Evaluate whether any boolean value is true for every subarray. Parameters ---------- ignore_nulls * If set to `True` (default), null values are ignored. If there are no non-null values, the output is `False`. * If set to `False`, `Kleene logic`_ is used to deal with nulls: if the column contains any null values and no `True` values, the output is null. .. _Kleene logic: https://en.wikipedia.org/wiki/Three-valued_logic Examples -------- >>> df = pl.DataFrame( ... data={ ... "a": [ ... [True, True], ... [False, True], ... [False, False], ... [None, None], ... None, ... ] ... }, ... schema={"a": pl.Array(pl.Boolean, 2)}, ... ) >>> df.with_columns(any=pl.col("a").arr.any()) shape: (5, 2) ┌────────────────┬───────┠│ a ┆ any │ │ --- ┆ --- │ │ array[bool, 2] ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ [true, true] ┆ true │ │ [false, true] ┆ true │ │ [false, false] ┆ false │ │ [null, null] ┆ false │ │ null ┆ null │ └────────────────┴───────┘ rP)ÚaggÚFÚelementÚany©rrQs rrVzExprArrayNameSpace.any¶ó%€ðVx‰xœŸ ™ › Ÿ™°\˜ÓBÓCÐCrcóh—|jtj«j|¬««S)uV Evaluate whether all boolean values are true for every subarray. Parameters ---------- ignore_nulls * If set to `True` (default), null values are ignored. If there are no non-null values, the output is `True`. * If set to `False`, `Kleene logic`_ is used to deal with nulls: if the column contains any null values and no `False` values, the output is null. .. _Kleene logic: https://en.wikipedia.org/wiki/Three-valued_logic Examples -------- >>> df = pl.DataFrame( ... data={ ... "a": [ ... [True, True], ... [False, True], ... [False, False], ... [None, None], ... None, ... ] ... }, ... schema={"a": pl.Array(pl.Boolean, 2)}, ... ) >>> df.with_columns(all=pl.col("a").arr.all()) shape: (5, 2) ┌────────────────┬───────┠│ a ┆ all │ │ --- ┆ --- │ │ array[bool, 2] ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ [true, true] ┆ true │ │ [false, true] ┆ false │ │ [false, false] ┆ false │ │ [null, null] ┆ true │ │ null ┆ null │ └────────────────┴───────┘ rP)rSrTrUÚallrWs rrZzExprArrayNameSpace.allãrXr)Ú descendingÚ nulls_lastcóL—t|jj||««S)u¸ Sort the arrays in this column. Parameters ---------- descending Sort in descending order. nulls_last Place null values last. Examples -------- >>> df = pl.DataFrame( ... { ... "a": [[3, 2, 1], [9, 1, 2]], ... }, ... schema={"a": pl.Array(pl.Int64, 3)}, ... ) >>> df.with_columns(sort=pl.col("a").arr.sort()) shape: (2, 2) ┌───────────────┬───────────────┠│ a ┆ sort │ │ --- ┆ --- │ │ array[i64, 3] ┆ array[i64, 3] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [3, 2, 1] ┆ [1, 2, 3] │ │ [9, 1, 2] ┆ [1, 2, 9] │ └───────────────┴───────────────┘ >>> df.with_columns(sort=pl.col("a").arr.sort(descending=True)) shape: (2, 2) ┌───────────────┬───────────────┠│ a ┆ sort │ │ --- ┆ --- │ │ array[i64, 3] ┆ array[i64, 3] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [3, 2, 1] ┆ [3, 2, 1] │ │ [9, 1, 2] ┆ [9, 2, 1] │ └───────────────┴───────────────┘ )rrÚarr_sort)rr[r\s rÚsortzExprArrayNameSpace.sorts!€ôP˜Ÿ™×.Ñ.¨z¸:ÓFÓGÐGrcóH—t|jj««S)u˜ Reverse the arrays in this column. Examples -------- >>> df = pl.DataFrame( ... { ... "a": [[3, 2, 1], [9, 1, 2]], ... }, ... schema={"a": pl.Array(pl.Int64, 3)}, ... ) >>> df.with_columns(reverse=pl.col("a").arr.reverse()) shape: (2, 2) ┌───────────────┬───────────────┠│ a ┆ reverse │ │ --- ┆ --- │ │ array[i64, 3] ┆ array[i64, 3] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [3, 2, 1] ┆ [1, 2, 3] │ │ [9, 1, 2] ┆ [2, 1, 9] │ └───────────────┴───────────────┘ )rrÚ arr_reversers rÚreversezExprArrayNameSpace.reverse:s€ô.˜Ÿ™×1Ñ1Ó3Ó4Ð4rcóH—t|jj««S)uô Retrieve the index of the minimal value in every sub-array. Returns ------- Expr Expression of data type :class:`UInt32` or :class:`UInt64` (depending on compilation). Examples -------- >>> df = pl.DataFrame( ... { ... "a": [[1, 2], [2, 1]], ... }, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.with_columns(arg_min=pl.col("a").arr.arg_min()) shape: (2, 2) ┌───────────────┬─────────┠│ a ┆ arg_min │ │ --- ┆ --- │ │ array[i64, 2] ┆ u32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•¡ │ [1, 2] ┆ 0 │ │ [2, 1] ┆ 1 │ └───────────────┴─────────┘ )rrÚ arr_arg_minrs rÚarg_minzExprArrayNameSpace.arg_minSó€ô:˜Ÿ™×1Ñ1Ó3Ó4Ð4rcóH—t|jj««S)uô Retrieve the index of the maximum value in every sub-array. Returns ------- Expr Expression of data type :class:`UInt32` or :class:`UInt64` (depending on compilation). Examples -------- >>> df = pl.DataFrame( ... { ... "a": [[1, 2], [2, 1]], ... }, ... schema={"a": pl.Array(pl.Int64, 2)}, ... ) >>> df.with_columns(arg_max=pl.col("a").arr.arg_max()) shape: (2, 2) ┌───────────────┬─────────┠│ a ┆ arg_max │ │ --- ┆ --- │ │ array[i64, 2] ┆ u32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•¡ │ [1, 2] ┆ 1 │ │ [2, 1] ┆ 0 │ └───────────────┴─────────┘ )rrÚ arr_arg_maxrs rÚarg_maxzExprArrayNameSpace.arg_maxrrfr©Ú null_on_oobcób—t|«}t|jj||««S)uk Get the value by index in the sub-arrays. So index `0` would return the first item of every sublist and index `-1` would return the last item of every sublist if an index is out of bounds, it will return a `None`. Parameters ---------- index Index to return per sub-array null_on_oob Behavior if an index is out of bounds: True -> set as null False -> raise an error Examples -------- >>> df = pl.DataFrame( ... {"arr": [[1, 2, 3], [4, 5, 6], [7, 8, 9]], "idx": [1, -2, 0]}, ... schema={"arr": pl.Array(pl.Int32, 3), "idx": pl.Int32}, ... ) >>> df.with_columns(get=pl.col("arr").arr.get("idx", null_on_oob=True)) shape: (3, 3) ┌───────────────┬─────┬─────┠│ arr ┆ idx ┆ get │ │ --- ┆ --- ┆ --- │ │ array[i32, 3] ┆ i32 ┆ i32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•¡ │ [1, 2, 3] ┆ 1 ┆ 2 │ │ [4, 5, 6] ┆ -2 ┆ 5 │ │ [7, 8, 9] ┆ 0 ┆ 7 │ └───────────────┴─────┴─────┘ )rrrÚarr_get)rÚindexrkÚ index_pyexprs rÚgetzExprArrayNameSpace.get‘s+€ôF-¨UÓ3ˆ ܘŸ™×-Ñ-¨l¸KÓHÓIÐIrcó(—|jdd¬«S)u4 Get the first value of the sub-arrays. Examples -------- >>> df = pl.DataFrame( ... {"a": [[1, 2, 3], [4, 5, 6], [7, 8, 9]]}, ... schema={"a": pl.Array(pl.Int32, 3)}, ... ) >>> df.with_columns(first=pl.col("a").arr.first()) shape: (3, 2) ┌───────────────┬───────┠│ a ┆ first │ │ --- ┆ --- │ │ array[i32, 3] ┆ i32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•¡ │ [1, 2, 3] ┆ 1 │ │ [4, 5, 6] ┆ 4 │ │ [7, 8, 9] ┆ 7 │ └───────────────┴───────┘ rTrj©rprs rÚfirstzExprArrayNameSpace.first·s€ð,x‰x˜ tˆxÓ,Ð,rcó(—|jdd¬«S)u" Get the last value of the sub-arrays. Examples -------- >>> df = pl.DataFrame( ... {"a": [[1, 2, 3], [4, 5, 6], [7, 9, 8]]}, ... schema={"a": pl.Array(pl.Int32, 3)}, ... ) >>> df.with_columns(last=pl.col("a").arr.last()) shape: (3, 2) ┌───────────────┬──────┠│ a ┆ last │ │ --- ┆ --- │ │ array[i32, 3] ┆ i32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ [1, 2, 3] ┆ 3 │ │ [4, 5, 6] ┆ 6 │ │ [7, 9, 8] ┆ 8 │ └───────────────┴──────┘ éÿÿÿÿTrjrrrs rÚlastzExprArrayNameSpace.lastÏs€ð,x‰x˜¨ˆxÓ-Ð-rcóf—t|d¬«}t|jj||««S)u Join all string items in a sub-array and place a separator between them. This errors if inner type of array `!= String`. Parameters ---------- separator string to separate the items with ignore_nulls Ignore null values (default). If set to ``False``, null values will be propagated. If the sub-list contains any null values, the output is ``None``. Returns ------- Expr Expression of data type :class:`String`. Examples -------- >>> df = pl.DataFrame( ... {"s": [["a", "b"], ["x", "y"]], "separator": ["*", "_"]}, ... schema={ ... "s": pl.Array(pl.String, 2), ... "separator": pl.String, ... }, ... ) >>> df.with_columns(join=pl.col("s").arr.join(pl.col("separator"))) shape: (2, 3) ┌───────────────┬───────────┬──────┠│ s ┆ separator ┆ join │ │ --- ┆ --- ┆ --- │ │ array[str, 2] ┆ str ┆ str │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ ["a", "b"] ┆ * ┆ a*b │ │ ["x", "y"] ┆ _ ┆ x_y │ └───────────────┴───────────┴──────┘ T©Ú str_as_lit)rrrÚarr_join)rÚ separatorrQÚseparator_pyexprs rÚjoinzExprArrayNameSpace.joinçs/€ôR1°ÀtÔLÐܘŸ™×.Ñ.Ð/?ÀÓNÓOÐOr©Ú empty_as_nullÚ keep_nullscóN—t|jj||¬««S)uj Returns a column with a separate row for every array element. Parameters ---------- empty_as_null Explode an empty array into a `null`. keep_nulls Explode a `null` array into a `null`. Returns ------- Expr Expression with the data type of the array elements. Examples -------- >>> df = pl.DataFrame( ... {"a": [[1, 2, 3], [4, 5, 6]]}, schema={"a": pl.Array(pl.Int64, 3)} ... ) >>> df.select(pl.col("a").arr.explode()) shape: (6, 1) ┌─────┠│ a │ │ --- │ │ i64 │ â•žâ•â•â•â•â•â•¡ │ 1 │ │ 2 │ │ 3 │ │ 4 │ │ 5 │ │ 6 │ └─────┘ r~)rrÚ arr_explode)rrr€s rÚexplodezExprArrayNameSpace.explodes)€ôHØ L‰L× $Ñ $°=ÈZÐ $Ó Xó ð r)Ú nulls_equalcóf—t|d¬«}t|jj||««S)u¾ Check if sub-arrays contain the given item. Parameters ---------- item Item that will be checked for membership nulls_equal : bool, default True If True, treat null as a distinct value. Null values will not propagate. Returns ------- Expr Expression of data type :class:`Boolean`. Examples -------- >>> df = pl.DataFrame( ... {"a": [["a", "b"], ["x", "y"], ["a", "c"]]}, ... schema={"a": pl.Array(pl.String, 2)}, ... ) >>> df.with_columns(contains=pl.col("a").arr.contains("a")) shape: (3, 2) ┌───────────────┬──────────┠│ a ┆ contains │ │ --- ┆ --- │ │ array[str, 2] ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•¡ │ ["a", "b"] ┆ true │ │ ["x", "y"] ┆ false │ │ ["a", "c"] ┆ true │ └───────────────┴──────────┘ Trx)rrrÚ arr_contains)rÚitemr„Ú item_pyexprs rÚcontainszExprArrayNameSpace.contains;s-€ôD,¨D¸TÔBˆ ܘŸ™×2Ñ2°;À ÓLÓMÐMrcód—t|d¬«}t|jj|««S)u2 Count how often the value produced by `element` occurs. Parameters ---------- element An expression that produces a single value Examples -------- >>> df = pl.DataFrame( ... {"a": [[1, 2], [1, 1], [2, 2]]}, schema={"a": pl.Array(pl.Int64, 2)} ... ) >>> df.with_columns(number_of_twos=pl.col("a").arr.count_matches(2)) shape: (3, 2) ┌───────────────┬────────────────┠│ a ┆ number_of_twos │ │ --- ┆ --- │ │ array[i64, 2] ┆ u32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1, 2] ┆ 1 │ │ [1, 1] ┆ 0 │ │ [2, 2] ┆ 2 │ └───────────────┴────────────────┘ Trx)rrrÚarr_count_matches)rrUÚelement_pyexprs rÚ count_matchesz ExprArrayNameSpace.count_matches`s*€ô4/¨wÀ4ÔHˆÜ˜Ÿ™×7Ñ7¸ÓGÓHÐHrcó—t|t«rJt|«}|jj d«}t |«j j|«S|jj |«}t |«S)uÆ Convert the Series of type `Array` to a Series of type `Struct`. Parameters ---------- fields If the name and number of the desired fields is known in advance a list of field names can be given, which will be assigned by index. Otherwise, to dynamically assign field names, a custom function can be used; if neither are set, fields will be `field_0, field_1 .. field_n`. Examples -------- Convert array to struct with default field name assignment: >>> df = pl.DataFrame( ... {"n": [[0, 1, 2], [3, 4, 5]]}, schema={"n": pl.Array(pl.Int8, 3)} ... ) >>> df.with_columns(struct=pl.col("n").arr.to_struct()) shape: (2, 2) ┌──────────────┬───────────┠│ n ┆ struct │ │ --- ┆ --- │ │ array[i8, 3] ┆ struct[3] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ [0, 1, 2] ┆ {0,1,2} │ │ [3, 4, 5] ┆ {3,4,5} │ └──────────────┴───────────┘ Convert array to struct with field name assignment by function/index: >>> df = pl.DataFrame( ... {"n": [[0, 1, 2], [3, 4, 5]]}, schema={"n": pl.Array(pl.Int8, 3)} ... ) >>> df.select(pl.col("n").arr.to_struct(fields=lambda idx: f"n{idx}")).rows( ... named=True ... ) [{'n': {'n0': 0, 'n1': 1, 'n2': 2}}, {'n': {'n0': 3, 'n1': 4, 'n2': 5}}] Convert array to struct with field name assignment by index from a list of names: >>> df.select(pl.col("n").arr.to_struct(fields=["c1", "c2", "c3"])).rows( ... named=True ... ) [{'n': {'c1': 0, 'c2': 1, 'c3': 2}}, {'n': {'c1': 3, 'c2': 4, 'c3': 5}}] N)Ú isinstancerÚlistrÚ arr_to_structrÚstructÚ rename_fields)rÚfieldsÚ field_namesÚpyexprs rÚ to_structzExprArrayNameSpace.to_struct}sg€ôd fœhÔ 'ܘv›,ˆKØ—\‘\×/Ñ/°Ó5ˆFܘVÓ$×+Ñ+×9Ñ9¸+ÓFÐ Fà—\‘\×/Ñ/°Ó7ˆFܘVÓ$Ð $rcó`—t|«}t|jj|««S)u Shift array values by the given number of indices. Parameters ---------- n Number of indices to shift forward. If a negative value is passed, values are shifted in the opposite direction instead. Notes ----- This method is similar to the `LAG` operation in SQL when the value for `n` is positive. With a negative value for `n`, it is similar to `LEAD`. Examples -------- By default, array values are shifted forward by one index. >>> df = pl.DataFrame( ... {"a": [[1, 2, 3], [4, 5, 6]]}, schema={"a": pl.Array(pl.Int64, 3)} ... ) >>> df.with_columns(shift=pl.col("a").arr.shift()) shape: (2, 2) ┌───────────────┬───────────────┠│ a ┆ shift │ │ --- ┆ --- │ │ array[i64, 3] ┆ array[i64, 3] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1, 2, 3] ┆ [null, 1, 2] │ │ [4, 5, 6] ┆ [null, 4, 5] │ └───────────────┴───────────────┘ Pass a negative value to shift in the opposite direction instead. >>> df.with_columns(shift=pl.col("a").arr.shift(-2)) shape: (2, 2) ┌───────────────┬─────────────────┠│ a ┆ shift │ │ --- ┆ --- │ │ array[i64, 3] ┆ array[i64, 3] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1, 2, 3] ┆ [3, null, null] │ │ [4, 5, 6] ┆ [6, null, null] │ └───────────────┴─────────────────┘ )rrrÚ arr_shift)rr(r,s rÚshiftzExprArrayNameSpace.shift·s)€ô\)¨Ó+ˆÜ˜Ÿ™×/Ñ/°Ó9Ó:Ð:r©Úas_listcób—t|jj|j|¬««S)u Run any polars expression against the arrays' elements. Parameters ---------- expr Expression to run. Note that you can select an element with `pl.element()` as_list Collect the resulting data as a list. This allows for expressions which output a variable amount of data. Examples -------- >>> df = pl.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]}) >>> df.with_columns(rank=pl.concat_arr("a", "b").arr.eval(pl.element().rank())) shape: (3, 3) ┌─────┬─────┬───────────────┠│ a ┆ b ┆ rank │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ array[f64, 2] │ â•žâ•â•â•â•â•â•ªâ•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ 1 ┆ 4 ┆ [1.0, 2.0] │ │ 8 ┆ 5 ┆ [2.0, 1.0] │ │ 3 ┆ 2 ┆ [2.0, 1.0] │ └─────┴─────┴───────────────┘ See Also -------- polars.Expr.arr.agg: Evaluate any expression and automatically explode. polars.Expr.list.eval: Same for the List datatype. r›)rrÚarr_eval)rrrœs rÚevalzExprArrayNameSpace.evalès(€ô@˜Ÿ™×.Ñ.¨t¯|©|ÀWÐ.ÓMÓNÐNrcó^—t|jj|j««S)uh Run any polars aggregation expression against the arrays' elements. Parameters ---------- expr Expression to run. Note that you can select an element with `pl.element()`. Examples -------- >>> df = pl.Series( ... "a", [[1, None], [42, 13], [None, None]], pl.Array(pl.Int64, 2) ... ).to_frame() >>> df.with_columns(null_count=pl.col.a.arr.agg(pl.element().null_count())) shape: (3, 2) ┌───────────────┬────────────┠│ a ┆ null_count │ │ --- ┆ --- │ │ array[i64, 2] ┆ u32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1, null] ┆ 1 │ │ [42, 13] ┆ 0 │ │ [null, null] ┆ 2 │ └───────────────┴────────────┘ >>> df.with_columns(no_nulls=pl.col.a.arr.agg(pl.element().drop_nulls())) shape: (3, 2) ┌───────────────┬───────────┠│ a ┆ no_nulls │ │ --- ┆ --- │ │ array[i64, 2] ┆ list[i64] │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡ │ [1, null] ┆ [1] │ │ [42, 13] ┆ [42, 13] │ │ [null, null] ┆ [] │ └───────────────┴───────────┘ See Also -------- polars.Expr.arr.eval: Evaluate any expression without automatic explode. polars.Expr.list.agg: Same for the List datatype. )rrÚarr_aggrs rrSzExprArrayNameSpace.agg s#€ôT˜Ÿ™×-Ñ-¨d¯l©lÓ;Ó<Ð5ð>GLõ$JóL-ó0.ð0GKõ*PðX04Èõ& ðP?Cõ#NóJIð<EIð8%ØAð8%à ó8%ôt/;ðb38õ OôD*=rrN)Ú __future__rÚcollections.abcrÚtypingrÚpolarsrrTÚpolars._utils.parserÚpolars._utils.wraprr r Úpolars._typingr r rr¯rrúr·s/ðÝ"å$Ý å!Ý5Ý(áÝ(åß7÷c=òc=r