jUddlmZddlmZddlmZddlmZddl m Z er"ddl m Z m Z ddlmZddlmZdd lmZmZdd lmZe Gd d Zd S)) annotations) TYPE_CHECKING) functions)wrap_s) expr_dispatch)CallableSequence)Series)PySeries)IntoExprIntoExprColumn)ExprcveZdZdZdZdRdZdSdZdSd ZdSd ZdSd Z dTdUdZ dTdUdZ dSdZ dddVdZ dSdZdSdZdddWdZdSdZ dXdddYd%ZdZddd[d(ZdZddd[d)ZdddWd*Zdddd+d\d/ZdSd0ZdSd1ZdSd2Zdd3d]d7ZdSd8ZdSd9Zddd^d<Zddd=d_d@ZddAd`dEZdadGZ dXdbdJZ!dTdcdKZ"ddLdddPZ#dedQZ$dS)fArrayNameSpacez$Namespace for array related methods.arrseriesr returnNonec|j|_dSN)_s)selfrs X/home/longshao/multi-rider-rag/.venv/lib/python3.11/site-packages/polars/series/array.py__init__zArrayNameSpace.__init__s"IcdS)a" Compute the min values of the sub-arrays. Examples -------- >>> s = pl.Series("a", [[1, 2], [4, 3]], dtype=pl.Array(pl.Int64, 2)) >>> s.arr.min() shape: (2,) Series: 'a' [i64] [ 1 3 ] Nrs rminzArrayNameSpace.minrcdS)a" Compute the max values of the sub-arrays. Examples -------- >>> s = pl.Series("a", [[1, 2], [4, 3]], dtype=pl.Array(pl.Int64, 2)) >>> s.arr.max() shape: (2,) Series: 'a' [i64] [ 2 4 ] Nrrs rmaxzArrayNameSpace.max+r rcdS)a Compute the sum values of the sub-arrays. Notes ----- If there are no non-null elements in a row, the output is `0`. Examples -------- >>> s = pl.Series([[1, 2], [4, 3]], dtype=pl.Array(pl.Int64, 2)) >>> s.arr.sum() shape: (2,) Series: '' [i64] [ 3 7 ] Nrrs rsumzArrayNameSpace.sum;r rcdS)a/ Compute the mean of the values of the sub-arrays. Examples -------- >>> s = pl.Series("a", [[1, 2], [4, 3]], dtype=pl.Array(pl.Int64, 2)) >>> s.arr.mean() shape: (2,) Series: 'a' [f64] [ 1.5 3.5 ] Nrrs rmeanzArrayNameSpace.meanOr rddofintcdS)a7 Compute the std of the values of the sub-arrays. Examples -------- >>> s = pl.Series("a", [[1, 2], [4, 3]], dtype=pl.Array(pl.Int64, 2)) >>> s.arr.std() shape: (2,) Series: 'a' [f64] [ 0.707107 0.707107 ] Nrrr(s rstdzArrayNameSpace.std_r rcdS)a5 Compute the var of the values of the sub-arrays. Examples -------- >>> s = pl.Series("a", [[1, 2], [4, 3]], dtype=pl.Array(pl.Int64, 2)) >>> s.arr.var() shape: (2,) Series: 'a' [f64] [ 0.5 0.5 ] Nrr+s rvarzArrayNameSpace.varor rcdS)a3 Compute the median of the values of the sub-arrays. Examples -------- >>> s = pl.Series("a", [[1, 2], [4, 3]], dtype=pl.Array(pl.Int64, 2)) >>> s.arr.median() shape: (2,) Series: 'a' [f64] [ 1.5 3.5 ] Nrrs rmedianzArrayNameSpace.medianr rF)maintain_orderr1boolcdS)a Get the unique/distinct values in the array. Parameters ---------- maintain_order Maintain order of data. This requires more work. Returns ------- Series Series of data type :class:`List`. Examples -------- >>> s = pl.Series([[1, 1, 2], [3, 4, 5]], dtype=pl.Array(pl.Int64, 3)) >>> s.arr.unique() shape: (2,) Series: '' [list[i64]] [ [1, 2] [3, 4, 5] ] Nr)rr1s runiquezArrayNameSpace.uniquer rcdS)a4 Count the number of unique values in every sub-arrays. Examples -------- >>> s = pl.Series("a", [[1, 2], [4, 4]], dtype=pl.Array(pl.Int64, 2)) >>> s.arr.n_unique() shape: (2,) Series: 'a' [u32] [ 2 1 ] Nrrs rn_uniquezArrayNameSpace.n_uniquer rcdS)a Convert an Array column into a List column with the same inner data type. Returns ------- Series Series of data type :class:`List`. Examples -------- >>> s = pl.Series([[1, 2], [3, 4]], dtype=pl.Array(pl.Int8, 2)) >>> s.arr.to_list() shape: (2,) Series: '' [list[i8]] [ [1, 2] [3, 4] ] Nrrs rto_listzArrayNameSpace.to_listr rT) ignore_nullsr9cdS)a 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 Returns ------- Series Series of data type :class:`Boolean`. Examples -------- >>> s = pl.Series( ... [[True, True], [False, True], [False, False], [None, None], None], ... dtype=pl.Array(pl.Boolean, 2), ... ) >>> s.arr.any() shape: (5,) Series: '' [bool] [ true true false false null ] Nrrr9s ranyzArrayNameSpace.anyr rcdS)a Return the number of elements in each array. Returns ------- Series Series of data type :class:`UInt32`. Examples -------- >>> s = pl.Series("a", [[1, 2], [4, 3]], dtype=pl.Array(pl.Int64, 2)) >>> s.arr.len() shape: (2,) Series: 'a' [u32] [ 2 2 ] Nrrs rlenzArrayNameSpace.lenr rN)as_arrayoffset int | Exprlengthint | Expr | Noner?cdS)u Slice the sub-arrays. Parameters ---------- offset The starting index of the slice. length The length of the slice. as_array Return the result as a Series of data type :class:`.Array`. Returns ------- Series Series of data type :class:`.List` or :class:`.Array` if `as_array=True`. Examples -------- >>> s = pl.Series( ... [[1, 2, 3, 4, 5, 6], [7, 8, 9, 10, 11, 12]], ... dtype=pl.Array(pl.Int64, 6), ... ) >>> s.arr.slice(1) shape: (2,) Series: '' [list[i64]] [ [2, 3, … 6] [8, 9, … 12] ] >>> s.arr.slice(1, 3, as_array=True) shape: (2,) Series: '' [array[i64, 3]] [ [2, 3, 4] [8, 9, 10] ] >>> s.arr.slice(-2) shape: (2,) Series: '' [list[i64]] [ [5, 6] [11, 12] ] Nr)rr@rBr?s rslicezArrayNameSpace.slice r rncdS)u# 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 -------- >>> s = pl.Series( ... [[1, 2, 3, 4, 5, 6], [7, 8, 9, 10, 11, 12]], ... dtype=pl.Array(pl.Int64, 6), ... ) >>> s.arr.head() shape: (2,) Series: '' [list[i64]] [ [1, 2, … 5] [7, 8, … 11] ] >>> s.arr.head(3, as_array=True) shape: (2,) Series: '' [array[i64, 3]] [ [1, 2, 3] [7, 8, 9] ] NrrrGr?s rheadzArrayNameSpace.head>r rcdS)u$ 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 -------- >>> s = pl.Series( ... [[1, 2, 3, 4, 5, 6], [7, 8, 9, 10, 11, 12]], ... dtype=pl.Array(pl.Int64, 6), ... ) >>> s.arr.tail() shape: (2,) Series: '' [list[i64]] [ [2, 3, … 6] [8, 9, … 12] ] >>> s.arr.tail(3, as_array=True) shape: (2,) Series: '' [array[i64, 3]] [ [4, 5, 6] [10, 11, 12] ] NrrIs rtailzArrayNameSpace.tail`r rcdS)a 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 Returns ------- Series Series of data type :class:`Boolean`. Examples -------- >>> s = pl.Series( ... [[True, True], [False, True], [False, False], [None, None], None], ... dtype=pl.Array(pl.Boolean, 2), ... ) >>> s.arr.all() shape: (5,) Series: '' [bool] [ true false false true null ] Nrr;s rallzArrayNameSpace.allr r) descending nulls_last multithreadedrOrPrQcdS)a Sort the arrays in this column. Parameters ---------- descending Sort in descending order. nulls_last Place null values last. multithreaded Sort using multiple threads. Examples -------- >>> s = pl.Series("a", [[3, 2, 1], [9, 1, 2]], dtype=pl.Array(pl.Int64, 3)) >>> s.arr.sort() shape: (2,) Series: 'a' [array[i64, 3]] [ [1, 2, 3] [1, 2, 9] ] >>> s.arr.sort(descending=True) shape: (2,) Series: 'a' [array[i64, 3]] [ [3, 2, 1] [9, 2, 1] ] Nr)rrOrPrQs rsortzArrayNameSpace.sortr rcdS)a@ Reverse the arrays in this column. Examples -------- >>> s = pl.Series("a", [[3, 2, 1], [9, 1, 2]], dtype=pl.Array(pl.Int64, 3)) >>> s.arr.reverse() shape: (2,) Series: 'a' [array[i64, 3]] [ [1, 2, 3] [2, 1, 9] ] Nrrs rreversezArrayNameSpace.reverser rcdS)a Retrieve the index of the minimal value in every sub-array. Returns ------- Series Series of data type :class:`UInt32` or :class:`UInt64` (depending on compilation). Examples -------- >>> s = pl.Series("a", [[3, 2, 1], [9, 1, 2]], dtype=pl.Array(pl.Int64, 3)) >>> s.arr.arg_min() shape: (2,) Series: 'a' [u32] [ 2 1 ] Nrrs rarg_minzArrayNameSpace.arg_minr rcdS)a Retrieve the index of the maximum value in every sub-array. Returns ------- Series Series of data type :class:`UInt32` or :class:`UInt64` (depending on compilation). Examples -------- >>> s = pl.Series("a", [[0, 9, 3], [9, 1, 2]], dtype=pl.Array(pl.Int64, 3)) >>> s.arr.arg_max() shape: (2,) Series: 'a' [u32] [ 1 0 ] Nrrs rarg_maxzArrayNameSpace.arg_maxr r) null_on_oobindexint | IntoExprColumnrZcdS)a 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 sublist null_on_oob Behavior if an index is out of bounds: True -> set as null False -> raise an error Returns ------- Series Series of innter data type. Examples -------- >>> s = pl.Series( ... "a", [[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype=pl.Array(pl.Int32, 3) ... ) >>> s.arr.get(pl.Series([1, -2, 0]), null_on_oob=True) shape: (3,) Series: 'a' [i32] [ 2 5 7 ] Nr)rr[rZs rgetzArrayNameSpace.getr rcdS)a_ Get the first value of the sub-arrays. Examples -------- >>> s = pl.Series( ... "a", [[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype=pl.Array(pl.Int32, 3) ... ) >>> s.arr.first() shape: (3,) Series: 'a' [i32] [ 1 4 7 ] Nrrs rfirstzArrayNameSpace.first4r rcdS)a] Get the last value of the sub-arrays. Examples -------- >>> s = pl.Series( ... "a", [[1, 2, 3], [4, 5, 6], [7, 9, 8]], dtype=pl.Array(pl.Int32, 3) ... ) >>> s.arr.last() shape: (3,) Series: 'a' [i32] [ 3 6 8 ] Nrrs rlastzArrayNameSpace.lastHr r separatorr cdS)a+ 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 ------- Series Series of data type :class:`String`. Examples -------- >>> s = pl.Series([["x", "y"], ["a", "b"]], dtype=pl.Array(pl.String, 2)) >>> s.arr.join(separator="-") shape: (2,) Series: '' [str] [ "x-y" "a-b" ] Nr)rrcr9s rjoinzArrayNameSpace.join\r r) empty_as_null keep_nullsrfrgcdS)a 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 ------- Series Series with the data type of the array elements. Examples -------- >>> s = pl.Series("a", [[1, 2, 3], [4, 5, 6]], dtype=pl.Array(pl.Int64, 3)) >>> s.arr.explode() shape: (6,) Series: 'a' [i64] [ 1 2 3 4 5 6 ] Nr)rrfrgs rexplodezArrayNameSpace.explode~r r) nulls_equalitemr rjcdS)a 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 ------- Series Series of data type :class:`Boolean`. Examples -------- >>> s = pl.Series( ... "a", [[3, 2, 1], [1, 2, 3], [4, 5, 6]], dtype=pl.Array(pl.Int32, 3) ... ) >>> s.arr.contains(1) shape: (3,) Series: 'a' [bool] [ true true false ] Nr)rrkrjs rcontainszArrayNameSpace.containsr relementcdS)a Count how often the value produced by `element` occurs. Parameters ---------- element An expression that produces a single value Examples -------- >>> s = pl.Series("a", [[1, 2, 3], [2, 2, 2]], dtype=pl.Array(pl.Int64, 3)) >>> s.arr.count_matches(2) shape: (2,) Series: 'a' [u32] [ 1 3 ] Nr)rrns r count_matcheszArrayNameSpace.count_matchesr rfields+Callable[[int], str] | Sequence[str] | Nonect|j}|t j|jj| 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: >>> s1 = pl.Series("n", [[0, 1, 2], [3, 4, 5]], dtype=pl.Array(pl.Int8, 3)) >>> s2 = s1.arr.to_struct() >>> s2 shape: (2,) Series: 'n' [struct[3]] [ {0,1,2} {3,4,5} ] >>> s2.struct.fields ['field_0', 'field_1', 'field_2'] Convert array to struct with field name assignment by function/index: >>> s3 = s1.arr.to_struct(fields=lambda idx: f"n{idx:02}") >>> s3.struct.fields ['n00', 'n01', 'n02'] Convert array to struct with field name assignment by index from a list of names: >>> s1.arr.to_struct(fields=["one", "two", "three"]).struct.unnest() shape: (2, 3) ┌─────┬─────┬───────┐ │ one ┆ two ┆ three │ │ --- ┆ --- ┆ --- │ │ i8 ┆ i8 ┆ i8 │ ╞═════╪═════╪═══════╡ │ 0 ┆ 1 ┆ 2 │ │ 3 ┆ 4 ┆ 5 │ └─────┴─────┴───────┘ ) rrto_frameselectFcolnamer to_struct to_series)rrqss rryzArrayNameSpace.to_structsUf 47OOzz||""15==#4#>#>v#F#FGGQQSSSrcdS)a 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. >>> s = pl.Series([[1, 2, 3], [4, 5, 6]], dtype=pl.Array(pl.Int64, 3)) >>> s.arr.shift() shape: (2,) Series: '' [array[i64, 3]] [ [null, 1, 2] [null, 4, 5] ] Pass a negative value to shift in the opposite direction instead. >>> s.arr.shift(-2) shape: (2,) Series: '' [array[i64, 3]] [ [3, null, null] [6, null, null] ] Nr)rrGs rshiftzArrayNameSpace.shift r r)as_listexprrr~cdS)a 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 -------- >>> s = pl.Series("a", [[1, 4], [8, 5], [3, 2]], pl.Array(pl.Int64, 2)) >>> s.arr.eval(pl.element().rank()) shape: (3,) Series: 'a' [array[f64, 2]] [ [1.0, 2.0] [2.0, 1.0] [2.0, 1.0] ] Nr)rrr~s revalzArrayNameSpace.eval1r rcdS)a 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 -------- >>> s = pl.Series( ... "a", [[1, None], [42, 13], [None, None]], pl.Array(pl.Int64, 2) ... ) >>> s.arr.agg(pl.element().null_count()) shape: (3,) Series: 'a' [u32] [ 1 0 2 ] >>> s.arr.agg(pl.element().drop_nulls()) shape: (3,) Series: 'a' [list[i64]] [ [1] [42, 13] [] ] Nr)rrs raggzArrayNameSpace.aggJr r)rr rr)rr )r')r(r)rr )r1r2rr )r9r2rr r)r@rArBrCr?r2rr )rF)rGrAr?r2rr )rOr2rPr2rQr2rr )r[r\rZr2rr )rcr r9r2rr )rfr2rgr2rr )rkr rjr2rr )rnr rr )rqrrrr )rGr\rr )rrr~r2rr )rrrr )%__name__ __module__ __qualname____doc__ _accessorrrr"r$r&r,r.r0r4r6r8r<r>rErJrLrNrSrUrWrYr^r`rbrerirmrpryr}rrrrrrrs..I&&&&            (                  05      4        *+/$ $ $ $ $ $ L    0%)3  3 3 3 3 3 3 j  %       D  %       D+/$ $ $ $ $ $ R! " % % % % % % N    "    .    .GL$ $ $ $ $ $ L    (    (GK       D04      @?C      @    0?C4T4T4T4T4Tl% % % % % N38      2      rrN) __future__rtypingrpolarsrrvpolars._utils.wraprpolars.series.utilsrcollections.abcrr r polars._plrr polars._typingr r polars.expr.exprrrrrrrs"""""" !!!!!!%%%%%%------&22222222$$$$$$77777777%%%%%%U  U  U  U  U  U  U  U  U  U  r