deprecate Categorical.map(na_action=ignore)

Author: topper-123

doc/source/whatsnew/v2.1.0.rst

@@ -28,7 +28,9 @@ enhancement2
 
 Other enhancements
 ^^^^^^^^^^^^^^^^^^
-- :meth:`Categorical.map` and :meth:`CategoricalIndex.map` now have a ``na_action`` parameter (:issue:`44279`)
+- :meth:`Categorical.map` and :meth:`CategoricalIndex.map` now have a ``na_action`` parameter.
+  :meth:`Categorical.map` implicitly had a default value of ``"ignore"`` for ``na_action``. This has formally been deprecated and will be changed to ``None`` in the future.
+  Also notice that :meth:`Series.map` has default ``na_action=None`` and calls to series with categorical data will now use ``na_action=None`` unless explicitly set otherwise (:issue:`44279`)
 - Implemented ``__pandas_priority__`` to allow custom types to take precedence over :class:`DataFrame`, :class:`Series`, :class:`Index`, or :class:`ExtensionArray` for arithmetic operations, :ref:`see the developer guide <extending.pandas_priority>` (:issue:`48347`)
 - :meth:`MultiIndex.sort_values` now supports ``na_position`` (:issue:`51612`)
 - :meth:`MultiIndex.sortlevel` and :meth:`Index.sortlevel` gained a new keyword ``na_position`` (:issue:`51612`)

pandas/core/apply.py

@@ -39,6 +39,7 @@
 
 from pandas.core.dtypes.cast import is_nested_object
 from pandas.core.dtypes.common import (
+    is_categorical_dtype,
     is_dict_like,
     is_extension_array_dtype,
     is_list_like,
@@ -1086,7 +1087,11 @@ def apply_standard(self) -> DataFrame | Series:
                 return f(obj)
 
         # row-wise access
-        mapped = obj._map_values(mapper=f, convert=self.convert_dtype)
+        # apply doesn't have a `na_action` keyword and for backward compat reasons
+        # we need to give `na_action="ignore"` for categorical data.
+        # TODO: remove the `na_action="ignore"` has been removed from Categorical.
+        action = "ignore" if is_categorical_dtype(obj) else None
+        mapped = obj._map_values(mapper=f, na_action=action, convert=self.convert_dtype)
 
         if len(mapped) and isinstance(mapped[0], ABCSeries):
             # GH#43986 Need to do list(mapped) in order to get treated as nested

pandas/core/arrays/categorical.py

@@ -13,6 +13,7 @@
     cast,
     overload,
 )
+from warnings import warn
 
 import numpy as np
 
@@ -25,6 +26,7 @@
 )
 from pandas._libs.arrays import NDArrayBacked
 from pandas.compat.numpy import function as nv
+from pandas.util._exceptions import find_stack_level
 from pandas.util._validators import validate_bool_kwarg
 
 from pandas.core.dtypes.cast import (
@@ -1196,7 +1198,11 @@ def remove_unused_categories(self) -> Categorical:
 
     # ------------------------------------------------------------------
 
-    def map(self, mapper, na_action: Literal["ignore"] | None = "ignore"):
+    def map(
+        self,
+        mapper,
+        na_action: Literal["ignore"] | None | lib.NoDefault = lib.no_default,
+    ):
         """
         Map categories using an input mapping or function.
 
@@ -1217,6 +1223,11 @@ def map(self, mapper, na_action: Literal["ignore"] | None = "ignore"):
             If 'ignore', propagate NaN values, without passing them to the
             mapping correspondence.
 
+            .. deprecated:: 2.1.0
+
+               The dault value of 'ignore' has been deprecated and will be changed to
+               None in the future.
+
         Returns
         -------
         pandas.Categorical or pandas.Index
@@ -1268,6 +1279,17 @@ def map(self, mapper, na_action: Literal["ignore"] | None = "ignore"):
         >>> cat.map({'a': 'first', 'b': 'second'})
         Index(['first', 'second', nan], dtype='object')
         """
+        if na_action is lib.no_default:
+            warn(
+                "The default value of 'ignore' for the `na_action` parameter in "
+                "pandas.Categorical.map is deprecated and will be "
+                "changed to 'None' in a future version. Please set na_action to the "
+                "desired value to avoid seeing this warning",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            na_action = "ignore"
+
         assert callable(mapper) or is_dict_like(mapper)
 
         new_categories = self.categories.map(mapper)

pandas/tests/arrays/categorical/test_analytics.py

@@ -300,16 +300,16 @@ def test_memory_usage(self):
 
     def test_map(self):
         c = Categorical(list("ABABC"), categories=list("CBA"), ordered=True)
-        result = c.map(lambda x: x.lower())
+        result = c.map(lambda x: x.lower(), na_action=None)
         exp = Categorical(list("ababc"), categories=list("cba"), ordered=True)
         tm.assert_categorical_equal(result, exp)
 
         c = Categorical(list("ABABC"), categories=list("ABC"), ordered=False)
-        result = c.map(lambda x: x.lower())
+        result = c.map(lambda x: x.lower(), na_action=None)
         exp = Categorical(list("ababc"), categories=list("abc"), ordered=False)
         tm.assert_categorical_equal(result, exp)
 
-        result = c.map(lambda x: 1)
+        result = c.map(lambda x: 1, na_action=None)
         # GH 12766: Return an index not an array
         tm.assert_index_equal(result, Index(np.array([1] * 5, dtype=np.int64)))
 

pandas/tests/arrays/categorical/test_map.py

@@ -139,3 +139,16 @@ def test_map_with_dict_or_series(na_action):
     result = cat.map(mapper, na_action=na_action)
     # Order of categories in result can be different
     tm.assert_categorical_equal(result, expected)
+
+
+def test_map_na_action_no_default_deprecated():
+    # GH51645
+    cat = Categorical(["a", "b", "c"])
+    msg = (
+        "The default value of 'ignore' for the `na_action` parameter in "
+        "pandas.Categorical.map is deprecated and will be "
+        "changed to 'None' in a future version. Please set na_action to the "
+        "desired value to avoid seeing this warning"
+    )
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        cat.map(lambda x: x)

pandas/tests/arrays/categorical/test_subclass.py

@@ -16,7 +16,7 @@ def test_from_codes(self):
 
     def test_map(self):
         sc = tm.SubclassedCategorical(["a", "b", "c"])
-        res = sc.map(lambda x: x.upper())
+        res = sc.map(lambda x: x.upper(), na_action=None)
         assert isinstance(res, tm.SubclassedCategorical)
         exp = Categorical(["A", "B", "C"])
         tm.assert_categorical_equal(res, exp)