Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(python): Add missing examples of series/list.py #13423

Merged
merged 1 commit into from
Jan 4, 2024
Merged

docs(python): Add missing examples of series/list.py #13423

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
247 changes: 226 additions & 21 deletions py-polars/polars/series/list.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
"""
Expand Down Expand Up @@ -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:
"""
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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(
Expand All @@ -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:
Expand Down Expand Up @@ -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:
"""
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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]
]

"""

Expand Down Expand Up @@ -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")
Expand Down