Code example in keep_name does not show functionality

[mcrumiller]

Polars version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of Polars.

Issue description

In the documentation for keep_name, the output of the example is the same in the case where keep_name is not used and when it's used:

Examples

A groupby aggregation often changes the name of a column. With keep_name we can keep the original name of the column

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": ["a", "b", None],
...     }
... )
>>> df.groupby("a").agg(pl.col("b").list()).sort(by="a")
shape: (3, 2)
┌─────┬───────────┐
│ a   ┆ b         │
│ --- ┆ ---       │
│ i64 ┆ list[str] │
╞═════╪═══════════╡
│ 1   ┆ ["a"]     │
├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ 2   ┆ ["b"]     │
├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ 3   ┆ [null]    │
└─────┴───────────┘

Keep the original column name:

>>> df.groupby("a").agg(pl.col("b").list().keep_name()).sort(by="a")
shape: (3, 2)
┌─────┬───────────┐
│ a   ┆ b         │
│ --- ┆ ---       │
│ i64 ┆ list[str] │
╞═════╪═══════════╡
│ 1   ┆ ["a"]     │
├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ 2   ┆ ["b"]     │
├╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┤
│ 3   ┆ [null]    │
└─────┴───────────┘

Reproducible example

n/a

Expected behavior

The example should show a change in behavior when keep_name is used. The first example needs to be a case whereby the column name changes.

I can't seem to find such an instance, but if someone wants to point me to an example where the column name changes, I can create a PR.

Installed versions

Replace this line with the output of pl.show_versions(), leave the backticks in place

[ritchie46]

Right! Can you think of one? Maybe one where we do multicolumn arithmetic. (6 * pl.all()).keep_name()

[mcrumiller]

Multi-column arithmetic doesn't seem to change the name either. A simple example would be something like:

df = pl.DataFrame({
    'a': [1, 2, 3, 4, 5]
})
df.select(pl.col('a').alias('b'))

shape: (5, 1)
┌─────┐
│ b   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
├╌╌╌╌╌┤
│ 2   │
├╌╌╌╌╌┤
│ 3   │
├╌╌╌╌╌┤
│ 4   │
├╌╌╌╌╌┤
│ 5   │
└─────┘

With keep_name:

df.select(pl.col('a').alias('b').keep_name())

shape: (5, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
├╌╌╌╌╌┤
│ 2   │
├╌╌╌╌╌┤
│ 3   │
├╌╌╌╌╌┤
│ 4   │
├╌╌╌╌╌┤
│ 5   │
└─────┘

However, it's not the greatest example.

[ritchie46]

See: #3773 (comment)