§ è‘ju˜ãó”—ddlmZddlmZddlmZddlmZddl m Z ddl m Z erddlm Z ddlmZdd lmZmZGd „d ¦«Zd S) é)Ú annotations)ÚSequence)Ú TYPE_CHECKING)Ú functions)Úparse_into_expression)Ú wrap_expr)ÚCallable)ÚExpr)ÚIntoExprÚIntoExprColumncót—eZdZdZdZdOd„ZdPd„Z dQd d œdRd„ZdSd d œdTd„ZdSd d œdTd„Z dPd„Z dPd„Z dPd„Z dUdVd„Z dUdVd„ZdPd„ZdPd „Zd d!œdWd#„ZdPd$„ZdPd%„Zd&d'œdXd)„Zd&d'œdXd*„Zd d d+œdYd.„ZdPd/„ZdPd0„ZdPd1„Zd d2œdZd6„ZdPd7„ZdPd8„Zd&d'œd[d;„Zd&d&d<œd\d?„Zd&d@œd]dD„Zd^dF„Z dQd_dI„Z!dUd`dJ„Z"d dKœdadM„Z#dbdN„Z$d S)cÚExprArrayNameSpacez(Namespace for array related expressions.ÚarrÚexprr ÚreturnÚNonecó—|j|_dS©N)Ú_pyexpr©Úselfrs úV/home/longshao/multi-rider-rag/.venv/lib/python3.11/site-packages/polars/expr/array.pyÚ__init__zExprArrayNameSpace.__init__s€Ø”|ˆŒ ˆ ˆ ócóN—t|j ¦«¦«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Ô0Ð0rNF©Úas_arrayÚoffsetúint | str | ExprÚlengthúint | str | Expr | Noner!Úboolcó˜—t|¦«}|t|¦«nd}t|j |||¦«¦«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)rr"r$r!Ú offset_pyexprÚ length_pyexprs rÚslicezExprArrayNameSpace.slice0sM€õh.¨fÑ5Ô5ˆ Ø9?Ð9KÕ-¨fÑ5Ô5Ð5ÐQUˆ ݘœ×/Ò/° ¸}ÈhÑWÔWÑXÔXÐXréÚncó2—| d||¬¦«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+)rr-r!s rÚheadzExprArrayNameSpace.headhs€ðVzŠz˜!˜Q¨ˆzÑ2Ô2Ð2rcóp—t|¦«}t|j ||¦«¦«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•s2€õV)¨Ñ+Ô+ˆÝ˜œ×.Ò.¨x¸ÑBÔBÑCÔCÐCrcóN—t|j ¦«¦«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óN—t|j ¦«¦«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óN—t|j ¦«¦«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ñrréÚddofÚintcóP—t|j |¦«¦«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©rr>s rÚstdzExprArrayNameSpace.stdó"€õ*˜œ×-Ò-¨dÑ3Ô3Ñ4Ô4Ð4rcóP—t|j |¦«¦«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_varrBs rÚvarzExprArrayNameSpace.varrDrcóN—t|j ¦«¦«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Ô0Ñ1Ô1Ð1rcóN—t|j ¦«¦«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Ô2Ñ3Ô3Ð3r)Úmaintain_orderrNcóP—t|j |¦«¦«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)rrNs rÚuniquezExprArrayNameSpace.uniqueds"€õ6˜œ×0Ò0°Ñ@Ô@ÑAÔAÐArcóN—t|j ¦«¦«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Ô4Ñ5Ô5Ð5rcóN—t|j ¦«¦«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Ô3Ñ4Ô4Ð4rT©Ú ignore_nullsrYcóv—| tj¦« |¬¦«¦«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 │ └────────────────┴───────┘ rX)ÚaggÚFÚelementÚany©rrYs rr^zExprArrayNameSpace.any¶ó+€ðVxŠxœ ™ œ Ÿš°\˜ÑBÔBÑCÔCÐCrcóv—| tj¦« |¬¦«¦«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 │ └────────────────┴───────┘ rX)r[r\r]Úallr_s rrbzExprArrayNameSpace.allãr`r)Ú descendingÚ nulls_lastrcrdcóR—t|j ||¦«¦«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)rrcrds rÚsortzExprArrayNameSpace.sorts%€õP˜œ×.Ò.¨z¸:ÑFÔFÑGÔGÐGrcóN—t|j ¦«¦«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Ô3Ñ4Ô4Ð4rcóN—t|j ¦«¦«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Ô3Ñ4Ô4Ð4rcóN—t|j ¦«¦«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_maxrrnr©Ú null_on_oobÚindexúint | IntoExprColumnrscóp—t|¦«}t|j ||¦«¦«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)rrtrsÚ index_pyexprs rÚgetzExprArrayNameSpace.get‘s2€õF-¨UÑ3Ô3ˆ ݘœ×-Ò-¨l¸KÑHÔHÑIÔIÐIrcó0—| dd¬¦«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 │ └───────────────┴───────┘ rTrr©ryrs rÚfirstzExprArrayNameSpace.first·s€ð,xŠx˜ tˆxÑ,Ô,Ð,rcó0—| dd¬¦«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 │ └───────────────┴──────┘ éÿÿÿÿTrrr{rs rÚlastzExprArrayNameSpace.lastÏs€ð,xŠx˜¨ˆxÑ-Ô-Ð-rÚ separatorr cót—t|d¬¦«}t|j ||¦«¦«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)rr€rYÚseparator_pyexprs rÚjoinzExprArrayNameSpace.joinçs9€õR1°ÀtÐLÑLÔLÐݘœ×.Ò.Ð/?ÀÑNÔNÑOÔOÐOr©Ú empty_as_nullÚ keep_nullsrˆr‰cóT—t|j ||¬¦«¦«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)rrˆr‰s rÚexplodezExprArrayNameSpace.explodes/€õHØ ŒL× $Ò $°=ÈZÐ $Ñ XÔ Xñ ô ð r)Ú nulls_equalÚitemr rcót—t|d¬¦«}t|j ||¦«¦«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 │ └───────────────┴──────────┘ Tr‚)rrrÚ arr_contains)rrŽrÚ item_pyexprs rÚcontainszExprArrayNameSpace.contains;s7€õD,¨D¸TÐBÑBÔBˆ ݘœ×2Ò2°;À ÑLÔLÑMÔMÐMrr]cór—t|d¬¦«}t|j |¦«¦«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 │ └───────────────┴────────────────┘ Tr‚)rrrÚarr_count_matches)rr]Úelement_pyexprs rÚ count_matchesz ExprArrayNameSpace.count_matches`s4€õ4/¨wÀ4ÐHÑHÔHˆÝ˜œ×7Ò7¸ÑGÔGÑHÔHÐHrÚfieldsú+Sequence[str] | Callable[[int], str] | Nonecó—t|t¦«rPt|¦«}|j d¦«}t |¦«j |¦«S|j |¦«}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)rr—Ú field_namesÚpyexprs rÚ to_structzExprArrayNameSpace.to_struct}sy€õd fhÑ 'Ô 'ð %ݘv™,œ,ˆKØ”\×/Ò/°Ñ5Ô5ˆFݘVÑ$Ô$Ô+×9Ò9¸+ÑFÔFÐ Fà”\×/Ò/°Ñ7Ô7ˆFݘVÑ$Ô$Ð $rcón—t|¦«}t|j |¦«¦«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-r2s rÚshiftzExprArrayNameSpace.shift·s0€õ\)¨Ñ+Ô+ˆÝ˜œ×/Ò/°Ñ9Ô9Ñ:Ô:Ð:r©Úas_listr¦có^—t|j |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ÔMÑNÔNÐNrcóZ—t|j |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 rr[zExprArrayNameSpace.agg s%€õT˜œ×-Ò-¨d¬lÑ;Ô;Ñ<Ô<Ðr?rr )rNr&rr )rYr&rr )rcr&rdr&rr )rtrursr&rr )r€r rYr&rr )rˆr&r‰r&rr )rŽr rr&rr )r]r rr )r—r˜rr )r-rurr )rr r¦r&rr )rr rr )%Ú__name__Ú __module__Ú __qualname__Ú__doc__Ú _accessorrrr+r/r3r6r9r<rCrGrJrMrQrTrWr^rbrgrjrmrqryr|rr†rŒr’r–r¡r¤r©r[©rrrrsÔ€€€€€Ø2Ð2à€Ið$ð$ð$ð$ð1ð1ð1ð1ð4+/ð6Yð ð 6Yð6Yð6Yð6Yð6Yð6Yðp+3Àð+3ð+3ð+3ð+3ð+3ð+3ðZ,DÀð,Dð,Dð,Dð,Dð,Dð,Dð\1ð1ð1ð1ð.1ð1ð1ð1ð.1ð1ð1ð1ð.5ð5ð5ð5ð5ð.5ð5ð5ð5ð5ð.2ð2ð2ð2ð.4ð4ð4ð4ð.05ðBðBðBðBðBðBð:6ð6ð6ð6ð25ð5ð5ð5ð8+/ð+Dð+Dð+Dð+Dð+Dð+DðZ+/ð+Dð+Dð+Dð+Dð+Dð+DðZ*/À5ð(Hð(Hð(Hð(Hð(Hð(HðT5ð5ð5ð5ð25ð5ð5ð5ð>5ð5ð5ð5ð>GLð$Jð$Jð$Jð$Jð$Jð$JðL-ð-ð-ð-ð0.ð.ð.ð.ð0GKð*Pð*Pð*Pð*Pð*Pð*PðX04Èð& ð& ð& ð& ð& ð& ðP?Cð#Nð#Nð#Nð#Nð#Nð#NðJIðIðIðIð<EIð8%ð8%ð8%ð8%ð8%ðt/;ð/;ð/;ð/;ð/;ðb38ð Oð Oð Oð Oð Oð OðD*=ð*=ð*=ð*=ð*=ð*=rrN)Ú __future__rÚcollections.abcrÚtypingrÚpolarsrr\Úpolars._utils.parserÚpolars._utils.wraprr r Úpolars._typingr r rr±rrúr¹sñðØ"Ð"Ð"Ð"Ð"Ð"à$Ð$Ð$Ð$Ð$Ð$Ø Ð Ð Ð Ð Ð à!Ð!Ð!Ð!Ð!Ð!Ø5Ð5Ð5Ð5Ð5Ð5Ø(Ð(Ð(Ð(Ð(Ð(àð8Ø(Ð(Ð(Ð(Ð(Ð(àÐÐÐÐÐØ7Ð7Ð7Ð7Ð7Ð7Ð7Ð7ðc=ðc=ðc=ðc=ðc=ñc=ôc=ðc=ðc=ðc=r