DOC: Improve sort parameter doc of DataFrameGroupBy.value_counts

[KevsterAmp]

• closes BUG: GroupBy.value_counts doesn't preserve original order for non-grouping rows #59307 (Replace xxxx with the GitHub issue number)
• Tests added and passed if fixing a bug or adding a new feature
• All code checks passed.
• Added type annotations to new arguments/methods/functions.
• 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.

[KevsterAmp]

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

[KevsterAmp]

Fixed it

[rhshadrach]

Thanks for the PR!

[rhshadrach]

I think we also want to modify the docstring on SeriesGroupBy.value_counts. Can you make the same adjustment there.

[KevsterAmp]

Sure thing

[KevsterAmp]

@rhshadrach - are there any extra changes needed for this PR? Thanks

[sfc-gh-joshi]

@KevsterAmp I left an additional ? on the parent issue: #59307 (comment)

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.

[KevsterAmp]

Fixed the doc, thanks.

[KevsterAmp]

@KevsterAmp I left an additional ? on the parent issue: #59307 (comment)

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

[KevsterAmp]

@rhshadrach - are there any extra changes needed for this PR? Thanks

[rhshadrach]

@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 #59307 (comment)

[rhshadrach]

@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!