diff --git a/py-polars/polars/series/list.py b/py-polars/polars/series/list.py index 22808628e0d0..45c000ed33ff 100644 --- a/py-polars/polars/series/list.py +++ b/py-polars/polars/series/list.py @@ -175,16 +175,72 @@ def sample( """ def sum(self) -> Series: - """Sum all the arrays in the list.""" + """ + Sum all the arrays in the list. + + Examples + -------- + >>> s = pl.Series("values", [[1], [2, 3]]) + >>> s.list.sum() + shape: (2,) + Series: 'values' [i64] + [ + 1 + 5 + ] + + """ def max(self) -> Series: - """Compute the max value of the arrays in the list.""" + """ + Compute the max value of the arrays in the list. + + Examples + -------- + >>> s = pl.Series("values", [[4, 1], [2, 3]]) + >>> s.list.max() + shape: (2,) + Series: 'values' [i64] + [ + 4 + 3 + ] + + """ def min(self) -> Series: - """Compute the min value of the arrays in the list.""" + """ + Compute the min value of the arrays in the list. + + Examples + -------- + >>> s = pl.Series("values", [[4, 1], [2, 3]]) + >>> s.list.min() + shape: (2,) + Series: 'values' [i64] + [ + 1 + 2 + ] + + """ def mean(self) -> Series: - """Compute the mean value of the arrays in the list.""" + """ + Compute the mean value of the arrays in the list. + + Examples + -------- + >>> s = pl.Series("values", [[3, 1], [3, 3]]) + >>> s.list.mean() + shape: (2,) + Series: 'values' [f64] + [ + 2.0 + 3.0 + ] + + """ def sort(self, *, descending: bool = False) -> Series: """ @@ -216,7 +272,21 @@ def sort(self, *, descending: bool = False) -> Series: """ def reverse(self) -> Series: - """Reverse the arrays in the list.""" + """ + Reverse the arrays in the list. + + Examples + -------- + >>> s = pl.Series("a", [[3, 2, 1], [9, 1, 2]]) + >>> s.list.reverse() + shape: (2,) + Series: 'a' [list[i64]] + [ + [1, 2, 3] + [2, 1, 9] + ] + + """ def unique(self, *, maintain_order: bool = False) -> Series: """ @@ -227,6 +297,17 @@ def unique(self, *, maintain_order: bool = False) -> Series: maintain_order Maintain order of data. This requires more work. + Examples + -------- + >>> s = pl.Series("a", [[1, 1, 2], [2, 3, 3]]) + >>> s.list.unique() + shape: (2,) + Series: 'a' [list[i64]] + [ + [1, 2] + [2, 3] + ] + """ def concat(self, other: list[Series] | Series | list[Any]) -> Series: @@ -238,6 +319,18 @@ def concat(self, other: list[Series] | Series | list[Any]) -> Series: other Columns to concat into a List Series + Examples + -------- + >>> s1 = pl.Series("a", [["a", "b"], ["c"]]) + >>> s2 = pl.Series("b", [["c"], ["d", None]]) + >>> s1.list.concat(s2) + shape: (2,) + Series: 'a' [list[str]] + [ + ["a", "b", "c"] + ["c", "d", null] + ] + """ def get(self, index: int | Series | list[int]) -> Series: @@ -253,6 +346,18 @@ def get(self, index: int | Series | list[int]) -> Series: index Index to return per sublist + Examples + -------- + >>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]]) + >>> s.list.get(0) + shape: (3,) + Series: 'a' [i64] + [ + 3 + null + 1 + ] + """ def gather( @@ -276,6 +381,19 @@ def gather( True -> set as null False -> raise an error Note that defaulting to raising an error is much cheaper + + Examples + -------- + >>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]]) + >>> s.list.gather([0, 2], null_on_oob=True) + shape: (3,) + Series: 'a' [list[i64]] + [ + [3, 1] + [null, null] + [1, null] + ] + """ def __getitem__(self, item: int) -> Series: @@ -311,10 +429,40 @@ def join(self, separator: IntoExpr) -> Series: """ def first(self) -> Series: - """Get the first value of the sublists.""" + """ + Get the first value of the sublists. + + Examples + -------- + >>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]]) + >>> s.list.first() + shape: (3,) + Series: 'a' [i64] + [ + 3 + null + 1 + ] + + """ def last(self) -> Series: - """Get the last value of the sublists.""" + """ + Get the last value of the sublists. + + Examples + -------- + >>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]]) + >>> s.list.last() + shape: (3,) + Series: 'a' [i64] + [ + 1 + null + 2 + ] + + """ def contains(self, item: float | str | bool | int | date | datetime) -> Series: """ @@ -330,6 +478,18 @@ def contains(self, item: float | str | bool | int | date | datetime) -> Series: Series Series of data type :class:`Boolean`. + Examples + -------- + >>> s = pl.Series("a", [[3, 2, 1], [], [1, 2]]) + >>> s.list.contains(1) + shape: (3,) + Series: 'a' [bool] + [ + true + false + true + ] + """ def arg_min(self) -> Series: @@ -342,6 +502,17 @@ def arg_min(self) -> Series: Series of data type :class:`UInt32` or :class:`UInt64` (depending on compilation). + Examples + -------- + >>> s = pl.Series("a", [[1, 2], [2, 1]]) + >>> s.list.arg_min() + shape: (2,) + Series: 'a' [u32] + [ + 0 + 1 + ] + """ def arg_max(self) -> Series: @@ -354,6 +525,17 @@ def arg_max(self) -> Series: Series of data type :class:`UInt32` or :class:`UInt64` (depending on compilation). + Examples + -------- + >>> s = pl.Series("a", [[1, 2], [2, 1]]) + >>> s.list.arg_max() + shape: (2,) + Series: 'a' [u32] + [ + 1 + 0 + ] + """ def diff(self, n: int = 1, null_behavior: NullBehavior = "ignore") -> Series: @@ -547,6 +729,20 @@ def count_matches( element An expression that produces a single value + Examples + -------- + >>> s = pl.Series("a", [[0], [1], [1, 2, 3, 2], [1, 2, 1], [4, 4]]) + >>> s.list.count_matches(1) + shape: (5,) + Series: 'a' [u32] + [ + 0 + 1 + 1 + 2 + 0 + ] + """ def to_array(self, width: int) -> Series: @@ -667,20 +863,15 @@ def eval(self, expr: Expr, *, parallel: bool = False) -> Series: Examples -------- - >>> df = pl.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]}) - >>> df.with_columns( - ... pl.concat_list(["a", "b"]).list.eval(pl.element().rank()).alias("rank") - ... ) - shape: (3, 3) - ┌─────┬─────┬────────────┐ - │ a ┆ b ┆ rank │ - │ --- ┆ --- ┆ --- │ - │ i64 ┆ i64 ┆ list[f64] │ - ╞═════╪═════╪════════════╡ - │ 1 ┆ 4 ┆ [1.0, 2.0] │ - │ 8 ┆ 5 ┆ [2.0, 1.0] │ - │ 3 ┆ 2 ┆ [2.0, 1.0] │ - └─────┴─────┴────────────┘ + >>> s = pl.Series("a", [[1, 4], [8, 5], [3, 2]]) + >>> s.list.eval(pl.element().rank()) + shape: (3,) + Series: 'a' [list[f64]] + [ + [1.0, 2.0] + [2.0, 1.0] + [2.0, 1.0] + ] """ @@ -772,6 +963,20 @@ def set_symmetric_difference(self, other: Series) -> Series: other Right hand side of the set operation. + Examples + -------- + >>> a = pl.Series([[1, 2, 3], [], [None, 3], [5, 6, 7]]) + >>> b = pl.Series([[2, 3, 4], [3], [3, 4, None], [6, 8]]) + >>> a.list.set_symmetric_difference(b) + shape: (4,) + Series: '' [list[i64]] + [ + [1, 4] + [3] + [4] + [5, 7, 8] + ] + """ # noqa: W505 @deprecate_renamed_function("count_matches", version="0.19.3")