feat: Allow designation of a custom name for the value_counts "count" column

[alexander-beedie]

Closes #16425.

While we don't usually (but do sometimes #15222), I think we should allow a "name" parameter here, because otherwise we are making the caller change their column names (in the case of a clash) to account for us forcing one called "count" onto them.

It is more user-friendly to allow our "count" column to be renamed, as there is no way for the caller to do so, and working around it with pre/post aliasing to maintain their original column name is pretty ugly (and verges on painful in the DataFrame case) 🤔

Example

Series

s = pl.Series("count", [20, 20, 60, 50, 50, 50])

With a "name" param:

s.value_counts(sort=True, name="n")
# shape: (3, 2)
# ┌───────┬─────┐
# │ count ┆ n   │
# │ ---   ┆ --- │
# │ i64   ┆ u32 │
# ╞═══════╪═════╡
# │ 50    ┆ 3   │
# │ 20    ┆ 2   │
# │ 60    ┆ 1   │
# └───────┴─────┘

Without a "name" param achieving the same output is... not ergonomic :)

s.alias("temp_count").value_counts(sort=True).alias(
    {"count":"n", "temp_count":"count"}
)
# shape: (3, 2)
# ┌───────┬─────┐
# │ count ┆ n   │
# │ ---   ┆ --- │
# │ i64   ┆ u32 │
# ╞═══════╪═════╡
# │ 50    ┆ 3   │
# │ 20    ┆ 2   │
# │ 60    ┆ 1   │
# └───────┴─────┘

DataFrame

And it's even worse for DataFrame...

df = pl.DataFrame({"count": [20, 20, 60, 50, 50, 50]})

With a "name" param:

df.select(pl.col("count").value_counts(name="n"))
# shape: (3, 1)
# ┌───────────┐
# │ count     │
# │ ---       │
# │ struct[2] │
# ╞═══════════╡
# │ {60,1}    │
# │ {50,3}    │
# │ {20,2}    │
# └───────────┘
df.unnest("count")
# shape: (3, 2)
# ┌───────┬─────┐
# │ count ┆ n   │
# │ ---   ┆ --- │
# │ i64   ┆ u32 │
# ╞═══════╪═════╡
# │ 50    ┆ 3   │
# │ 60    ┆ 1   │
# │ 20    ┆ 2   │
# └───────┴─────┘

Without a "name" param we have to tie ourselves in knots to achieve the same output, first aliasing the target column and then renaming both the resulting struct column and its component fields:

df.select(
    pl.col("count")
    .alias("temp_count")
    .value_counts()
    .struct.rename_fields(["count", "n"])
).rename({"temp_count": "count"})

[stinodego]

Yep, looks good to me. Thanks for picking this up!

[alexander-beedie]

Yep, looks good to me. Thanks for picking this up!

It was an ideal coffee-sized patch; that's my fundamental unit of work these days 😆