docs(python): Provide additional explanation and examples for the value_counts "normalize" parameter (pola-rs#22756)

Author: alexander-beedie

py-polars/polars/expr/expr.py

@@ -9975,81 +9975,97 @@ def value_counts(
         normalize: bool = False,
     ) -> Expr:
         """
-        Count the occurrences of unique values.
+        Count the occurrence of unique values.
 
         Parameters
         ----------
         sort
-            Sort the output by count in descending order.
-            If set to `False` (default), the order of the output is random.
+            Sort the output by count, in descending order.
+            If set to `False` (default), the order is non-deterministic.
         parallel
             Execute the computation in parallel.
 
             .. note::
-                This option should likely not be enabled in a group by context,
-                as the computation is already parallelized per group.
+                This option should likely *not* be enabled in a `group_by` context,
+                as the computation will already be parallelized per group.
         name
-            Give the resulting count column a specific name;
-            if `normalize` is True defaults to "proportion",
-            otherwise defaults to "count".
+            Give the resulting count column a specific name; if `normalize` is
+            True this defaults to "proportion", otherwise defaults to "count".
         normalize
-            If true gives relative frequencies of the unique values
+            If True, the count is returned as the relative frequency of unique
+            values normalized to 1.0.
 
         Returns
         -------
         Expr
-            Expression of data type :class:`Struct` with mapping of unique values to
-            their count.
+            Expression of type :class:`Struct`, mapping unique values to their
+            count (or proportion).
 
         Examples
         --------
         >>> df = pl.DataFrame(
         ...     {"color": ["red", "blue", "red", "green", "blue", "blue"]}
         ... )
-        >>> df.select(pl.col("color").value_counts())  # doctest: +IGNORE_RESULT
+        >>> df_count = df.select(pl.col("color").value_counts())
+        >>> df_count  # doctest: +IGNORE_RESULT
         shape: (3, 1)
         ┌─────────────┐
         │ color       │
         │ ---         │
         │ struct[2]   │
         ╞═════════════╡
-        │ {"red",2}   │
         │ {"green",1} │
         │ {"blue",3}  │
+        │ {"red",2}   │
         └─────────────┘
 
-        Sort the output by (descending) count and customize the count field name.
+        >>> df_count.unnest("color")  # doctest: +IGNORE_RESULT
+        shape: (3, 2)
+        ┌───────┬───────┐
+        │ color ┆ count │
+        │ ---   ┆ ---   │
+        │ str   ┆ u32   │
+        ╞═══════╪═══════╡
+        │ green ┆ 1     │
+        │ blue  ┆ 3     │
+        │ red   ┆ 2     │
+        └───────┴───────┘
 
-        >>> df = df.select(pl.col("color").value_counts(sort=True, name="n"))
-        >>> df
-        shape: (3, 1)
-        ┌─────────────┐
-        │ color       │
-        │ ---         │
-        │ struct[2]   │
-        ╞═════════════╡
-        │ {"blue",3}  │
-        │ {"red",2}   │
-        │ {"green",1} │
-        └─────────────┘
+        Sort the output by (descending) count, customize the field name,
+        and normalize the count to its relative proportion (of 1.0).
 
-        >>> df.unnest("color")
+        >>> df_count = df.select(
+        ...     pl.col("color").value_counts(
+        ...         name="fraction",
+        ...         normalize=True,
+        ...         sort=True,
+        ...     )
+        ... )
+        >>> df_count
+        shape: (3, 1)
+        ┌────────────────────┐
+        │ color              │
+        │ ---                │
+        │ struct[2]          │
+        ╞════════════════════╡
+        │ {"blue",0.5}       │
+        │ {"red",0.333333}   │
+        │ {"green",0.166667} │
+        └────────────────────┘
+
+        >>> df_count.unnest("color")
         shape: (3, 2)
-        ┌───────┬─────┐
-        │ color ┆ n   │
-        │ ---   ┆ --- │
-        │ str   ┆ u32 │
-        ╞═══════╪═════╡
-        │ blue  ┆ 3   │
-        │ red   ┆ 2   │
-        │ green ┆ 1   │
-        └───────┴─────┘
-        """
-        if name is None:
-            if normalize:
-                name = "proportion"
-            else:
-                name = "count"
+        ┌───────┬──────────┐
+        │ color ┆ fraction │
+        │ ---   ┆ ---      │
+        │ str   ┆ f64      │
+        ╞═══════╪══════════╡
+        │ blue  ┆ 0.5      │
+        │ red   ┆ 0.333333 │
+        │ green ┆ 0.166667 │
+        └───────┴──────────┘
+        """
+        name = name or ("proportion" if normalize else "count")
         return self._from_pyexpr(
             self._pyexpr.value_counts(sort, parallel, name, normalize)
         )

py-polars/polars/series/series.py

@@ -2614,25 +2614,25 @@ def value_counts(
         Parameters
         ----------
         sort
-            Sort the output by count in descending order.
-            If set to `False` (default), the order of the output is random.
+            Sort the output by count, in descending order.
+            If set to `False` (default), the order is non-deterministic.
         parallel
             Execute the computation in parallel.
 
             .. note::
-                This option should likely not be enabled in a group by context,
-                as the computation is already parallelized per group.
+                This option should likely *not* be enabled in a `group_by` context,
+                as the computation will already be parallelized per group.
         name
-            Give the resulting count column a specific name;
-            if `normalize` is True defaults to "proportion",
-            otherwise defaults to "count".
+            Give the resulting count column a specific name; if `normalize` is
+            True this defaults to "proportion", otherwise defaults to "count".
         normalize
-            If true gives relative frequencies of the unique values
+            If True, the count is returned as the relative frequency of unique
+            values normalized to 1.0.
 
         Returns
         -------
         DataFrame
-            Mapping of unique values to their count.
+            Columns map the unique values to their count (or proportion).
 
         Examples
         --------
@@ -2662,12 +2662,21 @@ def value_counts(
         │ red   ┆ 2   │
         │ green ┆ 1   │
         └───────┴─────┘
-        """
-        if name is None:
-            if normalize:
-                name = "proportion"
-            else:
-                name = "count"
+
+        Return the count as a relative frequency, normalized to 1.0:
+        >>> s.value_counts(sort=True, normalize=True, name="fraction")
+        shape: (3, 2)
+        ┌───────┬──────────┐
+        │ color ┆ fraction │
+        │ ---   ┆ ---      │
+        │ str   ┆ f64      │
+        ╞═══════╪══════════╡
+        │ blue  ┆ 0.5      │
+        │ red   ┆ 0.333333 │
+        │ green ┆ 0.166667 │
+        └───────┴──────────┘
+        """
+        name = name or ("proportion" if normalize else "count")
         return pl.DataFrame._from_pydf(
             self._s.value_counts(
                 sort=sort, parallel=parallel, name=name, normalize=normalize