DEPR or DOCS: pd.value_counts() is public, but not documented. Deprecate or document?

[Dr-Irv]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

import pandas as pd
pd.value_counts([1,2,3,2,1])

Issue Description

pd.value_counts() works, but it does not appear in the documentation.

Two possibilities:

1. It should not be exported and is not intended to be available.
2. It should be exported, and needs documentation by modifying pandas/doc/source/reference/general_functions.rst

Uncovered when cleaning up pandas-stubs: pandas-dev/pandas-stubs#170 (comment)

Expected Behavior

Unclear!

Installed Versions

pandas 1.4.3 and associated docs

[mroeschke]

It appears in the user guide and v0.20 whatsnew

https://pandas.pydata.org/pandas-docs/dev/user_guide/basics.html#value-counts-histogramming-mode
https://pandas.pydata.org/pandas-docs/dev/whatsnew/v0.20.0.html#uint64-support-improved

But IMO +1 to deprecating this as redundant with the Series/DataFrame method which is way more publicized instead.

[simonjayhawkins]

It appears in the user guide and v0.20 whatsnew

https://pandas.pydata.org/pandas-docs/dev/user_guide/basics.html#value-counts-histogramming-mode https://pandas.pydata.org/pandas-docs/dev/whatsnew/v0.20.0.html#uint64-support-improved

looks like added in #1392, so been around since 0.8.0

But IMO +1 to deprecating this as redundant with the Series/DataFrame method which is way more publicized instead.

from #46749 (comment)

As the function only accepts 1d numpy arrays and not any pandas object then I would also be inclined to remove this for the public api in a future pandas version.

Looking some more the accepted types are documented (in the docstring) incorrectly, as the code also explicitly handles EAs and the values = Series(values) means that the top-level method also works with any array-like accepted by the Series constructor. (or types accepted the internal _ensure_arraylike function - not currently typed.)

Issue Description

pd.value_counts() works, but it does not appear in the documentation.

Two possibilities:

1. It should not be exported and is not intended to be available.
2. It should be exported, and needs documentation by modifying pandas/doc/source/reference/general_functions.rst

Uncovered when cleaning up pandas-stubs: pandas-dev/pandas-stubs#170 (comment)

Expected Behavior

Unclear!

For now, it was definitely intended to be public and is a long-standing feature (for passing to functions that accept a callable), so should really be documented.

So to answer the question in the title, BUG or DOCS, then not a bug. So maybe best to rename issue and remove the BUG label.

could maybe instead make this issue a discussion on deprecation or just label as a DOC issue.

[jreback]

i thought we depreciated and removed this quite a while ago

definitely should be depreciated if it still exists

[simonjayhawkins]

i thought we depreciated and removed this quite a while ago

I didn't find any open issues about this on a quick search.

definitely should be depreciated if it still exists

sure, but since I didn't find anything to reference, can you perhaps give a reason here.

[jreback]

#13790

we don't expose any other functions like this at top level

+1 to deprecate

[simonjayhawkins]

OK will milestone 1.5 since I will assume for now that we will deprecate this, and if we don't get any objections, we don't need to update the docs. Also for typing, can be removed from top-level api.

any analogy with pandas.unique? Is this useful as a top-level function or do the same arguments apply?