DOC: Improve sort parameter doc of DataFrameGroupBy.value_counts
State: closed

- [x] closes #59307 (Replace xxxx with the GitHub issue number)
- [x] [Tests added and passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#writing-tests) if fixing a bug or adding a new feature
- [x] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).
- [x] Added [type annotations](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#type-hints) to new arguments/methods/functions.
- [x] Added an entry in the latest `doc/source/whatsnew/vX.X.X.rst` file if fixing a bug or adding a new feature.


I just copied the sort docstring of `Dataframe.value_counts` since the latter is mirrored to behaved like it.

![image](https://github.com/user-attachments/assets/26ad12af-e69e-40c1-97e8-c75708af16b8)



Labels:
name: Docs
name: Groupby
name: Algos
description: Non-arithmetic algos: value_counts, factorize, sorting, isin, clip, shift, diff

Comments:
Seems like I have changed the wrong `value_count()` function. I have changed `pandas.core.groupby.SeriesGroupBy.value_counts` rather than `pandas.core.groupby.DataFrameGroupBy.value_counts`. Applying fix in a bit
Fixed it
![image](https://github.com/user-attachments/assets/502946c1-c8b1-4d4b-8679-d7bebc628ee1)

@rhshadrach - are there any extra changes needed for this PR? Thanks
@KevsterAmp I left an additional ? on the parent issue: https://github.com/pandas-dev/pandas/issues/59307#issuecomment-2271819631

It seems like when the groupby's sort flag and value_counts sort flag are both false, no sorting is done. Is this a behavioral bug, or just something else to add to documentation?

**edit:** It seems also that when `value_counts` has sort=True, the result frame is still being sorted on the DataFrame column values:
```
>>> data0 = {
    "by": ["c", "b", "a", "a", "b", "b", "c", "a"],
    "value1": ["ee", "aa", "bb", "aa", "bb", "cc", "dd", "aa"],
    "value2": [1, 2, 3, 1, 1, 3, 2, 1],
}
>>> pd.DataFrame(data0).groupby(by=["by"]).value_counts(sort=True)
by  value1  value2
a   aa      1         2
    bb      3         1
b   aa      2         1
    bb      1         1
    cc      3         1
c   dd      2         1
    ee      1         1
```
In the input frame, the row `c ee 1` (which appears once) appears before `c dd 1` (also appearing once), but the result ends up being sorted on `value1` as well as the counts. I think it's worth clarifying whether `value_counts(sort=True)` will also sort on the DataFrame's values, or if it's just that the algorithm used to sort the counts column is unstable.
Fixed the doc, thanks. 

![image](https://github.com/user-attachments/assets/fd1dfe1a-f0ea-4555-9db4-bb080a746a7f)

> @KevsterAmp I left an additional ? on the parent issue: [#59307 (comment)](https://github.com/pandas-dev/pandas/issues/59307#issuecomment-2271819631)
> 
> It seems like when the groupby's sort flag and value_counts sort flag are both false, no sorting is done. Is this a behavioral bug, or just something else to add to documentation?
> 
> **edit:** It seems also that when `value_counts` has sort=True, the result frame is still being sorted on the DataFrame column values:
> 
> ```
> >>> data0 = {
>     "by": ["c", "b", "a", "a", "b", "b", "c", "a"],
>     "value1": ["ee", "aa", "bb", "aa", "bb", "cc", "dd", "aa"],
>     "value2": [1, 2, 3, 1, 1, 3, 2, 1],
> }
> >>> pd.DataFrame(data0).groupby(by=["by"]).value_counts(sort=True)
> by  value1  value2
> a   aa      1         2
>     bb      3         1
> b   aa      2         1
>     bb      1         1
>     cc      3         1
> c   dd      2         1
>     ee      1         1
> ```
> 
> In the input frame, the row `c ee 1` (which appears once) appears before `c dd 1` (also appearing once), but the result ends up being sorted on `value1` as well as the counts. I think it's worth clarifying whether `value_counts(sort=True)` will also sort on the DataFrame's values, or if it's just that the algorithm used to sort the counts column is unstable.

Not sure if I will address this in this PR, since the scope of this one is to just modify the doc. Thanks
@rhshadrach - are there any extra changes needed for this PR? Thanks
@KevsterAmp - I am hesitant to make this change since certain cases that are correct now become incorrect. When you do `df.groupby(..., sort=False).value_counts(sort=False)`, pandas is preserving the order of the input. See https://github.com/pandas-dev/pandas/issues/59307#issuecomment-2271819631
@KevsterAmp - I've opened #59307 based on the discussion in the linked issue. Unfortunately that supersedes this PR. Going to close here - but thanks for working on this!