Doc: resolve GL08 for pandas.core.groupby.SeriesGroupBy.value_counts (#57609)

Author: jordan-d-murphy

ci/code_checks.sh

@@ -178,7 +178,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
  pandas.Timestamp.tzinfo\
  pandas.Timestamp.value\
  pandas.Timestamp.year\
- pandas.core.groupby.SeriesGroupBy.value_counts\
  pandas.tseries.offsets.BQuarterBegin.is_anchored\
  pandas.tseries.offsets.BQuarterBegin.is_on_offset\
  pandas.tseries.offsets.BQuarterBegin.n\

pandas/core/groupby/generic.py

@@ -801,6 +801,85 @@ def value_counts(
  bins=None,
  dropna: bool = True,
  ) -> Series | DataFrame:
+ """
+ Return a Series or DataFrame containing counts of unique rows.
+
+ .. versionadded:: 1.4.0
+
+ Parameters
+ ----------
+ normalize : bool, default False
+ Return proportions rather than frequencies.
+ sort : bool, default True
+ Sort by frequencies.
+ ascending : bool, default False
+ Sort in ascending order.
+ bins : int or list of ints, optional
+ Rather than count values, group them into half-open bins,
+ a convenience for pd.cut, only works with numeric data.
+ dropna : bool, default True
+ Don't include counts of rows that contain NA values.
+
+ Returns
+ -------
+ Series or DataFrame
+ Series if the groupby ``as_index`` is True, otherwise DataFrame.
+
+ See Also
+ --------
+ Series.value_counts: Equivalent method on Series.
+ DataFrame.value_counts: Equivalent method on DataFrame.
+ DataFrameGroupBy.value_counts: Equivalent method on DataFrameGroupBy.
+
+ Notes
+ -----
+ - If the groupby ``as_index`` is True then the returned Series will have a
+ MultiIndex with one level per input column.
+ - If the groupby ``as_index`` is False then the returned DataFrame will have an
+ additional column with the value_counts. The column is labelled 'count' or
+ 'proportion', depending on the ``normalize`` parameter.
+
+ By default, rows that contain any NA values are omitted from
+ the result.
+
+ By default, the result will be in descending order so that the
+ first element of each group is the most frequently-occurring row.
+
+ Examples
+ --------
+ >>> s = pd.Series(
+ ... [1, 1, 2, 3, 2, 3, 3, 1, 1, 3, 3, 3],
+ ... index=["A", "A", "A", "A", "A", "A", "B", "B", "B", "B", "B", "B"],
+ ... )
+ >>> s
+ A 1
+ A 1
+ A 2
+ A 3
+ A 2
+ A 3
+ B 3
+ B 1
+ B 1
+ B 3
+ B 3
+ B 3
+ dtype: int64
+ >>> g1 = s.groupby(s.index)
+ >>> g1.value_counts(bins=2)
+ A (0.997, 2.0] 4
+ (2.0, 3.0] 2
+ B (2.0, 3.0] 4
+ (0.997, 2.0] 2
+ Name: count, dtype: int64
+ >>> g1.value_counts(normalize=True)
+ A 1 0.333333
+ 2 0.333333
+ 3 0.333333
+ B 3 0.666667
+ 1 0.333333
+ Name: proportion, dtype: float64
+ """
  name = "proportion" if normalize else "count"
 
  if bins is None:
@@ -2303,7 +2382,7 @@ def value_counts(
  Returns
  -------
  Series or DataFrame
- Series if the groupby as_index is True, otherwise DataFrame.
+ Series if the groupby ``as_index`` is True, otherwise DataFrame.
 
  See Also
  --------
@@ -2313,9 +2392,9 @@ def value_counts(
 
  Notes
  -----
- - If the groupby as_index is True then the returned Series will have a
+ - If the groupby ``as_index`` is True then the returned Series will have a
  MultiIndex with one level per input column.
- - If the groupby as_index is False then the returned DataFrame will have an
+ - If the groupby ``as_index`` is False then the returned DataFrame will have an
  additional column with the value_counts. The column is labelled 'count' or
  'proportion', depending on the ``normalize`` parameter.