o ¹­§iS”ã@szddlmZddlmZddlmZddlmZddlm Z er4ddlm Z ddl m Z ddl mZmZGd d „d ƒZd S) é)Ú annotations)ÚSequence)Ú TYPE_CHECKING)Úparse_into_expression)Ú wrap_expr)ÚCallable)ÚExpr)ÚIntoExprÚIntoExprColumnc@s¦eZdZdZdZdodd„Zdpd d „Z dqd d œdrdd„Zdsd d œdtdd„Zdsd d œdtdd„Z dpdd„Z dpdd„Z dpd d!„Z dudvd%d&„Z dudvd'd(„Zdpd)d*„Zdpd+d,„Zd d-œdwd/d0„Zdpd1d2„Zdpd3d4„Zdpd5d6„Zdpd7d8„Zd d d9œdxdd?„Zdpd@dA„ZdpdBdC„Zd dDœdydHdI„ZdpdJdK„ZdpdLdM„ZdNdOœdzdSdT„ZdNdNdUœd{dXdY„ZdNdZœd|d^d_„Zd}dadb„Z dqd~dedf„Z!duddgdh„Z"d diœd€dkdl„Z#ddmdn„Z$d S)‚ÚExprArrayNameSpacez(Namespace for array related expressions.ZarrÚexprrÚreturnÚNonecCs |j|_dS©N)Ú_pyexpr©Úselfr ©rúH/home/app/Keep/.python/lib/python3.10/site-packages/polars/expr/array.pyÚ__init__s zExprArrayNameSpace.__init__cCó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 │ └─────┘ )rrZarr_len©rrrrÚlenózExprArrayNameSpace.lenNF©Úas_arrayÚoffsetúint | str | ExprÚlengthúint | str | Expr | NonerÚboolcCs0t|ƒ}|dur 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)rrrZ arr_slice)rrrrZ offset_pyexprZ length_pyexprrrrÚslice/s4zExprArrayNameSpace.sliceéÚncCs|jd||dS)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#rrrrÚheadgs+zExprArrayNameSpace.headcCó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] │ └───────────────┘ )rrrZarr_tail)rr#rÚn_pyexprrrrÚtail”s+zExprArrayNameSpace.tailcCr)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 │ └─────┘ )rrZarr_minrrrrÚminÂrzExprArrayNameSpace.mincCr)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 │ └─────┘ )rrZarr_maxrrrrÚmaxÙrzExprArrayNameSpace.maxcCr)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 │ └─────┘ )rrZarr_sumrrrrÚsumðrzExprArrayNameSpace.suméÚddofÚintcCó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 │ └──────────┘ )rrZarr_std©rr,rrrÚstdózExprArrayNameSpace.stdcCr.)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 │ └─────┘ )rrZarr_varr/rrrÚvarr1zExprArrayNameSpace.varcCr)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 │ └─────┘ )rrZarr_meanrrrrÚmean5rzExprArrayNameSpace.meancCr)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 │ └─────┘ )rrZ arr_medianrrrrÚmedianLrzExprArrayNameSpace.median)Úmaintain_orderr5cCr.)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] │ └───────────┘ )rrZ arr_unique)rr5rrrÚuniquecszExprArrayNameSpace.uniquecCr)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 │ └───────────────┴──────────┘ )rrZ arr_n_uniquerrrrÚn_unique€ózExprArrayNameSpace.n_uniquecCr)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] │ └──────────┘ )rrZ arr_to_listrrrrÚto_list™szExprArrayNameSpace.to_listcCr)u… Evaluate whether any boolean value is true for every subarray. 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 │ └────────────────┴───────┘ )rrZarr_anyrrrrÚanyµó zExprArrayNameSpace.anycCr)u‡ Evaluate whether all boolean values are true for every subarray. 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 │ └────────────────┴───────┘ )rrZarr_allrrrrÚall×r;zExprArrayNameSpace.all)Ú descendingÚ nulls_lastr=r>cCst|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] │ └───────────────┴───────────────┘ )rrZarr_sort)rr=r>rrrÚsortùs(zExprArrayNameSpace.sortcCr)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] │ └───────────────┴───────────────┘ )rrZ arr_reverserrrrÚreverse#r8zExprArrayNameSpace.reversecCr)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 │ └───────────────┴─────────┘ )rrZ arr_arg_minrrrrÚarg_min<ózExprArrayNameSpace.arg_mincCr)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 │ └───────────────┴─────────┘ )rrZ arr_arg_maxrrrrÚarg_max[rBzExprArrayNameSpace.arg_max©Ú null_on_oobÚindexúint | IntoExprColumnrEcCr%)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 │ └───────────────┴─────┴─────┘ )rrrZarr_get)rrFrEZ index_pyexprrrrÚgetzs#zExprArrayNameSpace.getcCó|jdddS)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 │ └───────────────┴───────┘ rTrD©rHrrrrÚfirst ózExprArrayNameSpace.firstcCrI)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 │ └───────────────┴──────┘ éÿÿÿÿTrDrJrrrrÚlast¸rLzExprArrayNameSpace.lastT)Ú ignore_nullsÚ separatorr rOcCót|dd}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©Z str_as_lit)rrrZarr_join)rrPrOZseparator_pyexprrrrÚjoinÐs )zExprArrayNameSpace.join©Ú empty_as_nullÚ keep_nullsrUrVcCst|jj||dƒ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 │ └─────┘ rT)rrZ arr_explode)rrUrVrrrÚexplodeüs$ÿzExprArrayNameSpace.explode)Ú nulls_equalÚitemr rXcCrQ)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 │ └───────────────┴──────────┘ TrR)rrrZ arr_contains)rrYrXZ item_pyexprrrrÚcontains$s "zExprArrayNameSpace.containsÚelementcCst|dd}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 │ └───────────────┴────────────────┘ TrR)rrrZarr_count_matches)rr[Zelement_pyexprrrrÚ count_matchesIs z ExprArrayNameSpace.count_matchesÚfieldsú+Sequence[str] | Callable[[int], str] | NonecCsBt|tƒrt|ƒ}|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ÚlistrZ arr_to_structrÚstructZ rename_fields)rr]Ú field_namesZpyexprrrrÚ to_structfs 2  zExprArrayNameSpace.to_structcCst|ƒ}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] │ └───────────────┴─────────────────┘ )rrrZ arr_shift)rr#r&rrrÚshift s.zExprArrayNameSpace.shift©Úas_listrfcCst|jj|j|dƒ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. re)rrZarr_eval)rr rfrrrÚevalÑs zExprArrayNameSpace.evalcCst|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. )rrZarr_aggrrrrÚaggós*zExprArrayNameSpace.agg)r rr r)r rr)rrrrrr r r)r")r#rrr r r)r+)r,r-r r)r5r r r)r=r r>r r r)rFrGrEr r r)rPr rOr r r)rUr rVr r r)rYr rXr r r)r[r r r)r]r^r r)r#rGr r)r rrfr r r)r rr r)%Ú__name__Ú __module__Ú __qualname__Ú__doc__Ú _accessorrrr!r$r'r(r)r*r0r2r3r4r6r7r9r:r<r?r@rArCrHrKrNrSrWrZr\rcrdrgrhrrrrr sN  ýû8- .          "" *   & ,( % ÿ :1"r N)Ú __future__rÚcollections.abcrÚtypingrZpolars._utils.parserZpolars._utils.wraprrZpolarsrZpolars._typingr r r rrrrÚs