docs: Explain aggregation & sorting of lists

docs/source/src/python/user-guide/expressions/lists.py

@@ -123,6 +123,79 @@
 print(result.equals(result2))
 # --8<-- [end:element-wise-regex]
 
+# --8<-- [start:children]
+df = pl.DataFrame(
+    {
+        "children": [
+            [
+                {"name": "Anne", "age": 5},
+                {"name": "Averill", "age": 7},
+            ],
+            [
+                {"name": "Brandon", "age": 12},
+                {"name": "Brooke", "age": 9},
+                {"name": "Branson", "age": 11},
+            ],
+            [{"name": "Camila", "age": 19}],
+            [
+                {"name": "Dennis", "age": 8},
+                {"name": "Doyle", "age": 11},
+                {"name": "Dina", "age": 18},
+            ],
+        ],
+    }
+)
+
+print(df)
+# --8<-- [end:children]
+
+# --8<-- [start:list-sorting]
+result = df.select(
+    pl.col("children")
+    .list.eval(
+        pl.element()
+        .sort_by(pl.element().struct.field("age"), descending=True)
+        .struct.field("name")
+    )
+    .alias("names_by_age"),
+    pl.col("children")
+    .list.eval(pl.element().struct.field("age").min())
+    .alias("min_age"),
+    pl.col("children")
+    .list.eval(pl.element().struct.field("age").max())
+    .alias("max_age"),
+)
+print(result)
+# --8<-- [end:list-sorting]
+
+# --8<-- [start:list-aggregation]
+result = df.select(
+    pl.col("children")
+    .list.eval(
+        pl.element()
+        .sort_by(pl.element().struct.field("age"), descending=True)
+        .struct.field("name")
+    )
+    .alias("names_by_age"),
+    pl.col("children")
+    .list.agg(pl.element().struct.field("age").min())
+    .alias("min_age"),
+    pl.col("children")
+    .list.agg(pl.element().struct.field("age").max())
+    .alias("max_age"),
+)
+print(result)
+# --8<-- [end:list-aggregation]
+
+# --8<-- [start:list-entropy]
+result = df.with_columns(
+    pl.col("children")
+    .list.agg(pl.element().struct.field("age").entropy())
+    .alias("age_entropy"),
+)
+print(result)
+# --8<-- [end:list-entropy]
+
 # --8<-- [start:weather_by_day]
 weather_by_day = pl.DataFrame(
     {

docs/source/src/rust/user-guide/expressions/lists.rs

@@ -35,6 +35,22 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Contribute the Rust translation of the Python example by opening a PR.
     // --8<-- [end:element-wise-regex]
 
+    // --8<-- [start:children]
+    // Contribute the Rust translation of the Python example by opening a PR.
+    // --8<-- [end:children]
+
+    // --8<-- [start:list-sorting]
+    // Contribute the Rust translation of the Python example by opening a PR.
+    // --8<-- [end:list-sorting]
+
+    // --8<-- [start:list-aggregation]
+    // Contribute the Rust translation of the Python example by opening a PR.
+    // --8<-- [end:list-aggregation]
+
+    // --8<-- [start:list-entropy]
+    // Contribute the Rust translation of the Python example by opening a PR.
+    // --8<-- [end:list-entropy]
+
     // --8<-- [start:weather_by_day]
     // Contribute the Rust translation of the Python example by opening a PR.
     // --8<-- [end:weather_by_day]

docs/source/user-guide/expressions/lists-and-arrays.md

@@ -151,10 +151,54 @@ If you are unfamiliar with the namespace `str` or the notation `(?i)` in the reg
 time to
 [look at how to work with strings and regular expressions in Polars](strings.md#check-for-the-existence-of-a-pattern).
 
+### Aggregation & sorting
+
+Like `select` on data frames, the two related functions `eval` and `agg` can also be
+used to aggregate over or sort the list elements.
+
+We'll reuse a slightly modified version of the example data from the very beginning:
+
+{{code_block('user-guide/expressions/lists', 'children', ['List'])}}
+
+```python exec="on" result="text" session="expressions/lists"
+--8<-- "python/user-guide/expressions/lists.py:children"
+```
+
+Using `eval`, we can sort the list elements or compute some aggregations:
+
+{{code_block('user-guide/expressions/lists', 'list-sorting', ['list.eval', 'Expr.sort_by'])}}
+
+```python exec="on" result="text" session="expressions/lists"
+--8<-- "python/user-guide/expressions/lists.py:list-sorting"
+```
+
+`eval` will always return a list. Use `agg` to get `min_age` and `max_age` as scalar values instead
+of single-element lists:
+
+{{code_block('user-guide/expressions/lists', 'list-aggregation', ['list.agg'])}}
+
+```python exec="on" result="text" session="expressions/lists"
+--8<-- "python/user-guide/expressions/lists.py:list-aggregation"
+```
+
+If the evaluated expression is statically determined to return only one value, `agg` will
+automatically explode the resulting list into the inner values. This matches what
+`df.group_by(...).agg(...)` does, hence the name. This is in contrast with `eval`, which will not
+perform such unwrapping.
+
+While some aggregation functions like `.list.sum()` are directly available in the `list` namespace,
+you can access more exotic aggregations like `entropy` via `agg`/`eval` only:
+
+{{code_block('user-guide/expressions/lists', 'list-entropy', ['list.agg', 'Expr.entropy'])}}
+
+```python exec="on" result="text" session="expressions/lists"
+--8<-- "python/user-guide/expressions/lists.py:list-entropy"
+```
+
 ### Row-wise computations
 
-The function `eval` gives us access to the list elements and `pl.element` refers to each individual
-element, but we can also use `pl.all()` to refer to all of the elements of the list.
+`pl.all()` can be combined with `pl.concat_list(...)` to perform row-wise aggregations over a subset
+of columns.
 
 To show this in action, we will start by creating another dataframe with some more weather data: