API: various .value_counts() result in different names / indices

doc/source/whatsnew/v2.0.0.rst

@@ -207,6 +207,44 @@ a supported dtype:
 
    pd.Series(["2016-01-01"], dtype="datetime64[D]")
 
+.. _whatsnew_200.api_breaking.value_counts:
+
+Value counts behaviour change
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In past versions, when running :meth:`Series.value_counts`, the result would inherit
+the original object's name, and the result index would be nameless. This would cause
+confusion when resetting the index, and the column names would not correspond with the
+column values.
+Now, the result name will be ``'count'`` (or ``'proportion'`` if ``normalize=True`` was passed),
+and the index will be named after the original object.
+
+*Previous behavior*:
+
+.. code-block:: ipython
+
+    In [8]: (
+       ...:     pd.Series(['quetzal', 'quetzal', 'elk'], name='animal')
+       ...:     .value_counts()
+       ...:     .reset_index()
+       ...: )
+       ...:
+    Out[8]:
+         index  animal
+    0  quetzal       2
+    1      elk       1
+
+*New behavior*:
+
+.. ipython:: python
+
+    (
+        pd.Series(['quetzal', 'quetzal', 'elk'], name='animal')
+        .value_counts()
+        .reset_index()
+    )
+
+Likewise for other ``value_counts`` methods (for example, :meth:`DataFrame.value_counts`).
+
 .. _whatsnew_200.api_breaking.astype_to_unsupported_datetimelike:
 
 Disallow astype conversion to non-supported datetime64/timedelta64 dtypes

pandas/core/algorithms.py

@@ -842,7 +842,8 @@ def value_counts(
         Series,
     )
 
-    name = getattr(values, "name", None)
+    index_name = getattr(values, "name", None)
+    name = "proportion" if normalize else "count"
 
     if bins is not None:
         from pandas.core.reshape.tile import cut
@@ -854,7 +855,7 @@ def value_counts(
             raise TypeError("bins argument only works with numeric data.") from err
 
         # count, remove nulls (from the index), and but the bins
-        result = ii.value_counts(dropna=dropna)
+        result = ii.value_counts(dropna=dropna).rename(name)
         result = result[result.index.notna()]
         result.index = result.index.astype("interval")
         result = result.sort_index()
@@ -871,16 +872,20 @@ def value_counts(
         if is_extension_array_dtype(values):
 
             # handle Categorical and sparse,
-            result = Series(values)._values.value_counts(dropna=dropna)
-            result.name = name
+            result = Series(values)._values.value_counts(dropna=dropna).rename(name)
+            result.index.name = index_name
             counts = result._values
 
         elif isinstance(values, ABCMultiIndex):
             # GH49558
             levels = list(range(values.nlevels))
-            result = Series(index=values).groupby(level=levels, dropna=dropna).size()
+            result = (
+                Series(index=values, name=name)
+                .groupby(level=levels, dropna=dropna)
+                .size()
+            )
             # TODO: allow index names to remain (see discussion in GH49497)
-            result.index.names = [None] * values.nlevels
+            result.index.names = values.names
             counts = result._values
 
         else:
@@ -892,6 +897,7 @@ def value_counts(
             idx = Index._with_infer(keys)
             if idx.dtype == bool and keys.dtype == object:
                 idx = idx.astype(object)
+            idx.name = index_name
 
             result = Series(counts, index=idx, name=name)
 

pandas/core/arrays/arrow/array.py

@@ -795,7 +795,7 @@ def value_counts(self, dropna: bool = True) -> Series:
 
         index = Index(type(self)(values))
 
-        return Series(counts, index=index).astype("Int64")
+        return Series(counts, index=index, name="count").astype("Int64")
 
     @classmethod
     def _concat_same_type(

pandas/core/arrays/categorical.py

@@ -1508,7 +1508,7 @@ def value_counts(self, dropna: bool = True) -> Series:
         ix = coerce_indexer_dtype(ix, self.dtype.categories)
         ix = self._from_backing_data(ix)
 
-        return Series(count, index=CategoricalIndex(ix), dtype="int64")
+        return Series(count, index=CategoricalIndex(ix), dtype="int64", name="count")
 
     # error: Argument 2 of "_empty" is incompatible with supertype
     # "NDArrayBackedExtensionArray"; supertype defines the argument type as

pandas/core/arrays/masked.py

@@ -974,7 +974,7 @@ def value_counts(self, dropna: bool = True) -> Series:
         )
 
         if dropna:
-            res = Series(value_counts, index=keys)
+            res = Series(value_counts, index=keys, name="count")
             res.index = res.index.astype(self.dtype)
             res = res.astype("Int64")
             return res
@@ -990,7 +990,7 @@ def value_counts(self, dropna: bool = True) -> Series:
         mask = np.zeros(len(counts), dtype="bool")
         counts_array = IntegerArray(counts, mask)
 
-        return Series(counts_array, index=index)
+        return Series(counts_array, index=index, name="count")
 
     @doc(ExtensionArray.equals)
     def equals(self, other) -> bool:

pandas/core/base.py

@@ -948,7 +948,7 @@ def value_counts(
         1.0    1
         2.0    1
         4.0    1
-        dtype: int64
+        Name: count, dtype: int64
 
         With `normalize` set to `True`, returns the relative frequency by
         dividing all values by the sum of values.
@@ -959,7 +959,7 @@ def value_counts(
         1.0    0.2
         2.0    0.2
         4.0    0.2
-        dtype: float64
+        Name: proportion, dtype: float64
 
         **bins**
 
@@ -972,7 +972,7 @@ def value_counts(
         (0.996, 2.0]    2
         (2.0, 3.0]      2
         (3.0, 4.0]      1
-        dtype: int64
+        Name: count, dtype: int64
 
         **dropna**
 
@@ -984,7 +984,7 @@ def value_counts(
         2.0    1
         4.0    1
         NaN    1
-        dtype: int64
+        Name: count, dtype: int64
         """
         return algorithms.value_counts(
             self,

pandas/core/frame.py

@@ -7056,28 +7056,28 @@ def value_counts(
         4         0            2
         2         2            1
         6         0            1
-        dtype: int64
+        Name: count, dtype: int64
 
         >>> df.value_counts(sort=False)
         num_legs  num_wings
         2         2            1
         4         0            2
         6         0            1
-        dtype: int64
+        Name: count, dtype: int64
 
         >>> df.value_counts(ascending=True)
         num_legs  num_wings
         2         2            1
         6         0            1
         4         0            2
-        dtype: int64
+        Name: count, dtype: int64
 
         >>> df.value_counts(normalize=True)
         num_legs  num_wings
         4         0            0.50
         2         2            0.25
         6         0            0.25
-        dtype: float64
+        Name: proportion, dtype: float64
 
         With `dropna` set to `False` we can also count rows with NA values.
 
@@ -7094,20 +7094,21 @@ def value_counts(
         first_name  middle_name
         Beth        Louise         1
         John        Smith          1
-        dtype: int64
+        Name: count, dtype: int64
 
         >>> df.value_counts(dropna=False)
         first_name  middle_name
         Anne        NaN            1
         Beth        Louise         1
         John        Smith          1
                     NaN            1
-        dtype: int64
+        Name: count, dtype: int64
         """
         if subset is None:
             subset = self.columns.tolist()
 
-        counts = self.groupby(subset, dropna=dropna).grouper.size()
+        name = "proportion" if normalize else "count"
+        counts = self.groupby(subset, dropna=dropna).grouper.size().rename(name)
 
         if sort:
             counts = counts.sort_values(ascending=ascending)

pandas/core/groupby/generic.py

@@ -611,7 +611,8 @@ def value_counts(
         ids, _, _ = self.grouper.group_info
         val = self.obj._values
 
-        names = self.grouper.names + [self.obj.name]
+        index_names = self.grouper.names + [self.obj.name]
+        name = "proportion" if normalize else "count"
 
         if is_categorical_dtype(val.dtype) or (
             bins is not None and not np.iterable(bins)
@@ -625,8 +626,8 @@ def value_counts(
                 sort=sort,
                 ascending=ascending,
                 bins=bins,
-            )
-            ser.index.names = names
+            ).rename(name)
+            ser.index.names = index_names
             return ser
 
         # groupby removes null keys from groupings
@@ -736,11 +737,13 @@ def build_codes(lev_codes: np.ndarray) -> np.ndarray:
             codes = [build_codes(lev_codes) for lev_codes in codes[:-1]]
             codes.append(left[-1])
 
-        mi = MultiIndex(levels=levels, codes=codes, names=names, verify_integrity=False)
+        mi = MultiIndex(
+            levels=levels, codes=codes, names=index_names, verify_integrity=False
+        )
 
         if is_integer_dtype(out.dtype):
             out = ensure_int64(out)
-        return self.obj._constructor(out, index=mi, name=self.obj.name)
+        return self.obj._constructor(out, index=mi, name=name)
 
     def fillna(
         self,
@@ -1920,7 +1923,7 @@ def value_counts(
         male    low        FR         2
                            US         1
                 medium     FR         1
-        dtype: int64
+        Name: count, dtype: int64
 
         >>> df.groupby('gender').value_counts(ascending=True)
         gender  education  country
@@ -1929,7 +1932,7 @@ def value_counts(
         male    low        US         1
                 medium     FR         1
                 low        FR         2
-        dtype: int64
+        Name: count, dtype: int64
 
         >>> df.groupby('gender').value_counts(normalize=True)
         gender  education  country
@@ -1938,7 +1941,7 @@ def value_counts(
         male    low        FR         0.50
                            US         0.25
                 medium     FR         0.25
-        dtype: float64
+        Name: proportion, dtype: float64
 
         >>> df.groupby('gender', as_index=False).value_counts()
            gender education country  count
@@ -1960,6 +1963,7 @@ def value_counts(
             raise NotImplementedError(
                 "DataFrameGroupBy.value_counts only handles axis=0"
             )
+        name = "proportion" if normalize else "count"
 
         with self._group_selection_context():
             df = self.obj
@@ -1968,8 +1972,8 @@ def value_counts(
                 grouping.name for grouping in self.grouper.groupings if grouping.in_axis
             }
             if isinstance(self._selected_obj, Series):
-                name = self._selected_obj.name
-                keys = [] if name in in_axis_names else [self._selected_obj]
+                _name = self._selected_obj.name
+                keys = [] if _name in in_axis_names else [self._selected_obj]
             else:
                 unique_cols = set(self._selected_obj.columns)
                 if subset is not None:
@@ -1992,8 +1996,8 @@ def value_counts(
                 keys = [
                     # Can't use .values because the column label needs to be preserved
                     self._selected_obj.iloc[:, idx]
-                    for idx, name in enumerate(self._selected_obj.columns)
-                    if name not in in_axis_names and name in subsetted
+                    for idx, _name in enumerate(self._selected_obj.columns)
+                    if _name not in in_axis_names and _name in subsetted
                 ]
 
             groupings = list(self.grouper.groupings)
@@ -2015,7 +2019,7 @@ def value_counts(
                 observed=self.observed,
                 dropna=self.dropna,
             )
-            result_series = cast(Series, gb.size())
+            result_series = cast(Series, gb.size()).rename(name)
 
             # GH-46357 Include non-observed categories
             # of non-grouping columns regardless of `observed`
@@ -2059,14 +2063,12 @@ def value_counts(
                 result = result_series
             else:
                 # Convert to frame
-                name = "proportion" if normalize else "count"
                 index = result_series.index
                 columns = com.fill_missing_names(index.names)
                 if name in columns:
                     raise ValueError(
                         f"Column label '{name}' is duplicate of result column"
                     )
-                result_series.name = name
                 result_series.index = index.set_names(range(len(columns)))
                 result_frame = result_series.reset_index()
                 result_frame.columns = columns + [name]

pandas/tests/arrays/boolean/test_function.py

@@ -92,20 +92,20 @@ def test_ufunc_reduce_raises(values):
 def test_value_counts_na():
     arr = pd.array([True, False, pd.NA], dtype="boolean")
     result = arr.value_counts(dropna=False)
-    expected = pd.Series([1, 1, 1], index=arr, dtype="Int64")
+    expected = pd.Series([1, 1, 1], index=arr, dtype="Int64", name="count")
     assert expected.index.dtype == arr.dtype
     tm.assert_series_equal(result, expected)
 
     result = arr.value_counts(dropna=True)
-    expected = pd.Series([1, 1], index=arr[:-1], dtype="Int64")
+    expected = pd.Series([1, 1], index=arr[:-1], dtype="Int64", name="count")
     assert expected.index.dtype == arr.dtype
     tm.assert_series_equal(result, expected)
 
 
 def test_value_counts_with_normalize():
     ser = pd.Series([True, False, pd.NA], dtype="boolean")
     result = ser.value_counts(normalize=True)
-    expected = pd.Series([1, 1], index=ser[:-1], dtype="Float64") / 2
+    expected = pd.Series([1, 1], index=ser[:-1], dtype="Float64", name="proportion") / 2
     assert expected.index.dtype == "boolean"
     tm.assert_series_equal(result, expected)
 

pandas/tests/arrays/floating/test_function.py

@@ -100,11 +100,11 @@ def test_value_counts_na():
     result = arr.value_counts(dropna=False)
     idx = pd.Index([0.1, 0.2, pd.NA], dtype=arr.dtype)
     assert idx.dtype == arr.dtype
-    expected = pd.Series([2, 1, 1], index=idx, dtype="Int64")
+    expected = pd.Series([2, 1, 1], index=idx, dtype="Int64", name="count")
     tm.assert_series_equal(result, expected)
 
     result = arr.value_counts(dropna=True)
-    expected = pd.Series([2, 1], index=idx[:-1], dtype="Int64")
+    expected = pd.Series([2, 1], index=idx[:-1], dtype="Int64", name="count")
     tm.assert_series_equal(result, expected)
 
 
@@ -113,14 +113,14 @@ def test_value_counts_empty():
     result = ser.value_counts()
     idx = pd.Index([], dtype="Float64")
     assert idx.dtype == "Float64"
-    expected = pd.Series([], index=idx, dtype="Int64")
+    expected = pd.Series([], index=idx, dtype="Int64", name="count")
     tm.assert_series_equal(result, expected)
 
 
 def test_value_counts_with_normalize():
     ser = pd.Series([0.1, 0.2, 0.1, pd.NA], dtype="Float64")
     result = ser.value_counts(normalize=True)
-    expected = pd.Series([2, 1], index=ser[:2], dtype="Float64") / 3
+    expected = pd.Series([2, 1], index=ser[:2], dtype="Float64", name="proportion") / 3
     assert expected.index.dtype == ser.dtype
     tm.assert_series_equal(result, expected)