Allow add_categories() to accept Series/np.array and make raising on duplicates optional, fixes #9927

Author: mortada

doc/source/whatsnew/v0.16.1.txt

@@ -55,6 +55,7 @@ Enhancements
 - Allow Panel.shift with ``axis='items'`` (:issue:`9890`)
 
 - Trying to write an excel file now raises ``NotImplementedError`` if the ``DataFrame`` has a ``MultiIndex`` instead of writing a broken Excel file. (:issue:`9794`)
+- Allow ``Categorical.add_categories`` to accept `Series` or `np.array`, and add optional keyword ``raise_on_duplicates``. (:issue:`9927`)
 
 .. _whatsnew_0161.api:
 

pandas/core/categorical.py

@@ -650,7 +650,7 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
             raise ValueError("items in new_categories are not the same as in old categories")
         return self.set_categories(new_categories, ordered=ordered, inplace=inplace)
 
-    def add_categories(self, new_categories, inplace=False):
+    def add_categories(self, new_categories, inplace=False, raise_on_duplicates=True):
         """ Add new categories.
 
         `new_categories` will be included at the last/highest place in the categories and will be
@@ -668,6 +668,8 @@ def add_categories(self, new_categories, inplace=False):
         inplace : boolean (default: False)
            Whether or not to add the categories inplace or return a copy of this categorical
            with added categories.
+        raise_on_duplicates : bool
+           Whether to raise an error if new categories overlap with existing categories
 
         Returns
         -------
@@ -684,10 +686,12 @@ def add_categories(self, new_categories, inplace=False):
         if not is_list_like(new_categories):
             new_categories = [new_categories]
         already_included = set(new_categories) & set(self._categories)
-        if len(already_included) != 0:
+
+        if raise_on_duplicates and len(already_included) != 0:
             msg = "new categories must not include old categories: %s" % str(already_included)
             raise ValueError(msg)
-        new_categories = list(self._categories) + (new_categories)
+
+        new_categories = list(self._categories) + list(set(new_categories) - already_included)
         new_categories = self._validate_categories(new_categories)
         cat = self if inplace else self.copy()
         cat._categories = new_categories

pandas/tests/test_categorical.py

@@ -727,6 +727,19 @@ def f():
             cat.add_categories(["d"])
         self.assertRaises(ValueError, f)
 
+        # GH 9927
+        # with raise_on_duplicates=False
+        cat = Categorical(list("abc"), ordered=True)
+        res = cat.add_categories(list("cd"), raise_on_duplicates=False)
+        expected = Categorical(list("abc"), categories=list("abcd"), ordered=True)
+        self.assert_categorical_equal(res, expected)
+
+        # with Series or np.array
+        res = cat.add_categories(Series(["c", "d"]), raise_on_duplicates=False)
+        self.assert_categorical_equal(res, expected)
+        res = cat.add_categories(np.array(["c", "d"]), raise_on_duplicates=False)
+        self.assert_categorical_equal(res, expected)
+
     def test_remove_categories(self):
         cat = Categorical(["a","b","c","a"], ordered=True)
         old = cat.copy()